# Manifest essentials

Understand the agent.yaml fields that control identity, state, models, resources, and policy.

`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](/reference/agent-manifest).

- `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

```yaml
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](/concepts/identity-and-access)
  before choosing: availability and enforcement differ by path, and a mode grants nothing by itself.

## Persistence and warm starts

```yaml
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

```yaml
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

```yaml
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

```yaml
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](/reference/availability) and the [manifest reference](/reference/agent-manifest#network) for the grammar and enforcement points.

## Approvals and authorization

```yaml
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](/concepts/identity-and-access#what-the-service-assertion-is-and-is-not)
> 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](/guides/run/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`:

```yaml
harness:
  claude-agents-sdk: {}
```

or:

```yaml
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:

```bash
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](/reference/agent-manifest#governed-mcp-connectors) and
[workspace setup guide](/guides/connect-tools/mcp-connectors).

## Where to go next

- [Agent manifest](/reference/agent-manifest): every field, default, and validation rule.
- [Choose models](/guides/build/choose-models): the model allowlist and the gateway.
- [Test before you deploy](/guides/build/test-before-you-deploy): the dry run and the sandbox.