> For the complete documentation index, see [llms.txt](https://docs.interactive.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.interactive.ai/agents/reference/manifest.md).

# Manifest & content schemas

The annotated map of every manifest field, linking each block to its concept page, plus where the exact field-level schema reference lives.

> **Context** — This page is the navigational map of the manifest as of **manifest schema 1.4.0**: every block, what it does, where it's explained. The manifest shape is schema-versioned — which schema version applies to your runtime is the compatibility matrix's row for your image tag, and shapes differ across versions. The **exact field-level reference** (types, defaults, patterns, validation rules) is the generated Schemas reference — published per schema version alongside these docs, with machine-readable JSON Schemas (Draft 2020-12) in the artifact bucket (see [Versioning & compatibility](https://docs.interactive.ai/agents/operations/versioning.md#machine-readable-artifacts)).

## The full shape, annotated

```yaml
# ── Identity ────────────────────────────────────────────────────────────
name: DriveAway Production          # display name (UI, logs)
id: driveaway-prod                  # immutable URL-safe slug
version: "12"                       # your revision label (logs, traces)
description: Car rental bookings    # platform only: shown with the agent
appearance:                         # platform only: avatar keys from the palette
  icon: rounded
  color: twilight
endpoint: false                     # platform flag: provision a public URL?
secrets:                            # platform secret bundles to inject as env vars
  - secret_name: driveaway-agent-secrets
schedule:                           # platform only: when the agent runs
  uptime: Mon-Fri 07:30-20:30       #   exactly one of uptime / downtime
  timezone: Europe/Berlin
stack_id: driveaway                 # platform only: groups related resources

agent_config:
  # ── Process & engine knobs ───────────────────── concepts/architecture.md
  runtime:
    api_key: ${AGENT_API_KEY}       # shared bearer token (inbound + callbacks)
    log_level: INFO                 # TRACE|DEBUG|INFO|WARNING|ERROR|CRITICAL
    max_engine_iterations: 5        # per-turn tool/think chain cap
    policy_batch_size: 5            # policies per matcher call
    on_tool_error:                  # what a turn does when a tool fails ── concepts/tools.md
      default: continue             # continue | silent | handoff
      tools:
        zendesk:create_ticket: handoff
      handoff:
        reason: A required tool failed
        silent: true
    run_retention_days: 30          # days finished autonomous runs are kept for the runs view
    turn_recording: true            # record each conversation turn for the conversation view
    prompt_cache:                   # reuse cached prompt starts ── concepts/models.md
      enabled: true
      tool_results: autonomous      # off | autonomous | always

  # ── Platform connection ──────────────────────── concepts/architecture.md
  interactive_platform:
    base_url: https://app.interactive.ai   # also derives router + traces URLs
    public_key: ${INTERACTIVEAI_PUBLIC_KEY}
    secret_key: ${INTERACTIVEAI_SECRET_KEY}

  # ── Models ───────────────────────────────────── concepts/models.md
  llms:
    api_key: ${ROUTER_API_KEY}             # router credential (required)
    default: interactive/anthropic/claude-haiku-4.5    # customer-facing lane default
    fallback:                              # backup models, tried in order
      - interactive/anthropic/claude-sonnet-4-6
    response: interactive/anthropic/claude-sonnet-4-6  # final message (optional)
    preamble: interactive/anthropic/claude-haiku-4.5   # preamble + tool announcement (optional)
    search_query: interactive/anthropic/claude-haiku-4.5   # KB search-query writing (optional)
    evaluation:                            # internal engine inference (optional)
      default: interactive/google/gemini-3-flash-preview
      fallback: interactive/google/gemini-3.1-pro-preview   # escalation on retry exhaustion
      tools: interactive/anthropic/claude-haiku-4.5         # tool-call argument inference
      policy_matching: interactive/google/gemini-3-flash-preview
      routine_navigation: interactive/google/gemini-3.1-pro-preview
      judge: interactive/google/gemini-3.1-pro-preview           # replay rubric judge

  # ── Behavioural context ──────────────────────── concepts/prompts.md
  context:
    system_prompt:                  # persona & ground rules (versioned ref)
      id: driveaway-system-prompt
      version: 7
    language: match_user            # string; or an explicit language, e.g. "French"
    greeting: "Hi! I'm Mercedes from DriveAway — how can I help?"
    preamble:                       # mid-turn filler
      examples:
        - "Let me check."
        - "One moment."
      announce_tools: false         # true → status message after each tool batch
    routines:                       # ─────────── concepts/routines.md
      - id: car-search
        version: 4
      - id: book-a-car
        version: 9
    policies:                       # ─────────── concepts/policies.md
      - id: stay-on-topic
        version: 2
    glossaries:                     # ─────────── concepts/glossaries-and-macros.md
      - id: rental-terms
        version: 2
    macros:                         # ─────────── concepts/glossaries-and-macros.md
      - id: cancellation-wording    #   interpolated via ${macro-id} in chat_state
        version: 3
    reevaluation_tools:             # ─────────── concepts/tools.md
      - id: crm:authenticate_customer
    current_datetime:               # ─────────── reference/built-in-tools.md
      timezone: Europe/Lisbon      #   optional, defaults to UTC
    variables:                      # ─────────── guides/authoring-routines.md
      - name: default_priority      #   bindable from routine input bindings
        value: normal               #   optional manifest-owned global value
    relationships:                  # ─────────── concepts/priorities.md
      priorities:
        - higher: policy:incident-handoff
          over_all_routines: true
      entailments:
        - when: policy:self-exclusion-request
          also_apply:
            - policy:rg-tone
      requires:
        - tool: crm:authenticate_customer
          result_has: player_info
          all_routines: true

  # ── Tool servers ─────────────────────────────── concepts/tools.md
  mcps:
    - cars-tools                    # MCP registered in the project; id = name
    - ref: cars-mcp                 # same, with an explicit tool prefix
      id: cars                      # tool prefix; defaults to ref
      endpoint: private             # private (default) or public

  # ── Retrieval grounding (one of two types) ───── concepts/knowledge-base.md
  search:
    type: external                  # or: type: collections
    url: https://search.internal.example.com/agent-search
    api_key: ${SEARCH_API_KEY}
    top_k: 5

  # ── Conversation storage ─────────────────────── concepts/memory-and-state.md
  database:
    hostname: agent-postgres.internal.example.com
    port: 5432
    user: postgres
    password: ${DB_PASSWORD}
    dbname: postgres
    sslmode: require

  # ── Traces ───────────────────────────────────── guides/observability.md
  traces:
    deployment_environment: production
    trace_id_field: customer_id     # names autonomous traces by input field
    backend:                        # omit for the platform default backend
      url: https://otel.your-provider.com/v1/traces
      api_key: ${OTEL_API_KEY}
      api_key_scheme: bearer

  # ── Third-party webhook fan-out ──────────────── concepts/autonomous-routines.md
  webhooks:
    - name: kyc-events
      secret_env: ${KYC_WEBHOOK_SECRET}
      header: X-Payload-Digest
      algorithm: sha256
      prefix: ""
      routines:
        - kyc-decision

  # ── Scheduled routine triggers ───────────────── concepts/autonomous-routines.md
  schedules:                        # requires the database block
    - name: fee-reminders
      routine: fee-reminder         # must declare an autonomous: block
      cron: "0 9 * * *"             # 5-field cron, UTC
      input: { sweep: fees }        # boot-validated against input_schema
      callback_url: https://hooks.example.com/results   # optional
      max_attempts: 1               # >1 opts into re-running failed runs

  # ── Conversation replay (non-production) ─────────────────────────────
  replay:
    enabled: true                   # serve tool calls from scenario fixtures
    dataset: replay-dev             # default scenario dataset (optional)
```

Required blocks: `runtime`, `interactive_platform`, `llms`, `context` (within it, `system_prompt` and `language`). Everything else is optional with the defaults documented on each concept page and aggregated in [Limits & defaults](https://docs.interactive.ai/agents/reference/limits-and-defaults.md).

### Field types by block

Top-level manifest fields:

| Field         | Type                             | Required | Default | Meaning                                                                                                                                                                                                                                     |
| ------------- | -------------------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`        | string                           | yes      | —       | Display name (UI, logs)                                                                                                                                                                                                                     |
| `id`          | string (URL-safe pattern)        | yes      | —       | Immutable slug                                                                                                                                                                                                                              |
| `version`     | string                           | yes      | —       | Revision label (logs, traces); the deployment operator deploys it as the agent image tag                                                                                                                                                    |
| `description` | string                           | no       | —       | Platform only: human-readable description of the agent                                                                                                                                                                                      |
| `appearance`  | `{icon, color}`                  | no       | —       | Platform only: avatar icon and colour keys from the platform palette; each lowercase letters, digits and single hyphens, at most 32 characters                                                                                              |
| `endpoint`    | boolean                          | no       | `false` | Platform flag: provision a public URL                                                                                                                                                                                                       |
| `secrets`     | list of `{secret_name: string}`  | no       | `[]`    | Platform secret bundles to inject as env vars                                                                                                                                                                                               |
| `schedule`    | `{uptime \| downtime, timezone}` | no       | —       | Platform only: when the agent runs. Exactly one of `uptime` (when it runs) or `downtime` (when it is scaled down), as comma-separated `WEEKDAY-WEEKDAY HH:MM-HH:MM` windows, plus an IANA `timezone`. Unrelated to `agent_config.schedules` |
| `stack_id`    | string                           | no       | —       | Platform only: stack the agent belongs to, grouping related resources; lowercase letters, digits, hyphens and underscores, at most 63 characters                                                                                            |

`runtime`:

| Field                                | Type                                                                  | Required | Default                                     | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ------------------------------------ | --------------------------------------------------------------------- | -------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `api_key`                            | string (`${VAR}` env-ref)                                             | yes      | —                                           | Shared bearer token (inbound + callbacks)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `log_level`                          | string enum: `TRACE`\|`DEBUG`\|`INFO`\|`WARNING`\|`ERROR`\|`CRITICAL` | no       | `INFO`                                      | Process log level                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `max_engine_iterations`              | integer (≥ 1)                                                         | no       | `5`                                         | Per-turn tool/think chain cap                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `policy_batch_size`                  | integer (≥ 1)                                                         | no       | `5`                                         | Policies per matcher call                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `streaming`                          | boolean                                                               | no       | `false`                                     | Stream the reply, preambles and tool announcements token-by-token (`output_mode=STREAM`). The prompts, text and `llms.fallback` are the same either way                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `startup_review`                     | boolean                                                               | no       | `true`                                      | Run advisory LLM authoring reviews after readiness; incurs model costs per process start. Set `false` to opt out; deterministic startup gates still run                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `generation_attempts`                | integer (≥ 1)                                                         | no       | `3`                                         | Attempts per model for the reply and each evaluation call (a failed or timed-out call uses one); the reply then moves to `llms.fallback`, evaluation to `llms.evaluation.fallback`                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `autonomous_default_timeout_seconds` | integer (> 0)                                                         | no       | `120`                                       | Timeout for autonomous runs without their own `timeout_seconds`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `autonomous_max_timeout_seconds`     | integer (> 0)                                                         | no       | `600`                                       | Hard cap; routine-declared timeouts above it are clamped (must be ≥ the default)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `autonomous_callback_max_retries`    | integer (≥ 0)                                                         | no       | `5`                                         | Delivery attempts for callbacks / event webhooks                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `run_retention_days`                 | integer (> 0)                                                         | no       | `30`                                        | Days finished autonomous runs and their steps are kept for the agent UI's runs view before they are deleted. Runs hold their input, output and tool results, which can be personal data. Needs a `database`; without one, runs are kept in memory until the pod restarts                                                                                                                                                                                                                                                                                                                                                  |
| `turn_recording`                     | boolean                                                               | no       | `true`                                      | Record each conversation turn's decisions, steps, knowledge-base searches and timings for the agent UI's conversation view: the activity row under each customer message and the turn inspector. Recording never delays a turn: rows are stored in the background and dropped if storage is slow. A tool's arguments and result are not copied; the view reads them from the session's events. Kept for `run_retention_days`; without a `database`, turns are kept in memory until the pod restarts. Set `false` to store nothing per turn on an agent with heavy traffic                                                 |
| `prompt_cache`                       | object                                                                | no       | `{enabled: true, tool_results: autonomous}` | Prompt caching. `enabled` marks the stable start of each prompt for the model provider to cache and keeps a conversation's calls on one provider host; set `false` only to rule caching out while diagnosing a provider error. `tool_results` (`off`\|`autonomous`\|`always`) decides which turns also cache the tool results gathered during the turn, once they reach about 2,000 tokens: `autonomous` covers autonomous routine runs, where one run is a single long turn, and `always` adds conversational turns. Gemini models cache nearly the whole prompt on every call, tool results included, whatever the mode |
| `on_tool_error`                      | object                                                                | no       | `{default: continue}`                       | What a conversational turn does when a tool request fails: `default` (`continue`\|`silent`\|`handoff`), per-tool overrides in `tools` (`{<tool>: <action>}`), and the `handoff` arguments (`reason`, optional `internal_note`, `customer_message` or `silent`) that `handoff` uses — a handoff switches the session to manual mode. Autonomous routines set `autonomous.on_tool_error` instead. See [Tools](https://docs.interactive.ai/agents/concepts/tools.md#when-a-tool-fails)                                                                                                                                       |

`interactive_platform`:

| Field        | Type                                 | Required | Default                      | Meaning                                          |
| ------------ | ------------------------------------ | -------- | ---------------------------- | ------------------------------------------------ |
| `base_url`   | string (`https?://` scheme required) | no       | `https://app.interactive.ai` | Platform host; also derives router + traces URLs |
| `public_key` | string (`${VAR}` env-ref)            | yes      | —                            | InteractiveAI public key                         |
| `secret_key` | string (`${VAR}` env-ref)            | yes      | —                            | InteractiveAI secret key                         |

`llms` — see [Models](https://docs.interactive.ai/agents/concepts/models.md#the-llms-block) for the full field table.

`context`:

| Field                | Type                                                                 | Required | Default           | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| -------------------- | -------------------------------------------------------------------- | -------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `system_prompt`      | object `{id: string, version: integer ≥ 1}`                          | yes      | —                 | Prompt reference                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `language`           | string                                                               | yes      | —                 | `match_user`, or one or more comma-separated languages: a name (`French`), an ISO 639-1 code (`fr`, `pt-BR`) or a name with its country (`Portuguese (Brazil)`). Codes are read as names and keep their country. Free text is rejected when the agent starts (the JSON Schema accepts any non-empty string). See [Language](https://docs.interactive.ai/agents/concepts/prompts.md#language) for the exact rules                                                                                                                                                                                                                                                                                                                                                                     |
| `greeting`           | string                                                               | no       | `None`            | First-turn greeting                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `preamble`           | object `{examples: list[string] (≥1), announce_tools: boolean}`      | no       | `None` (disabled) | Mid-turn filler config; `announce_tools` defaults `false`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `routines`           | list of `{id: string, version: integer ≥ 1}`                         | no       | `[]`              | Routine references                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `policies`           | list of `{id: string, version: integer ≥ 1}`                         | no       | `[]`              | Policy references                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `glossaries`         | list of `{id: string, version: integer ≥ 1}`                         | no       | `[]`              | Glossary references                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `macros`             | list of `{id: string, version: integer ≥ 1}`                         | no       | `[]`              | Macro references, interpolated via `${macro-id}` in `chat_state`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `reevaluation_tools` | list of `{id: string}`                                               | no       | `[]`              | Tool ids that force re-evaluation after they execute (whether they succeed or error)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `relationships`      | object `{priorities: list[Priority], entailments: list[Entailment]}` | no       | `None`            | Priority/entailment overrides — see [Priorities](https://docs.interactive.ai/agents/concepts/priorities.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `current_datetime`   | object `{timezone: string}`                                          | no       | `None` (disabled) | Inject the current date and time into the model's context every turn, rendered in the given IANA timezone (default `UTC`) — see [Built-in tools](https://docs.interactive.ai/agents/reference/built-in-tools.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `variables`          | list of `{name: string, description: string, value: any}`            | no       | `[]`              | Context variables a routine node's `input` or a policy's `tool_arguments` may bind. `value`, when present, is the global value and is rewritten every boot; customer and tag values set through the SDK take precedence. Without `value` the SDK owns every value, the global one included: removing `value` leaves the last written global value in place until you clear it through the API. A name that matches a variable the integration already created through the SDK adopts it, keeping its id and every value; boot fails instead when several variables share the name or the existing one is tool-backed or tagged for another agent. Removing a declaration deletes the variable and its values, adopted ones included. Names are unique and exclude `current_datetime` |

`mcps[]`: either a string, the name of an MCP connection registered in the project (its tools are namespaced under that name), or an object:

| Field      | Type                                 | Required | Default   | Meaning                                                                                                      |
| ---------- | ------------------------------------ | -------- | --------- | ------------------------------------------------------------------------------------------------------------ |
| `ref`      | string (min length 1)                | yes      | —         | Name of the MCP connection registered in the project                                                         |
| `id`       | string (min length 1)                | no       | `ref`     | Namespace prefix applied to this MCP's tools at runtime                                                      |
| `endpoint` | string literal `private` \| `public` | no       | `private` | Endpoint of the MCP the agent connects to; `public` needs a self-hosted MCP with its public endpoint enabled |

The platform resolves each entry into the MCP's address and credential at deploy. A manifest that reaches the agent with an unresolved reference fails boot.

A raw connection object is still accepted but deprecated, and will be removed from the schema. Reference a registered MCP instead:

| Field       | Type                                 | Required | Default           | Meaning                                  |
| ----------- | ------------------------------------ | -------- | ----------------- | ---------------------------------------- |
| `id`        | string                               | yes      | —                 | Namespace prefix for this server's tools |
| `hostname`  | string (`https?://` scheme required) | yes      | —                 | MCP server host, scheme included         |
| `port`      | integer (1–65535)                    | yes      | —                 | TCP port                                 |
| `transport` | string literal `streamable-http`     | no       | `streamable-http` | MCP transport protocol                   |
| `path`      | string (starts with `/`)             | no       | `/mcp`            | MCP endpoint path                        |
| `api_key`   | string (`${VAR}` env-ref)            | no       | `None`            | Bearer credential for this MCP server    |

`search` (`type: external`):

| Field             | Type                                 | Required | Default    | Meaning                                                   |
| ----------------- | ------------------------------------ | -------- | ---------- | --------------------------------------------------------- |
| `type`            | string literal `external`            | no       | `external` | Discriminator                                             |
| `url`             | string (`https?://` scheme required) | yes      | —          | Full endpoint URL the runtime POSTs retrieval requests to |
| `api_key`         | string (`${VAR}` env-ref)            | no       | `None`     | Bearer credential for the endpoint                        |
| `top_k`           | integer (≥ 1)                        | no       | `5`        | Records requested per retrieval                           |
| `max_messages`    | integer (≥ 1)                        | no       | `20`       | Cap on recent messages sent in the request payload        |
| `timeout_seconds` | float (> 0)                          | no       | `5.0`      | HTTP timeout; expiry soft-fails the retrieval             |

`search` (`type: collections` — managed collections over the platform search API):

| Field               | Type                         | Required | Default                             | Meaning                                                                                                                                                                           |
| ------------------- | ---------------------------- | -------- | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`              | string literal `collections` | no       | `collections`                       | Discriminator                                                                                                                                                                     |
| `database`          | string                       | yes      | —                                   | Database hosting the collection                                                                                                                                                   |
| `collection`        | string                       | yes      | —                                   | Collection to query                                                                                                                                                               |
| `operator_base_url` | string                       | no       | `https://deployment.interactive.ai` | Search-API host; override only for non-standard deployments                                                                                                                       |
| `fields`            | list of field objects (≥ 1)  | yes      | —                                   | The query — one entry per search signal (see below)                                                                                                                               |
| `limit`             | integer (1–100)              | no       | `5`                                 | Results returned per retrieval                                                                                                                                                    |
| `history_limit`     | integer (≥ 1)                | no       | `5`                                 | Recent customer messages the per-field prompts see (most-recent last)                                                                                                             |
| `filter`            | object (JSON)                | no       | `{}`                                | Static metadata filter (operators like `$in`/`$gt`/`$or`), applied to every field                                                                                                 |
| `fusion_k`          | integer (≥ 1)                | no       | `60`                                | Rank-fusion constant; used only when more than one field                                                                                                                          |
| `min_score`         | float                        | no       | `None`                              | Drop results scoring below this — enforced platform-side (similarity scale) for a single `vector` field, applied by the agent on the rank-fusion scale (\~1/`fusion_k`) otherwise |
| `exact`             | boolean                      | no       | `false`                             | Exhaustive search, bypassing the approximate index; only valid with a single `vector` field                                                                                       |

Each entry in `fields`:

| Field             | Type                                        | Required | Default | Meaning                                                                                             |
| ----------------- | ------------------------------------------- | -------- | ------- | --------------------------------------------------------------------------------------------------- |
| `name`            | string (identifier, unique across `fields`) | yes      | —       | Field label; for `type: vector` it also names the slot to search unless `slot` is set               |
| `type`            | string enum: `vector`\|`str`                | yes      | —       | `vector` runs a dense lane against a slot; `str` uses the prompt output as a keyword query          |
| `llm_description` | object `{id: string, version: integer ≥ 1}` | yes      | —       | Prompt that turns the conversation into this field's text                                           |
| `slot`            | string (lowercase slot name)                | no       | `name`  | Collection slot this field searches; set it to fuse several fields on one slot (`vector` only)      |
| `candidate_limit` | integer (1–1000)                            | no       | —       | Candidates this field retrieves before fusion; no effect when the search is a single `vector` field |

`vector` fields declare no embedding model or dimension — the agent reads both from the target slot's embedding binding at boot, so a manifest/slot mismatch is impossible by construction.

Authenticates with the agent's existing platform keys; the database's organization and project are resolved automatically at startup.

`database`:

| Field      | Type                                                                             | Required | Default    | Meaning            |
| ---------- | -------------------------------------------------------------------------------- | -------- | ---------- | ------------------ |
| `hostname` | string (bare host, no scheme validation enforced)                                | yes      | —          | Postgres host      |
| `port`     | integer (1–65535)                                                                | no       | `5432`     | Postgres port      |
| `user`     | string                                                                           | no       | `postgres` | Postgres role      |
| `password` | string (`${VAR}` env-ref)                                                        | yes      | —          | Postgres password  |
| `dbname`   | string                                                                           | no       | `postgres` | Database name      |
| `sslmode`  | string enum: `disable`\|`allow`\|`prefer`\|`require`\|`verify-ca`\|`verify-full` | no       | `require`  | Postgres `sslmode` |

`traces`:

| Field                    | Type               | Required | Default      | Meaning                                            |
| ------------------------ | ------------------ | -------- | ------------ | -------------------------------------------------- |
| `deployment_environment` | string             | no       | `production` | OTel `deployment.environment` tag                  |
| `trace_id_field`         | string             | no       | `None`       | Input-payload key naming autonomous traces         |
| `backend`                | object (see below) | no       | `None`       | Custom OTLP backend; omit for the platform default |

`traces.backend`:

| Field            | Type                                 | Required | Default  | Meaning                                     |
| ---------------- | ------------------------------------ | -------- | -------- | ------------------------------------------- |
| `url`            | string (`https?://` scheme required) | no\*     | `None`   | OTLP HTTP traces endpoint                   |
| `api_key`        | string (`${VAR}` env-ref)            | no       | `None`   | Backend credential; requires `url` when set |
| `api_key_scheme` | string enum: `bearer`\|`basic`       | no       | `bearer` | Auth header scheme for `api_key`            |

\* `url` is required for the `backend` block to be meaningful, but only `api_key` enforces the dependency at validation time.

`event_webhook` (outgoing conversational events only):

| Field                        | Type                     | Required | Default | Meaning                                                                                                           |
| ---------------------------- | ------------------------ | -------- | ------- | ----------------------------------------------------------------------------------------------------------------- |
| `url`                        | HTTP(S) URL string       | no       | `None`  | Overrides the SDK's session webhook URL; omit to retain the SDK destination. No embedded credentials or fragment. |
| `include.customer_id`        | boolean                  | no       | `false` | Add the session's customer ID under event `context`                                                               |
| `include.session_metadata`   | list of nonempty strings | no       | `[]`    | Exact metadata keys to include under `context.session_metadata`                                                   |
| `include.customer_variables` | list of nonempty strings | no       | `[]`    | Exact customer variable names to include under `context.customer_variables`                                       |

Missing keys are omitted. Values are read at delivery time; customer variables have no global or tag fallback. With no selected fields, event bodies are unchanged. The runtime API key authenticates delivery. Sessions marked with `autonomous_run_id` or `webhook_match` retain legacy SDK delivery, without overrides or added context; autonomous markers on caller-owned chat sessions persist. Variable names resolve once per flush (lowest variable ID wins duplicate names), while values are refreshed per event.

**Destination trust:** without `url`, selected data is sent to the SDK-controlled per-session webhook destination. Set `url` explicitly when forwarding sensitive customer information. See [SDK integration](https://docs.interactive.ai/agents/guides/integrating-the-sdk.md#configure-delivery-on-the-agent-instead).

`webhooks[]`:

| Field        | Type                                    | Required | Default  | Meaning                                           |
| ------------ | --------------------------------------- | -------- | -------- | ------------------------------------------------- |
| `name`       | string                                  | yes      | —        | URL slug under `POST /webhooks/{name}`            |
| `secret_env` | string (`${VAR}` env-ref)               | yes      | —        | HMAC shared secret                                |
| `header`     | string                                  | yes      | —        | HTTP header carrying the signature                |
| `algorithm`  | string enum: `sha256`\|`sha1`\|`sha512` | no       | `sha256` | HMAC digest algorithm                             |
| `prefix`     | string                                  | no       | `""`     | Literal prefix before the hex digest              |
| `routines`   | list of string (≥ 1)                    | yes      | —        | Autonomous routine ids this webhook dispatches to |

`schedules[]` (requires the `database` block — replicas coordinate each tick through the shared Postgres store, so declaring schedules without a database fails startup):

| Field          | Type                  | Required | Default | Meaning                                                                   |
| -------------- | --------------------- | -------- | ------- | ------------------------------------------------------------------------- |
| `name`         | string                | yes      | —       | Unique schedule id (job keys, logs, traces)                               |
| `routine`      | string                | yes      | —       | Autonomous routine id to fire                                             |
| `cron`         | string (5-field cron) | yes      | —       | Cadence, evaluated in UTC                                                 |
| `input`        | object                | no       | `{}`    | Static routine input, validated against `input_schema` at startup         |
| `callback_url` | string                | no       | `None`  | Optional output sink (standard signed callback); omit for fire-and-forget |
| `max_attempts` | integer (≥ 1)         | no       | `1`     | Execution attempts per tick; `1` = a started run is never re-run          |

Timing semantics: exactly one execution per tick across all replicas. A tick that comes due while no replica is running (an explicit downtime window, a crash) fires once on wake **if** it is still the schedule's most recent due tick; older missed ticks never fire. A brand-new schedule waits for its next natural tick rather than firing its most recent past one at deploy time.

`replay` — replaying recorded conversations against the agent. **Never enable in production**: with it on, a session that carries a replay scenario has its tool calls answered from that scenario's recorded fixtures instead of the real tool service:

| Field     | Type    | Required | Default | Meaning                                                       |
| --------- | ------- | -------- | ------- | ------------------------------------------------------------- |
| `enabled` | boolean | no       | `false` | Serve fixtures for sessions carrying a scenario               |
| `dataset` | string  | no       | `None`  | Default dataset holding scenarios; a request may name another |

Only sessions carrying a scenario are affected — every other session on the same agent calls its tools for real. The engine's own `built-in:` service (`reason`, `emit_output`) is never intercepted, so a replayed conversation still does its real inference and control flow.

## Content document schemas

The documents the manifest references are validated against their own schemas, summarised on their concept pages:

| Document        | Shape defined in                                                                                   | Schema name (JSON Schema artifact) |
| --------------- | -------------------------------------------------------------------------------------------------- | ---------------------------------- |
| Routine         | [Routines](https://docs.interactive.ai/agents/concepts/routines.md)                                | `routines`                         |
| Policy          | [Policies](https://docs.interactive.ai/agents/concepts/policies.md)                                | `policies`                         |
| Glossary        | [Glossaries & macros](https://docs.interactive.ai/agents/concepts/glossaries-and-macros.md)        | `glossaries`                       |
| Macro           | [Glossaries & macros](https://docs.interactive.ai/agents/concepts/glossaries-and-macros.md#macros) | `macros`                           |
| Variable set¹   | [Sessions, memory & state](https://docs.interactive.ai/agents/concepts/memory-and-state.md)        | `variables`                        |
| Manifest itself | this page                                                                                          | `agent-manifest`, `agent-config`   |

¹ Variable sets are platform-catalog documents but are **not referenced from the manifest** — variable values are written per customer at runtime through the SDK.

Field-level tables for the routine and policy documents live on their concept pages. Prerequisite guards live on the manifest under `context.relationships.requires` — not on routine or policy content — see [Prerequisites](https://docs.interactive.ai/agents/concepts/priorities.md#prerequisites-requires).

The JSON Schemas include the cross-field rules prose can't keep honest — step-field mutual exclusions, "exactly one of `over`/`over_all_routines`", a routine node's `tools`/`chat_state`/`think` being mutually exclusive with a routing-only node requiring at least one `transitions` entry — so validating in CI catches authoring errors before deploy.

## Universal validation rules

* Credential-bearing fields accept only `${VAR_NAME}` env-refs (uppercase letters, digits, underscores; not starting with a digit) — literals are rejected at validation time.
* `min_length` enforces a character count only; it does not trim or reject whitespace-only values.
* `id` (manifest): URL-safe — letters, digits, hyphens, underscores only.
* Host fields: MCP hostnames (`mcps[].hostname`, deprecated raw connections) must include an `https?://` scheme. The database hostname (`database.hostname`) is a plain host string with no scheme validation enforced and does not accept a path, port, or query string inline (port is a separate field). The external search endpoint (`search.url` when `type: external`) is a single URL field requiring a scheme.
* Ports: 1–65535. Versions in refs: integers ≥ 1.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.interactive.ai/agents/reference/manifest.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
