Agent SDK

Summary: The Agent SDK (Software Development Kit) provides the foundational primitives for building autonomous AI agents. It abstracts the agent loop — perception, reasoning, action, observation — into composable components: Agent, Tool, Memory, and Orchestration. Key implementations include Anthropic's Claude Code Agent SDK and OpenAI's Codex Goals API.

Core Architecture

┌─────────────────────────────────────────────────────────────┐
│                      AGENT SDK LAYERS                        │
├─────────────────────────────────────────────────────────────┤
│  APPLICATION LAYER: Your agent logic & business rules       │
├─────────────────────────────────────────────────────────────┤
│  ORCHESTRATION LAYER: Loop management, state, error handling │
├─────────────────────────────────────────────────────────────┤
│  PRIMITIVES LAYER:                                           │
│  ┌─────────┐ ┌────────┐ ┌──────────┐ ┌─────────────────┐   │
│  │ Agent   │ │ Tool   │ │ Memory   │ │  Orchestration  │   │
│  │ (LLM +  │ │ (func- │ │ (short/  │ │ (loop, halt,    │   │
│  │  prompt)│ │  tions)│ │  long)   │ │  retry, stream) │   │
│  └─────────┘ └────────┘ └──────────┘ └─────────────────┘   │
└─────────────────────────────────────────────────────────────┘

Key Primitives

1. Agent

  • Definition: LLM + system prompt + available tools
  • Responsibility: Reason about task, select tools, produce responses
  • Configurable: Model, temperature, max tokens, tool schemas

2. Tool

  • Definition: Function with JSON schema (name, description, parameters)
  • Execution: Sandboxed, async, with timeout & retry policies
  • Types: Built-in (file ops, shell, web search) + custom

3. Memory

Type Scope Persistence Use Case
Short-term Conversation Session Context window management
Long-term Cross-session Database Knowledge, preferences, history
Episodic Task-specific Session Trajectory, decisions, outcomes

4. Orchestration

  • Loop: while not done: observe → reason → act → observe
  • Halt conditions: Goal achieved, max iterations, user intervention, error threshold
  • Streaming: Token-by-token for UX, tool calls as events

Major Implementations

SDK Provider Key Features Status
Claude Code Agent SDK Anthropic Native tool use, streaming, TypeScript/Python Production
OpenAI Codex Goals OpenAI Persistent goals, session continuity, GitHub integration Beta
LangGraph LangChain Graph-based orchestration, state machines, human-in-loop Open source
AutoGen Microsoft Multi-agent conversations, code execution, tool use Open source

Agent Loop Pattern (Claude Code)

Diagram: (Mermaid diagram - view source for diagram code)

graph TD
    A[User Request] --> B[Initialize Agent]
    B --> C{Goal Complete?}
    C -->|No| D[Select Tool]
    D --> E[Execute Tool]
    E --> F[Observe Result]
    F --> G[Update Memory]
    G --> C
    C -->|Yes| H[Return Result]

Steps

  1. Perceive: Read user input + relevant memory
  2. Reason: LLM decides next action (tool call or final answer)
  3. Act: Execute tool in sandbox
  4. Observe: Capture result, update state
  5. Repeat until halt condition

Context Window Management

Critical for long-running agents:

Strategy Description Trade-off
Sliding window Drop oldest messages Loses early context
Summarization Compress history via LLM Compute cost, may lose nuance
Hierarchical Separate working/archival memory Complex implementation
RAG retrieval Fetch relevant past context Requires embedding index

Best Practices

  1. Idempotent tools — Safe to retry on failure
  2. Explicit schemas — JSON Schema for all tool params
  3. Observability — Log every loop iteration (prompt, tool, result)
  4. Budget limits — Token count, wall time, tool call count
  5. Human-in-the-loop — Approval gates for irreversible actions

Related Concepts

Sources