Skip to content

agent-sdk.md

Latest commit

 

History

History
52 lines (41 loc) · 2.24 KB

agent-sdk.md

File metadata and controls

52 lines (41 loc) · 2.24 KB

Agent SDK

This template includes a sdk/ directory with TypeScript and Python starters. The SDK lets you embed Claude Code's agent loop inside your own applications — build custom bots, automations, or review tools.

Full reference: Agent SDK overview.

When to reach for the SDK

Need Use
Interactive coding CLI (claude)
One-off CI job CLI headless (claude -p "...")
Recurring scheduled job Routines
Long-running service, custom tools, custom orchestration SDK
GitHub PR automation Claude Code Action

Key SDK concepts

  • query() — the main entrypoint. Streams messages from the agent loop as an async iterable.
  • Options — cwd, permissionMode, model, maxTurns, tools, mcpServers, allowedTools, disallowedTools.
  • Custom tools — JSON Schema + handler. See sdk/custom-tool-example.ts.
  • Hooks — same lifecycle events as the CLI, intercepted in your process. See SDK hooks.
  • Sessions — persist and resume conversations. See sessions.
  • Subagents — spawn specialized agents programmatically. See SDK subagents.
  • Structured output — constrain the final response to a JSON schema. See structured outputs.

Safety for production deployments

Read Securely deploying AI agents before shipping an SDK-based service. The key points:

  • Never run in bypassPermissions mode against a user's data without sandboxing.
  • Validate every tool handler input — treat Claude-generated arguments as untrusted input.
  • Set maxTurns and cost budgets.
  • Log tool calls for audit.

Observability

See OpenTelemetry observability. The SDK emits OTel spans for each turn and tool call — point them at your collector of choice.