Claude Agent SDK

With the Claude Agent SDK harness your whole agent is one callable that returns a prompt and the options Claude should run with. The runtime supplies the model, the workspace, credentials, and session continuity, and composes the platform’s approvals with your own tool restrictions.

At a glance

• Scaffold with tanomis agent new NAME --harness claude-agents-sdk.
• create_agent(input_payload, context) returns (prompt, options); options can be a plain dict, so the module imports without the runtime.
• Never set a model or working directory in the entrypoint; the manifest and runtime own them.
• Keep permission_mode: "default" so the platform’s approval-required tools can pause the run.

Scaffold

Terminal

tanomis agent new support-copilot --harness claude-agents-sdk --agents-root ./agents

The entrypoint

agents/support-copilot/agent.py

from __future__ import annotations


def create_agent(input_payload, context):
    prompt = input_payload.get("prompt", "Triage this request.")
    return (
        prompt,
        {
            "system_prompt": (
                "You are a support triage agent. Return severity, a short summary, "
                "and the next best action."
            ),
            "permission_mode": "default",
            "max_turns": 12,
        },
    )

The callable may also accept only context, accept no arguments, or be async. A plain options dictionary keeps your module importable outside the managed runtime, which is what the generated contract test relies on.

Who owns what

Concern	Owner
System prompt, allowed and disallowed tools, max turns, hooks, subagents	You
Workspace root and current working directory	Runtime
Model resolution and provider credentials	Runtime
Session ID, resume state, partial-message streaming	Runtime
Tool decision callbacks	Composed: your restrictions first, then platform approvals
Governed connector configuration	Runtime

Do not set a model or working directory in the entrypoint to bypass the manifest. The runtime resolves both for the tenant and version, and a run that tries to override them is refused.

Approvals and questions

Name the tools that need a person in agent.yaml, and let the harness ask questions:

agent.yaml

policy:
  approval_required_tools:
    - Bash
  enable_ask_user: true

Keep permission_mode: "default". bypassPermissions skips the SDK callback path and is not compatible with governed approvals. See Approval-required actions for what happens when the run pauses.

Validate and deploy

Terminal

cd agents/support-copilot
uv run python -m unittest tests/test_agent_contract.py
tanomis agent deploy . --tenant northwind-sandbox --dry-run

Where to go next

• Write your agent: the contract every harness shares.
• Manifest essentials: models, tools, hosts, limits.
• Test before you deploy: the sandbox tenant.