Agent Construction with Claude

Key points

1. 1

   The construction spectrum runs from most control to least effort. A custom loop on the Messages API gives full control, but you build the tools, loop and context handling. The Claude Agent SDK is Claude Code's harness as a Python/TypeScript library in your own process. Claude Managed Agents is a hosted harness driven through the API.

2. 2

   Custom loop: while stop_reason is "tool_use", run the requested tools and send tool_result blocks, each matched by tool_use_id, in the next user message. Stop when Claude ends its turn, and always enforce a maximum-iteration cap.

3. 3

   When Claude calls several tools in one turn, return every tool_result together in a single user message, placed before any text.

4. 4

   The Agent SDK ships the same built-in tools (file read, edit, shell, search), agent loop, permissions, sessions, hooks and automatic compaction that power Claude Code. To reach the same loop from another language, run the CLI with -p and JSON output.

5. 5

   By default the Agent SDK loads the same filesystem configuration as the CLI (user, project and local settings, CLAUDE.md, skills, hooks). For reproducible services, restrict settingSources and define behavior in code.

6. 6

   Loop limits: maxTurns / max_turns caps tool-use turns, and maxBudgetUsd / max_budget_usd caps estimated spend. When a limit is hit, the result carries an error subtype (for example error_max_turns), so check it before recording success.

7. 7

   SDK hosting patterns: ephemeral (a container per one-off task), long-running (persistent containers), hybrid (ephemeral containers that resume from a session store), and multi-agent containers. Transcripts on local disk are lost when a container is removed.

8. 8

   Claude Managed Agents is built on an agent (model, prompt, tools, MCP servers, skills), an environment, a session and events. It suits long-running, asynchronous work with minimal infrastructure, and sessions persist event history server-side.

9. 9

   Deployment model: a Managed Agents environment runs either in an Anthropic-managed cloud sandbox or in a self-hosted sandbox on your infrastructure. The self-hosted option serves compliance and data-residency needs. For fully self-hosted, run the Agent SDK or your own loop.

10. 10

    Hooks give deterministic control. PreToolUse runs before a tool executes and can deny or modify the call (use it for guardrails). PostToolUse runs after execution (use it for formatting, linting and audit logs). Prompt instructions are only guidance.

11. 11

    SDK permission order is: hooks, deny rules, ask rules, permission mode, allow rules, then the canUseTool callback. A call approved at an earlier step never reaches canUseTool, and deny rules block even in bypassPermissions.

12. 12

    Put human-in-the-loop approval in the harness, on the high-impact actions (send, pay, delete), rather than on every tool call or in the prompt.

13. 13

    Trap: max_tokens caps a single response, not the number of loop iterations or the total cost. Runaway loops need turn or budget limits in the harness.

Read the source

• Agent SDK overview
• Agent SDK — agent loop
• Agent SDK — hooks
• Agent SDK — hosting
• Claude Managed Agents overview