Write your agent

An agent on Tanomis is one Python module with one callable. The runtime calls it with the run’s input and a context, and you return what the harness needs to start. Everything else, the model route, the workspace, credentials, session continuity, governed tools, is supplied by the runtime.

At a glance

• The entrypoint is module:callable, declared in agent.yaml as entrypoint.
• It receives input_payload (the run’s input JSON) and context (the runtime context).
• With Claude Agent SDK it returns (prompt, options); with Deep Agents it returns a compiled graph.
• It must not choose a model, a working directory, or credentials. Those are the manifest’s and the runtime’s.

The entrypoint

agent.yaml

entrypoint: agent:create_agent

agent.py

from __future__ import annotations


def create_agent(input_payload, context):
    ...

The callable may accept both arguments, only context, or none, and it may be async. Keep the module importable outside the managed runtime so the contract test can import it.

What comes in

Argument	What it holds
input_payload	The run’s input object exactly as your application sent it, for example {"prompt": "..."}. Its shape is yours to define; document it for the callers of your agent.
context	The runtime context: the resolved model under context.runtime_context.model, the session, and the workspace. Pass the model through unchanged; the runtime resolved it for the tenant and version.

What you return

Harness	Return	Notes
claude-agents-sdk	(prompt, options)	options is a plain dictionary: system prompt, allowed and disallowed tools, max turns, hooks, subagents, permission mode.
deepagents	The compiled graph from create_deep_agent	Tools, middleware, and graph state are yours; the model comes from context.runtime_context.model.

See Claude Agent SDK and Deep Agents for a complete example of each.

Who owns what

Concern	Owner
Behaviour: prompts, tools, turns, hooks, subagents, graph	You
Model resolution and provider credentials	Runtime, from model and permitted_models
Workspace root and working directory	Runtime
Session identity, resume, and streaming	Runtime
Tool decisions	Composed: your restrictions first, then platform approvals
Governed connector configuration	Runtime, from mcp.connectors

Setting a model or a working directory in code to bypass the manifest does not work: the runtime resolves those for the tenant and version, and the manifest is the contract that was reviewed.

Ask for a person when it matters

Two manifest switches turn moments in your agent into durable interactions: list tools in policy.approval_required_tools to pause for a permission decision, and set policy.enable_ask_user: true to let the agent ask a question. Your code does not implement the pause; the harness emits it and the runtime holds it. See Approval-required actions.

Where to go next

• Manifest essentials: the fields you touch first.
• Session workspace and state: what persists between runs.
• Test before you deploy: the contract test and the dry run.