What does the Claude Agent SDK change for internal tools?

The Claude Agent SDK makes a specific class of internal tool much cheaper to prototype: software that can inspect a working context, choose among tools, act over several turns, and report a result. It removes a pile of agent plumbing. It does not remove the hard product decisions around authority, data boundaries, failure handling, or whether an agent belongs in the workflow at all.

That distinction decides whether a team ships a useful tool in two weeks or creates an expensive chat window that nobody trusts. Treat the SDK as an application runtime for Claude Code capabilities, not as a finished internal tools platform. You still own the contract between the agent and the business.

The SDK abstracts the agent loop, not your product

The SDK gives your application a working agent loop with far less glue code than a direct model integration. Your code can send a task, stream typed messages, let Claude call built-in or custom tools, continue the conversation, interrupt it, and resume a session. In Python, query() fits bounded jobs whose input is known at the start. ClaudeSDKClient fits interactive or multi-turn work where the application needs to send more input while the session is alive.

That is materially more than an API client. A normal model client sends messages and receives content. You would otherwise write the loop that detects tool requests, dispatches functions, packages results, maintains conversation state, imposes turn limits, and streams progress. The SDK already speaks the protocol used by Claude Code and includes the command line runtime in its Python package. The official Python README says the bundled command line tool is used by default, while cli_path can select another installation. That packaging choice removes a setup dependency, but it also means you should pin and test the SDK as a runtime dependency, not treat it like a harmless collection of types.

The supplied capabilities include file operations, shell execution, search, web access where configured, hooks, sessions, subagents, and Model Context Protocol connections. Custom Python tools run as MCP servers inside your process. This is a useful abstraction because the model sees one consistent tool interface while your application can expose ordinary business functions behind it. A ticket lookup, a deployment query, and a policy check can all look like tools even when their backing systems have nothing in common.

The SDK does not know what a release approval means in your company. It does not decide which repository a person may inspect, which customer records belong to a support case, when a manager must approve an action, or how long a transcript may be retained. It cannot tell whether the correct result is a comment, a database update, a queued proposal, or a refusal. Those are product rules, and hiding them in a system prompt makes them harder to test.

A useful ownership split is simple. Let the SDK handle model interaction, tool protocol, message streaming, and session mechanics. Keep identity, authorization, tenancy, business state, durable audit records, and side effects in application code. The model may propose that an invoice be refunded. A deterministic service should verify the actor, amount, account, and approval state before any refund endpoint runs.

The abstraction boundary is useful and leaky

The SDK saves implementation time, but its abstractions remain visible whenever you debug cost, latency, permissions, or a bad tool call. Plan for that leak instead of building an internal API that pretends every agent run is a single text request.

First, the output is an event stream, not just an answer. Assistant text, tool requests, tool results, system messages, and a final result have different meanings. An internal interface should show enough of that progression for a user to understand whether the agent is reading, waiting, blocked, or finished. If your wrapper collapses everything into a spinner followed by prose, operators cannot distinguish a slow model from a stuck tool or a permission request.

Second, sessions have state. Reusing one client keeps a live conversation; resuming by session identifier can recover disk-backed context; forking can branch from an earlier session. This is convenient, but session state is not your business record. A release decision still belongs in the release system. Store the approved inputs and final structured result there, with the SDK session identifier only as diagnostic metadata. If the session files disappear, the business state must remain coherent.

Third, tool names and schemas become part of agent behavior. A vague tool called manage_release forces the model to infer too much. Separate tools such as get_ci_status, list_blocking_reviews, and propose_release_note expose clearer choices and allow different permission rules. Good descriptions state when to call a tool, what its identifiers mean, and what failure looks like. They do not try to teach the entire workflow inside one parameter description.

Fourth, the model can return prose that sounds settled even when its evidence is incomplete. Structured output helps with parsing, but a valid object is not necessarily a correct decision. Include evidence fields, missing input fields, and an explicit outcome vocabulary such as ready, blocked, or needs_review. Then validate the object and compare every cited identifier with data your application actually supplied.

This is where teams often blur orchestration and policy. Orchestration answers, "Which tool should run next?" Policy answers, "May this actor cause that operation on this resource now?" Claude can help with the first. Your code must answer the second. If you put both in the prompt, a prompt injection or misunderstood instruction can cross a boundary that should never have depended on language.

Tool results deserve their own contract as well. Do not pass an entire ticket history, database row, or monitoring response back to the model because the connector already returns it. Select the fields needed for the task, cap collections, label timestamps and units, and distinguish "no records" from "the query failed." A model cannot repair an ambiguous empty array. It may treat missing data as proof that no problem exists, which is exactly the wrong inference for an approval workflow.

Keep connector behavior deterministic. A tool should either return a typed result, return a typed business error, or fail with an operational error that the application can classify. Do not let it silently substitute a nearby project, retry with broader credentials, or turn a failed lookup into a text apology. Those conveniences obscure the evidence chain. The agent can choose another permitted tool after a visible failure, while the application can decide whether a retry is safe.

Latency also leaks through the abstraction. One agent run may contain several model turns and several network calls, so it will not behave like a normal form submission. Give each tool a deadline shorter than the job deadline. Stream plain progress based on actual events, such as "reading test summary" or "waiting for policy service," without inventing a percentage. If a user action needs a response within a second or two, use deterministic code for that action and run the agent before or after it.

Finally, define the boundary in an architecture note that fits on one page. List the input owner, workspace contents, tools, service identities, possible side effects, approval point, retained records, and shutdown control. This artifact catches design contradictions early. If nobody can say which component rejects an unauthorized write, the design is not ready for implementation, however good the demonstration looks.

Permissions are a policy layer, not a sandbox

SDK permission settings control how tools are offered and approved, but they do not reduce the operating system rights of the process. A restricted tool list is necessary. It is not isolation.

The official Python README makes an easy-to-miss distinction. allowed_tools auto-approves listed tools; it does not remove every unlisted tool from the toolset. Unlisted tools continue through the configured permission decision path. Current SDK versions also expose a tools option for selecting the base tool set, while disallowed_tools blocks named tools. If you intend to build a reader, configure only read tools in tools, then apply an approval policy as a second control. Do not assume an allowlist with a reassuring name has created the boundary you wanted.

The working directory has similar limits. Setting cwd points the agent at a project. It does not create a jail. A shell tool running under your service account has that account's file and network access unless the host, container, or operating system blocks it. The same is true for an in-process custom tool: it can do whatever your function can do.

For an internal deployment, enforce the boundary outside the model process:

• Run the agent as a dedicated identity with the minimum file and service rights.
• Mount only the workspace needed for the task and prefer a disposable copy.
• Restrict outbound network access to named services, or remove it entirely.
• Put write operations behind narrow APIs that repeat authorization checks.
• Record tool name, normalized input, result status, actor, and correlation identifier.

Hooks are useful inside that boundary. A PreToolUse hook can reject a shell command, rewrite a tool input, or require an application decision before execution. A PostToolUse hook can normalize logging and scan results. Hooks are deterministic code around the loop, which makes them better than a prompt for rules such as "never read the secrets directory." Yet pattern matching a command string is a weak security boundary. Shell syntax has too many equivalent forms, and a future tool can bypass a filter written for today's names. Remove dangerous capabilities first, then use hooks for context checks and evidence.

Human approval also needs careful placement. Asking a user to approve every read creates fatigue; auto-approving every write creates incidents. Require approval at the business consequence, such as publishing a release or changing an entitlement, and display the exact proposed change plus its evidence. Approval of an opaque statement like "continue agent task" is not meaningful consent.

Build or buy depends on where judgment lives

Use the SDK when your advantage lies in a workflow that is specific to your company and the available packaged products would force that workflow into their model. Buy when a vendor already owns the whole boring problem, especially identity, connectors, audit history, and ongoing compatibility.

The popular recommendation to build because the first demo takes a day is wrong. The demo measures prompt quality and API access. The production cost sits in access reviews, connector changes, evaluation cases, user support, incident response, data retention, and all the strange inputs that appear after launch. The SDK reduces the cost of the agent loop. It does not make those obligations disappear.

A purchase is usually stronger for horizontal jobs with settled interfaces: enterprise search, meeting transcription, password resets, basic ticket routing, or a chat surface over common systems. A vendor can spread connector maintenance and compliance work across many customers. Rebuilding a generic connector catalog with your own team rarely creates an advantage.

A custom build becomes reasonable when four conditions hold:

• The workflow crosses internal systems in a sequence that encodes company knowledge.
• Existing products would need broad access while a custom tool can use a narrow service account.
• The outcome can be evaluated against examples or checked by deterministic rules.
• Someone owns the tool after the prototype and can remove it if usage stays low.

Do not reduce the decision to license cost versus developer hours. Compare the cost of change. A vendor owns upstream API churn but may make your special approval path impossible. Your team can change custom behavior quickly but must repair it whenever the SDK, model, repository layout, or internal service changes. Estimate both paths over a year, including security review and on-call work.

There is also a middle path: buy the systems of record and build a thin agent that reads them through approved APIs. The agent should not become a shadow ticketing system or another source of truth. This pattern keeps durable state in mature products while allowing company-specific reasoning across them. It is often the best use of the SDK for an internal tool.

A first project needs narrow consequences

The best first project produces a useful recommendation from read-only evidence and lets a person make the consequential decision. It should run often enough to generate feedback, fail visibly, and have a manual fallback that people already understand.

Avoid a general internal assistant. Its scope expands with every question, so you cannot define success, predict access needs, or assemble a representative test set. Also avoid an agent whose first responsibility is writing production data. Even if each action seems reversible, the combination of broad inputs and broad authority makes evaluation difficult.

A release readiness reviewer is a better candidate. Give it a disposable snapshot containing a pull request description, changed files, test summaries, deployment policy, and a template for release notes. Ask it to find missing evidence, map changes to the policy, and produce a recommendation. It may read and search the snapshot. It may not edit the repository, run arbitrary shell commands, publish comments, or trigger a deployment.

This project answers a real operational question without pretending the model owns the release. A human reviewer already performs the task. The source evidence is finite. The result can cite file paths, checks, and policy clauses. False positives waste review time, while false negatives remain contained because the person still approves the release. The manual process stays available when the agent fails.

Define success before writing the prompt. Track whether the reviewer identifies known blockers, whether every claim cites supplied evidence, how often humans accept its recommendation, run duration, cost, and how often users abandon it. Do not use user satisfaction alone. People like fluent summaries even when the summaries omit a failed check. Seed the evaluation set with awkward cases: a skipped test reported as green, a policy exception with an expired date, generated files that dominate the diff, a renamed service, and an empty test report caused by a parser failure.

Set a deletion rule too. If the tool cannot save enough review time or catch enough missed evidence after a fixed trial, remove it. Internal AI tools accumulate because their marginal hosting cost looks small. Their real cost is the trust users spend checking unreliable output and the access surface security teams must keep reviewing.

Build the reviewer as a bounded job

The first version should accept a prepared directory and return a structured recommendation. Keep data collection outside the agent. A normal service can fetch the pull request, CI results, and policy file, redact secrets, then write a temporary workspace. That gives the agent a stable input contract and makes evaluation runs reproducible.

A minimal Python runner can look like this:

import anyio
from pathlib import Path
from claude_agent_sdk import ClaudeAgentOptions, ResultMessage, query

PROMPT = """
Review the supplied release packet. Read only files in this workspace.
Return one JSON object with: outcome, blockers, missing_evidence,
and evidence. Every blocker must cite a file path and a short excerpt.
Use outcome needs_review when evidence conflicts or is incomplete.
Do not propose commands and do not modify files.
"""

async def review(packet_dir: str) -> None:
    options = ClaudeAgentOptions(
        cwd=Path(packet_dir),
        tools=["Read", "Glob", "Grep"],
        allowed_tools=["Read", "Glob", "Grep"],
        max_turns=12,
        max_budget_usd=1.00,
        system_prompt="You are a release evidence reviewer.",
    )

    async for message in query(PROMPT, options=options):
        if isinstance(message, ResultMessage):
            print(message.result)
            print({
                "session_id": message.session_id,
                "cost_usd": message.total_cost_usd,
                "turns": message.num_turns,
            })

anyio.run(review, "./release_packet")

The expected business result should be narrower than free prose:

{
  "outcome": "needs_review",
  "blockers": [
    {
      "rule": "database migration has rollback evidence",
      "evidence": "policy.md:42",
      "reason": "No rollback result appears in ci_summary.json"
    }
  ],
  "missing_evidence": ["rollback test result"],
  "evidence": ["changes.txt:18", "ci_summary.json:7"]
}

In production, use the SDK's structured output facility rather than trusting print(message.result), then validate the returned schema again in your application. The second validation should reject unknown outcome values, nonexistent evidence paths, excerpts absent from the cited files, and an answer that claims readiness while missing_evidence is not empty. These checks catch confident formatting errors without asking another model to grade the first model.

The snippet contains two separate controls that teams commonly confuse. tools limits the built-in capabilities presented to the agent. allowed_tools makes those selected read operations run without repeated approval. The container and service identity still need their own restrictions. Pointing cwd at release_packet does not stop a compromised process from reading elsewhere.

Keep the first prompt in source control beside the result schema and evaluation cases. Version all three together. When someone changes the prompt, run the old and new versions across the same packets and compare blocker recall, unsupported claims, cost, and duration. A prompt change that reads better but misses one policy exception is a regression.

Inspectable results beat clever autonomy

A useful internal agent shows its work in a form a busy operator can verify. It does not expose private reasoning. It exposes inputs, tool activity, evidence, uncertainty, and the exact proposed business action.

For the reviewer, render the outcome first, followed by blockers and their citations. Put missing evidence beside the recommendation instead of burying it in a transcript. Show which packet version was reviewed and when the source snapshot was created. Let the user open the cited local artifact through your application, but keep the agent output itself free of invented links.

Store a compact execution record for each run: application user, source object identifiers, prompt version, model identifier, SDK version, selected tools, tool calls, final validated result, cost, duration, and terminal status. Redact tool results according to the data policy before they enter general logs. Full transcripts are tempting during debugging, yet they often contain source code, customer data, or credentials returned by a badly scoped tool. Separate short operational telemetry from restricted diagnostic content.

Failures need names that your support team can act on. Distinguish invalid input, denied permission, tool failure, model refusal, budget limit, turn limit, schema failure, cancellation, and internal exception. A generic "agent failed" message sends every problem to the same engineer and hides whether retrying is safe. Only retry failures known to be transient. A repeated schema failure needs investigation, not three more paid attempts.

Design cancellation before launch. Users close browser tabs, deployments change while a review runs, and a newer packet can make an older run irrelevant. Your application should cancel the SDK session, mark its record, and discard any late result. For actions with side effects, cancellation also needs idempotency and reconciliation, because stopping the conversation may not stop a tool call already accepted by another service.

Feedback should capture a correction, not a thumb. Ask the reviewer which blocker was wrong, which evidence was missed, or why the outcome changed. Turn accepted corrections into evaluation cases after removing sensitive data. This creates an improvement loop grounded in the work instead of a collection of vague ratings.

Operations remain your engineering work

The agent runtime does not own reliability for the full internal tool. You need capacity limits, queues, timeouts, version control, data handling, support procedures, and a way to disable the feature without disabling the underlying systems.

Put runs behind a queue when they can last longer than a normal request. Give each job an application identifier and treat SDK session identifiers as implementation details. Enforce concurrency per tenant or team so one bulk action cannot consume the entire budget. Set both turn and monetary limits. A monetary cap protects against one runaway session; a daily application budget protects against a loop that starts thousands of valid sessions.

Pin package versions and record them with every result. The Python package bundles a Claude Code command line version, and the Anthropic changelog tracks package and bundled runtime updates separately. Read that changelog as release notes for an execution engine. Test upgrades against your packet corpus before rollout, especially permission behavior, message types, session resume, and tool result parsing.

Model changes deserve the same treatment. A newer model can improve general reasoning and still change tool choice or output wording enough to break hidden assumptions. Keep parsers strict, prompts explicit, and evaluation cases independent of exact prose. Roll out by cohort, compare failure categories, and retain the ability to route new runs back to the last tested combination.

Secrets should enter tools at execution time, not the prompt or workspace. The agent asks for a business operation; the tool resolves credentials from a secret store and calls the service under a scoped identity. Never return a credential in the tool result. If a service response includes one, filter it before the result reaches the model and before any hook logs it.

Assign ownership in ordinary operational terms. One team owns the application, one person can pause it, on-call staff can see current failures, and security staff know what data classes it touches. A fractional CTO can help set this operating model and decide where Claude Code, Codex, MCP tools, or multiple agents actually earn their complexity. The name of the framework matters less than a clear owner and a measured workflow.

Decide after a measured trial

A two-week trial should produce evidence for a build, buy, or stop decision, not a prettier demonstration. Run the reviewer beside the existing process on real but controlled release packets. Keep humans responsible for decisions and compare the agent's findings with the final review record.

At the end, inspect four things. Did the agent find blockers that matter? Did it invent or miscite evidence? Did it reduce active review time after verification? Can the team operate it within an acceptable cost and support burden? Break the results down by packet type, because a good average can hide complete failure on database changes or monorepos.

Continue building if the workflow is specific, the evidence is measurable, and access can stay narrow. Buy if most work is connector upkeep, identity administration, and features a mature vendor already supplies. Stop if users still reread every source from scratch, the output cannot be evaluated without opinion, or the tool needs broad write access to create modest value. Stopping is a sound engineering result.

If the trial succeeds, add one capability at a time. The next sensible step may be posting the validated review as a draft comment after user approval. It is not an open-ended assistant with production shell access. Each added action needs its own authorization check, audit record, failure behavior, and evaluation case. That pace can feel conservative after a fast prototype. It is how an internal tool earns enough trust to become part of the work.