Production Ai Agents: The Architecture No Tutorial Shows You

// Anti-pattern: monolithic agent loop
async function badAgent(task) {
 let result = await llm.call(task);
 while (result.hasToolCall) {
 result = await llm.call(executeTool(result) + previousContext);
 }
 return result; // Brittle, no planning, no recovery
}

// Production pattern: planner + executor separated
class ProductionAgent {
 async run(task) {
 // Phase 1: Planner creates explicit plan
 const plan = await this.planner.createPlan({
 task,
 availableTools: this.tools.list(),
 constraints: this.constraints,
 });
 // plan = { steps: [{tool, args, dependsOn, retryPolicy}], estimatedCost }

 // Phase 2: Executor runs plan with oversight
 const executor = new PlanExecutor(plan, this.tools);
 return executor.run({
 onStepComplete: this.monitor.recordStep,
 onError: this.errorHandler.handle,
 maxRetries: 3,
 });
 }
}
// Plan is inspectable BEFORE execution
// Executor retries individual steps without re-planning
// Each phase has its own observability

class AgentMemory {
 // Tier 1: Working memory - current task context (in LLM context)
 working = new Map();

 // Tier 2: Episodic memory - past task results (vector DB)
 episodic = new VectorStore('episodes'); // "What happened when I did X?"

 // Tier 3: Semantic memory - facts and knowledge (vector DB)
 semantic = new VectorStore('knowledge'); // "What do I know about X?"

 async recall(query) {
 const [working, episodic, semantic] = await Promise.all([
 this.searchWorking(query),
 this.episodic.similaritySearch(query, { k: 3, threshold: 0.75 }),
 this.semantic.similaritySearch(query, { k: 5, threshold: 0.70 }),
 ]);
 return this.rankAndMerge([...working, ...episodic, ...semantic]);
 }

 async store(result) {
 await this.episodic.upsert({
 id: result.taskId,
 vector: await this.embed(result.summary),
 metadata: { task: result.task, outcome: result.outcome }
 });
 }
}

class ToolRegistry {
 register(name, fn, schema) {
 this.tools.set(name, { fn, schema: z.object(schema) });
 }

 async call(name, rawArgs, context) {
 const tool = this.tools.get(name);
 if (!tool) return { error: 'tool_not_found', name };

 // Validate BEFORE calling
 const parsed = tool.schema.safeParse(rawArgs);
 if (!parsed.success) {
 // Structured error lets LLM self-correct
 return { error: 'invalid_args', details: parsed.error.format() };
 }

 // Execute with timeout
 const result = await Promise.race([
 tool.fn(parsed.data, context),
 new Promise((_, rej) => setTimeout(() => rej(new Error('timeout')), 10000))
 ]);

 this.telemetry.record({ tool: name, args: parsed.data, result });
 return result;
 }
}

// Typed tool schema:
registry.register('search_code', searchCode, {
 query: z.string().min(3).max(200),
 extensions: z.array(z.enum(['.ts','.js','.py'])).optional(),
 maxResults: z.number().int().min(1).max(20).default(5),
});

const agentFSM = {
 IDLE: { next: ['PLANNING'] },
 PLANNING: { next: ['EXECUTING', 'FAILED'] },
 EXECUTING: { next: ['WAITING_TOOL', 'REVIEWING', 'FAILED'] },
 WAITING_TOOL: { next: ['EXECUTING', 'FAILED'] },
 REVIEWING: { next: ['EXECUTING', 'COMPLETE', 'REPLANNING'] },
 REPLANNING: { next: ['EXECUTING', 'FAILED'] },
 COMPLETE: { next: ['IDLE'] },
 FAILED: { next: ['IDLE'] },
};

class StatefulAgent {
 state = 'IDLE';
 history = [];

 transition(next) {
 if (!agentFSM[this.state].next.includes(next)) {
 throw new Error(this.state + ' cannot transition to ' + next);
 }
 this.history.push({ from: this.state, to: next, at: Date.now() });
 this.state = next;
 this.telemetry.record('state_change', { from: this.state, to: next });
 }
}
// Every state change is logged, validated, and replayable

class InstrumentedLLM {
 async call(prompt, opts = {}) {
 const span = tracer.startSpan('llm.call');
 span.setAttributes({
 'llm.model': opts.model,
 'llm.prompt_tokens': estimateTokens(prompt),
 'agent.task_id': this.context.taskId,
 });
 try {
 const response = await this.client.complete(prompt, opts);
 span.setAttributes({
 'llm.completion_tokens': response.usage.completion_tokens,
 'llm.cost_usd': calculateCost(response.usage),
 });
 return response;
 } catch (err) {
 span.recordException(err);
 throw err;
 } finally {
 span.end();
 }
 }
}