enable New Possibilities: Building with the Claude Agent SDK

The Claude Agent SDK lets you build an agent that can plan work, read files, run commands, and edit code from your own Python or TypeScript process. Anthropic’s documentation describes it as the same agent loop, tools, and context management that power Claude Code, exposed as a library rather than only an interactive terminal interface.

That changes the engineering task. You are not just asking a model for text. You are deciding which tools it may use, which files it can touch, what requires approval, how external tools are connected, and what evidence marks the run complete. The SDK provides the loop; your application still owns the boundary around it.

Choose the SDK for the job

Anthropic’s Agent SDK overview separates several Claude products by use case. The Agent SDK fits a builder who wants an agent loop in their own process, in Python or TypeScript. The CLI fits interactive development and one-off terminal work. A client library fits direct API access when you want to implement the tool loop yourself. Managed agents fit long-running or asynchronous work where the provider manages the sandbox and session infrastructure.

Make that choice before writing integration code. If the task is a developer sitting at a terminal and reviewing one patch, a library may add more surface than needed. If the task is an application that needs a repeatable agent run, explicit tool permissions, and application-owned state, the SDK gives you the right control points.

Write down the expected run:

Input: a user request and repository context
Plan: the agent identifies files and tools needed
Execution: approved tools read, edit, or run bounded commands
Review: hooks, tests, and application policy inspect the work
Result: the application returns a report and durable run state

The important word is application. Do not make the model the security boundary.

Start with a small agent loop

The SDK overview lists built-in tools for reading, writing, editing, running commands, and searching the web. It also lists hooks, subagents, MCP, permissions, sessions, skills, commands, memory, and plugins as separate capabilities.

Start with one narrow task and one or two tools. A useful first run might inspect a failing test and propose a patch without automatically modifying production files. Add write access only after the read-and-review path is understandable.

import { query } from "@anthropic-ai/claude-agent-sdk"

for await (const message of query({
  prompt: "Inspect the failing profile test and explain the smallest safe fix.",
  options: {
    allowedTools: ["Read", "Grep"],
  },
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result)
  }
}

Treat this as an illustrative shape and verify the current SDK reference before copying it into a project. The design principle is stable: expose only the tools the task needs, inspect the result, and expand the permission surface deliberately.

A first implementation should answer three questions:

• Which inputs are trusted?
• Which tool calls can create side effects?
• What happens when the run stops halfway through?

If those answers are unclear, adding more tools will make debugging harder.

Use hooks as execution boundaries

Hooks run your code in response to agent events such as a tool call, session start, or execution stop. Anthropic’s hooks documentation describes hooks for blocking dangerous operations, logging tool calls, transforming inputs or outputs, requiring approval, and tracking session lifecycle.

A PreToolUse hook is a useful boundary for repository safety. It can inspect the tool name and arguments before execution and return a decision. For example, a project may block writes to environment files or require review for a command that changes a deployment configuration.

function protectFiles(toolName: string, input: Record<string, unknown>) {
  if (!(["Write", "Edit"].includes(toolName))) return { decision: "allow" }

  const path = String(input.file_path ?? "")
  if (path.endsWith(".env") || path.includes("/secrets/")) {
    return {
      decision: "deny",
      reason: "Protected file requires an explicit application review",
    }
  }

  return { decision: "allow" }
}

The exact callback shape depends on the SDK interface you use. Keep the policy itself independent from that shape so it can be tested without starting an agent.

A hook should not be your only control. Pair it with filesystem permissions, secret isolation, branch protection, and server-side authorization. If a policy must always hold, enforce it below the model as well as in the agent callback.

Configure permissions in layers

The permissions documentation describes a defined evaluation order for tool requests. Hooks run first, followed by deny rules, ask rules, permission mode, allow rules, and finally the canUseTool callback when the request remains unresolved.

That order gives you a practical design pattern:

• Use hooks for contextual checks and logging.
• Use deny rules for operations that should never run automatically.
• Use ask rules and canUseTool for approval decisions.
• Use allow rules to grant narrow, repeatable access.
• Use the permission mode to set the default behavior for the run.

Do not begin with a broad bypass mode and attempt to recover safety through prompts. Start with the smallest allowlist that can complete the task.

For a write operation, approval should cover the actual operation, path, and arguments. “Approve file edits” is less useful than “approve editing these two files for this request.” Record the decision with a request or operation identifier so an old approval cannot be reused for changed work.

Add denial tests to the integration suite. Ask the agent to read an environment file, edit a protected migration, run a destructive command, or write outside the workspace. The expected result should be a block or an explicit approval request, not a model-generated promise that it will be careful.

Connect external systems through MCP

MCP lets the Agent SDK connect to external tools and data sources. Anthropic’s MCP documentation describes local processes, HTTP servers, and SDK-integrated servers. It also shows restricting access with allowedTools when connecting to a server.

Treat an MCP server as a new permission surface, not as a harmless plugin. Before enabling one, record its tools, data scope, credentials, network destinations, and side effects. Start with read-only operations and add writes only when the approval and audit path is clear.

const options = {
  mcpServers: {
    internalDocs: {
      type: "http",
      url: "https://docs.example.invalid/mcp",
    },
  },
  allowedTools: ["mcp__internalDocs__search"],
}

The hostname above is illustrative and not a real OTF integration. Replace it only with a verified service in your own environment. Never place a real credential in a prompt or committed configuration.

Keep retrieved content separate from trusted instructions. A document can contain text that attempts to redirect the agent. The server must still validate identity, resource ownership, arguments, and destination before executing a tool.

Add sessions and state deliberately

The SDK overview lists sessions for maintaining context across exchanges and resuming or forking later. That is useful for long tasks, but persistence creates another state-management problem.

Define what the session stores and what it does not:

• Store the request ID, repository revision, plan, tool events, approvals, and result category.
• Avoid storing secrets, unnecessary personal data, and unredacted provider responses.
• Tie resumptions to the same repository and permission policy.
• Re-check authorization when a session resumes.
• Make external writes idempotent before allowing retries.

A resumed session is not automatically a trusted session. The user’s role, repository state, and tool policy may have changed since the previous turn.

For background work, checkpoint after meaningful side effects. If the agent created a draft and then timed out, the next run should find the draft rather than create a duplicate. Store a stable operation ID and return the existing result when a retry refers to the same operation.

Put the repository in the loop

The agent can only follow conventions it can find. Keep a short root instruction file that explains project layout, build commands, protected paths, test commands, and the expected completion report. Scope detailed procedures to the directory or task where they apply.

A repository note might say:

Before editing:
- Read the root project instructions.
- Find the closest existing pattern.
- State the files expected to change.
- Do not edit generated or protected files without review.

Before completion:
- Run focused tests and the required type/build checks.
- Review the diff for unrelated changes and secrets.
- Report checks run, checks not run, approvals, and remaining risk.

This is where the SDK’s skills, commands, memory, and plugin capabilities can fit. Keep instructions short and versioned. Use hooks and CI for rules that prose alone cannot enforce.

For a deeper repository pattern, read production repository conventions for AI coding agents and safe AI agent tool permissions.

Evaluate the loop before adding autonomy

A useful evaluation set includes:

• A read-only task with a known answer.
• A small edit that should reuse an existing pattern.
• A malformed input case.
• A protected-file request.
• A command that needs approval.
• An MCP result containing an instruction aimed at the model.
• A timeout after an external side effect.
• A resumed session with changed permissions.

Record the repository revision, SDK version, model configuration, tools exposed, approvals, changed files, checks, and final result. Compare the run after every meaningful change to the agent, hooks, tools, or repository policy.

Do not measure only whether the final text sounds correct. Check whether the agent respected the file boundary, requested approval, preserved the user’s input, avoided duplicate side effects, and returned an honest failure when a tool was unavailable.

Connect the SDK to a durable product foundation

The Claude Agent SDK is the runtime layer. The product still needs an application boundary around it: authentication, authorization, data ownership, limits, audit records, safe retries, and user-visible status.

OTF paid full-stack kits include AI-tool configuration files and more than 20 tested prompts so a coding agent can extend code the buyer owns with project context. That does not replace SDK permissions or your application’s policy. It gives the agent a known repository vocabulary to work within. Review the current OTF templates before choosing a starting point.

The SDK’s value is the set of control points around the loop: built-in tools, hooks, permissions, MCP, sessions, skills, and application-owned state. Start narrow, make approvals explicit, test denial and retry paths, and expand only when the evidence supports it. The model may change. The boundary you build around the agent should remain understandable.

Sources

• Claude Agent SDK overview
• Claude Agent SDK permissions
• Claude Agent SDK hooks
• Claude Agent SDK MCP