AI Agents: A Deep Dive Into Architecture, Patterns, and Production

User → LLM → Answer

User → Retrieve docs → LLM + context → Answer

User → Goal → [Plan → Act → Observe]* → Result
                    ↑___________|
                         tools + memory

flowchart LR
  subgraph Chat
    U1[User] --> L1[LLM] --> A1[Answer]
  end
  subgraph RAG
    U2[User] --> R[Retriever] --> L2[LLM] --> A2[Answer]
  end
  subgraph Agent
    U3[User] --> G[Goal] --> P[Planner]
    P --> T[Tools]
    T --> O[Observe]
    O --> P
    P --> Done[Done / Escalate]
  end

┌──────────────────────────────────────────────────────────────┐
│                     Agent Runtime (control plane)             │
│  ┌─────────────┐  ┌──────────────┐  ┌─────────────────────┐  │
│  │   Policy    │  │ Orchestrator │  │  State / Session    │  │
│  │ guardrails  │  │ loop, budget │  │  memory, scratchpad │  │
│  └─────────────┘  └──────────────┘  └─────────────────────┘  │
│         │                 │                      │              │
│         └─────────────────┼──────────────────────┘              │
│                           ▼                                     │
│                  ┌─────────────────┐                            │
│                  │  LLM (reasoner) │                            │
│                  └────────┬────────┘                            │
│                           │ tool calls                          │
│                           ▼                                     │
│                  ┌─────────────────┐                            │
│                  │  Tool Gateway   │                            │
│                  │ auth, rate limit│                            │
│                  └────────┬────────┘                            │
└───────────────────────────┼──────────────────────────────────┘
                            ▼
              Git · DB · APIs · Browser · MCP servers

Step n:
  1. Build context (goal + history + tool results + memory)
  2. LLM outputs: thought + optional tool call(s)
  3. Execute tools (parallel if independent)
  4. Append observations to history
  5. Stop if: done | max steps | policy block | user interrupt

async function runAgent(goal: string, tools: ToolRegistry, budget: Budget) {
  const history: Message[] = [{ role: 'user', content: goal }]

  for (let step = 0; step < budget.maxSteps; step++) {
    const response = await llm.complete({
      messages: history,
      tools: tools.schemas(),
    })

    if (response.finishReason === 'stop' && !response.toolCalls?.length) {
      return { answer: response.text, history }
    }

    for (const call of response.toolCalls ?? []) {
      if (!policy.allow(call.name, call.args)) {
        history.push(observation(call.id, { error: 'POLICY_DENIED' }))
        continue
      }
      const result = await tools.execute(call.name, call.args)
      history.push(observation(call.id, result))
      budget.record(call, result)
    }

    if (budget.exceeded()) break
  }

  return { answer: null, history, status: 'BUDGET_EXCEEDED' }
}

interface MemoryStore {
  getRelevant(
    query: string,
    opts: { k: number; filters?: Record<string, string> }
  ): Promise<Chunk[]>
  put(chunk: Chunk): Promise<void>
}

// Orchestrator calls memory before each plan when goal is exploratory
const chunks = await memory.getRelevant(goal, { k: 8, filters: { repo: 'payments' } })

{
  "name": "create_draft_pr_comment",
  "description": "Post a draft review comment on a PR. Does not approve or merge.",
  "parameters": {
    "type": "object",
    "properties": {
      "owner": { "type": "string" },
      "repo": { "type": "string" },
      "pull_number": { "type": "integer" },
      "body": { "type": "string", "maxLength": 65536 }
    },
    "required": ["owner", "repo", "pull_number", "body"]
  }
}

IDE / Agent Host
    ├── built-in tools (read_file, grep)
    └── MCP client ──► MCP server (Jira, Postgres, custom)

Thought: I need the failing test name from CI.
Action: get_ci_logs(run_id="8821")
Observation: AssertionError in auth/token.test.ts ...
Thought: I'll read the test file and the implementation.
Action: read_file(path="src/auth/token.ts")
...

Request → Router → [CodeAgent | DataAgent | DocsAgent]

Supervisor
 ├── Researcher (read-only tools)
 ├── Coder (repo tools)
 └── Reviewer (lint, tests, no write)

Triager → Implementer → Tester → Documenter

Proposer ↔ Critic → merged answer

type Handoff = {
  runId: string
  goal: string
  facts: string[] // verified truths only
  artifacts: { path: string; summary: string }[]
  openQuestions: string[]
  constraints: string[] // "do not touch billing"
}

import OpenAI from 'openai'

type Tool = {
  name: string
  description: string
  parameters: Record<string, unknown>
  execute: (args: Record<string, unknown>) => Promise<unknown>
}

const tools: Tool[] = [
  {
    name: 'get_weather',
    description: 'Get current weather for a city',
    parameters: {
      type: 'object',
      properties: { city: { type: 'string' } },
      required: ['city'],
    },
    execute: async ({ city }) => {
      // Replace with real API
      return { city, tempC: 22, condition: 'cloudy' }
    },
  },
]

const openai = new OpenAI()

function toOpenAITools(ts: Tool[]) {
  return ts.map((t) => ({
    type: 'function' as const,
    function: {
      name: t.name,
      description: t.description,
      parameters: t.parameters,
    },
  }))
}

export async function weatherAgent(userGoal: string) {
  const messages: OpenAI.Chat.ChatCompletionMessageParam[] = [
    {
      role: 'system',
      content: 'You are a helpful agent. Use tools when needed. Be concise when done.',
    },
    { role: 'user', content: userGoal },
  ]

  const registry = new Map(tools.map((t) => [t.name, t]))
  const MAX_STEPS = 8

  for (let i = 0; i < MAX_STEPS; i++) {
    const completion = await openai.chat.completions.create({
      model: 'gpt-4.1-mini',
      messages,
      tools: toOpenAITools(tools),
    })

    const msg = completion.choices[0]?.message
    if (!msg) throw new Error('No message')

    messages.push(msg)

    const calls = msg.tool_calls ?? []
    if (calls.length === 0) {
      return msg.content ?? ''
    }

    for (const call of calls) {
      const fn = call.function
      const tool = registry.get(fn.name)
      if (!tool) {
        messages.push({
          role: 'tool',
          tool_call_id: call.id,
          content: JSON.stringify({ error: 'UNKNOWN_TOOL' }),
        })
        continue
      }
      const args = JSON.parse(fn.arguments || '{}')
      const result = await tool.execute(args)
      messages.push({
        role: 'tool',
        tool_call_id: call.id,
        content: JSON.stringify(result),
      })
    }
  }

  return 'Agent stopped: step budget exceeded'
}

const budget = {
  maxSteps: 12,
  maxTokens: 80_000,
  maxToolCalls: 30,
  maxCostUsd: 2.0,
}

function policyAllow(tool: string, args: Record<string, unknown>, ctx: Context): boolean {
  if (ctx.environment === 'production' && WRITE_TOOLS.has(tool)) return false
  if (tool === 'run_shell' && !ctx.allowShell) return false
  if (containsPathTraversal(args)) return false
  return true
}

{
  "runId": "run_abc",
  "goal": "Fix failing test in payments",
  "steps": [
    {
      "index": 0,
      "model": "gpt-4.1",
      "toolCalls": [{ "name": "read_file", "latencyMs": 42 }],
      "tokens": { "in": 1200, "out": 180 }
    }
  ],
  "outcome": "success",
  "costUsd": 0.14
}