# Claude Agent SDK

Write the Claude Agent SDK entrypoint, know what the runtime owns, and wire approvals and questions through the manifest.

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.

- 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

```bash title="Terminal"
tanomis agent new support-copilot --harness claude-agents-sdk --agents-root ./agents
```

## The entrypoint

```python title="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:

```yaml title="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](/guides/run/approval-required-actions)
for what happens when the run pauses.

## Validate and deploy

```bash title="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](/guides/build/write-your-agent): the contract every harness shares.
- [Manifest essentials](/guides/build/manifest-essentials): models, tools, hosts, limits.
- [Test before you deploy](/guides/build/test-before-you-deploy): the sandbox tenant.