> 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 > **Context** — This page is the navigational map of the manifest as of **manifest schema 7.0.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](/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) endpoint: false # platform flag: provision a public URL? secrets: # platform secret bundles to inject as env vars - secret_name: driveaway-agent-secrets 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 # ── 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: # router-side alternates, ordered - 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) 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 startup: interactive/google/gemini-3.1-pro-preview # boot-time routine evaluation policy_matching: interactive/google/gemini-3-flash-preview routine_navigation: interactive/google/gemini-3.1-pro-preview # ── 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 relationships: # ─────────── concepts/priorities.md priorities: - higher: policy:incident-handoff over_all_routines: true entailments: - when: policy:self-exclusion-request also_apply: - policy:rg-tone # ── Tool servers ─────────────────────────────── concepts/tools.md mcps: - id: cars hostname: http://cars-mcp.agents.svc.cluster.local port: 8765 transport: streamable-http path: /mcp # endpoint path; defaults to /mcp api_key: ${CARS_MCP_KEY} # ── Retrieval grounding (one of two types) ───── concepts/knowledge-base.md search: type: pgvector # or: type: external hostname: kb-postgres.internal.example.com port: 5432 password: ${KB_PG_PASSWORD} collection: support_articles embedding_model: interactive/openai/text-embedding-3-small embedding_dimensions: 1536 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 ``` 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](/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) | | `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 | `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 | `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](/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 a single free-text language name/instruction passed to the model verbatim | | `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](/agents/concepts/priorities.md) | `mcps[]`: | 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: pgvector` — [Knowledge base](/agents/concepts/knowledge-base.md)): | Field | Type | Required | Default | Meaning | | ---------------------- | -------------------------------------------------------------------------------- | -------- | ---------- | --------------------------------------------------- | | `type` | string literal `pgvector` | no | `pgvector` | Discriminator | | `hostname` | string (bare host, no scheme validation enforced) | yes | — | Postgres host | | `port` | integer (1–65535) | yes | — | 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` | | `collection` | string (SQL-identifier pattern, optionally schema-qualified) | yes | — | pgvector table name | | `content_key` | string | no | `content` | JSONB metadata key holding the document body | | `metadata_filter` | object (JSON) | no | `{}` | Fixed JSONB filter applied to every search | | `embedding_model` | string | yes | — | Embedding model, `provider/model` form | | `embedding_dimensions` | integer (≥ 1) | yes | — | Must match the collection's vector column dimension | | `top_k` | integer (≥ 1) | no | `5` | Articles returned per retrieval | | `prompt` | object `{id: string, version: integer ≥ 1}` | no | `None` | Extra instructions for the query-rewrite call | `search` (`type: external`): | Field | Type | Required | Default | Meaning | | ----------------- | ----------------------------------------------- | -------- | ---------- | -------------------------------------------------- | | `type` | string literal `external` | no | `external` | Discriminator | | `hostname` | string (scheme optional, defaults to `http://`) | yes | — | Search endpoint host | | `port` | integer (1–65535) | yes | — | Endpoint port | | `path` | string (starts with `/`) | yes | — | HTTP path the runtime POSTs 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 | `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. `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 | ## 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](/agents/concepts/routines.md) | `routines` | | Policy | [Policies](/agents/concepts/policies.md) | `policies` | | Glossary | [Glossaries & macros](/agents/concepts/glossaries-and-macros.md) | `glossaries` | | Macro | [Glossaries & macros](/agents/concepts/glossaries-and-macros.md#macros) | `macros` | | Variable set¹ | [Sessions, memory & state](/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. 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. * Hostname fields: MCP hostnames (`mcps[].hostname`) must include an `https?://` scheme. Database and knowledge-base hostnames (`database.hostname`, `search.hostname` when `type: pgvector`) are plain host strings with no scheme validation enforced. None accept paths, ports, or query strings inline (ports are separate fields, and MCP endpoint paths use the optional `path` field). * 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.interactive.ai/agents/reference/manifest.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.