Manifest essentials

agent.yaml is the deployable contract for one agent. Start with tanomis agent new; the generated manifest carries safe defaults and a minimal model authorization grant.

This page covers the fields you touch first. For every accepted setting — including MCP connectors, delegation, capability metadata, and the full validation rules — see the Agent manifest reference.

At a glance

• name, version, framework, entrypoint, kind, and identity_mode identify the agent and its behaviour.
• persistent: true and session limits shape the workspace; resources reserve capacity.
• model and permitted_models, network.egress, and policy declare what the version may reach; every one is a ceiling the tenant can narrow.

Identity and behavior

name: support-copilot
version: 0.1.0
framework: claude-agents-sdk
entrypoint: agent:create_agent
kind: interactive
identity_mode: service

• name is the stable agent identity.
• version labels an immutable build.
• framework selects the harness adapter.
• entrypoint is python_module:function.
• kind describes interactive or background behavior.
• identity_mode declares the intended attribution posture: service, delegated, or hybrid. Hosted deployments require it explicitly, and the first non-rejected version pins it, so choose with your organization administrator before production use. Read Agent identity and access before choosing: availability and enforcement differ by path, and a mode grants nothing by itself.

Persistence and warm starts

persistent: true
session:
  idle_timeout: 30m
  max_lifetime: 24h

persistent provisions durable tenant-scoped storage and is required for new hosted versions. Hosted sessions are moving to one managed worker boundary. Within that rollout, a snapshot can make startup faster, but it does not select a different runtime and is not controlled by the agent manifest.

Older manifests may still contain cr_enabled. The platform accepts it temporarily for internal rolling-deployment compatibility, but current runtime selection does not consult it. The deploy pipeline and CLI still use true temporarily to request a golden build until their follow-up cutover. During that rollout, a server may require cr_enabled: true on a manifest that declares egress or settlement; this admission check disappears after universal-worker and golden-policy cutover.

The harness owns its checkpoint format while the runtime owns the workspace and lifecycle.

Models

model: "your-workspace-model-id"
permitted_models:
  - "your-workspace-model-id"

model is the default resolved model. permitted_models is the runtime allowlist for overrides. Use model IDs available to the selected tenant. When changing the model, update the matching llm:<model-family>:invoke scope emitted by the scaffold.

Resource requests

resources:
  cpu: 100m
  memory: 512Mi

These are scheduling requests, not the burst ceiling. Leave them at the scaffolded values until measurements show a reason to change them. Optional cpu_limit and memory_limit raise the per-agent ceiling when tenant policy allows it.

Network egress

network:
  egress:
    - github.com

The external hostnames this agent may reach. Entries are bare, lowercase hostnames, and an entry covers its subdomains — github.com admits api.github.com. Wildcards, addresses, and in-cluster names are refused at deploy.

The platform’s own destinations — the managed model gateway and governed connector routes — are always available and are never declared here; your list only adds to them. Your administrator can set a tenant ceiling that narrows what you declare. On the managed worker path, egress is enforced identically on snapshot restore and clean bootstrap; if that boundary cannot be established, a session with author-declared egress is refused rather than sent to the transitional ordinary path.

Availability: Author-declared egress is enabled per tenant. See What is available where and the manifest reference for the grammar and enforcement points.

Approvals and authorization

policy:
  approval_required_tools:
    - Bash
  enable_ask_user: true
  scope_ceiling:
    - "llm:your-model-family:invoke"
  allowed_audiences:
    - "https://your-workspace-api.example"

• approval_required_tools pauses listed tools for a human decision.
• enable_ask_user exposes the harness question flow.
• scope_ceiling declares the maximum set of concrete capabilities a scoped token may carry. Wildcard grants are not accepted.
• allowed_audiences declares HTTPS resource audiences for scoped tokens and is required when a scope ceiling is present.

Availability: These authorization declarations validate and record the intended contract, but scoped service-token acquisition and delegated acquisition are currently held: no supported public runtime workflow uses them. Do not infer a token-minting setup from this example. Read Agent identity and access before designing scoped authority.

The first two fields emit runtime interactions, not token-exchange approvals. Once the version is deployed, follow Handle approval-required actions to list, validate, answer, and audit those durable questions and tool decisions through the Platform API.

When a supported integration makes these fields actionable, use only the audience supplied for your tenant/environment. Never copy one from another environment.

Harness settings

Keep only the block matching framework:

harness:
  claude-agents-sdk: {}

or:

harness:
  deepagents:
    is_async: true
    stream_modes: [messages, updates, custom]
    checkpointer: workspace-sqlite
    backend: workspace-composite
    recursion_limit: 50

Validate the whole contract without uploading:

Terminal

tanomis agent deploy . --tenant northwind-sandbox --dry-run

Connect tools across workspaces

Declare integrations with the published definition and contract, identity: user or workspace, and tools.allow. Required integrations block execution until configured; use required: false only when the agent can work without those tools. Customer connection IDs and credentials do not belong in the manifest. Configure them in Agent → Integrations after publishing the version. See the portable MCP fields and workspace setup guide.

Where to go next

• Agent manifest: every field, default, and validation rule.
• Choose models: the model allowlist and the gateway.
• Test before you deploy: the dry run and the sandbox.