Agent SDK runtime patterns

The SDK starts the Claude Code loop with tools, permissions, settings, CLAUDE.md, hooks and MCP. Deliberate runtime design prevents excess exposure, cache misses, stalled approvals and unreliable output handling.

Start with SDK basics. See API reference for APIs/settings/migration, agent features for loop/context/skills/subagents/checkpoints, and production deployment for isolation and observability.

#Runtime decisions

#Custom tools

Custom tools expose application capabilities through in-process MCP servers, suitable for internal APIs, databases, retrieval, tickets and business actions.

Return isError: true for recoverable business failures rather than throwing every error and potentially interrupting the loop.

import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";
import { z } from "zod";

const lookupInvoice = tool(
  "lookup_invoice",
  "Look up an invoice by ID and return billing status, amount, and due date",
  {
    invoiceId: z.string().describe("Invoice ID, for example inv_123")
  },
  async ({ invoiceId }) => {
    const invoice = await getInvoice(invoiceId);
    if (!invoice) {
      return {
        isError: true,
        content: [{ type: "text", text: "Invoice not found" }]
      };
    }
    return {
      content: [{ type: "text", text: `Status: ${invoice.status}` }],
      structuredContent: invoice
    };
  }
);

const billingServer = createSdkMcpServer({
  name: "billing",
  version: "1.0.0",
  tools: [lookupInvoice]
});

for await (const message of query({
  prompt: "Check invoice inv_123 and summarize the next action",
  options: {
    mcpServers: { billing: billingServer },
    allowedTools: ["mcp__billing__lookup_invoice"]
  }
})) {
  console.log(message);
}

#Choose a system prompt

For coding agents, prefer the preset plus append:

{
  systemPrompt: {
    type: "preset",
    preset: "claude_code",
    append: "When changing billing code, always mention migration and rollback risks."
  },
  settingSources: ["project"]
}

CLAUDE.md is injected project context, not the system prompt, and works with any prompt. Use settingSources: [] to avoid loading host rules in multitenant services.

#Streaming output

Streaming suits terminals, WebSockets, dashboards and log UIs. Do not wait only for the final result.

Single input suits simple tasks. Continuous chat requires explicit cancellation, timeout and navigation-away handling.

#Structured output

Structured outputs validate final results with JSON Schema, Zod or Pydantic for databases and UIs.

outputFormat: {
  type: "json_schema",
  schema: {
    type: "object",
    properties: {
      risk: { enum: ["low", "medium", "high"] },
      summary: { type: "string" },
      actions: {
        type: "array",
        items: { type: "string" }
      }
    },
    required: ["risk", "summary", "actions"]
  }
}

#Tool search

Tool definitions consume context. Search large catalogs first and load the most relevant tools.

Names and descriptions directly affect search quality:

On Vertex, Bedrock, Foundry or custom gateways, verify tool-reference support. Upfront fallback changes context usage and caching.

#User approvals and questions

canUseTool handles two kinds of pause:

Earlier allow rules, modes or allowedTools can skip canUseTool. Put mandatory checks in PreToolUse.

#Slash commands in SDK

Send noninteractive slash commands as prompts. Discover supported commands from system/init slash_commands.

/compact requires existing history; invoking it immediately in a new one-turn task is not useful.

#Prompt-cache TTL strategy

Caching is automatic. Hits depend on stable model, effort, prompts, tools, MCP, settings, CLAUDE.md and history prefixes.

Default behavior uses five minutes. Request one hour when reusing the same prefix after longer intervals:

export ENABLE_PROMPT_CACHING_1H=1

Observe separately:

#Official references

• Custom tools
• Modifying system prompts
• Streaming output
• Streaming Input
• Plugins in the SDK
• Structured outputs
• Tool search
• User input
• Slash commands in the SDK

#Related pages