> 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/environment.md).

# Environment variables

Environment configuration the platform sets on the agent: manifest env-refs (secrets) and fixed-name operator knobs, with defaults.

> **Context** — The platform sets two kinds of environment configuration on the agent at deploy time: **manifest env-refs** (the `${VAR}` placeholders your manifest declares — names are yours to choose) and **operator variables** (fixed names that tune runtime behaviour). Generated from the runtime source of truth for version `1.4.0` (manifest schema 1.4.0).

## Manifest env-refs (secrets)

Every credential-bearing manifest field takes a `${VAR_NAME}` reference; the platform supplies the value from the secret bundle your manifest declares (see [Deploying](https://docs.interactive.ai/agents/guides/deploying.md)). **Required** fields abort boot when the variable is unset (the error names it); optional fields resolve to unset. Webhook secrets are re-read per request (rotation without restart) — all others resolve once at boot.

| Manifest field                                 | Required           | Purpose                                                                                                                                                               |
| ---------------------------------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `agent_config.database.password`               | when block present | `${VAR}` env-ref for the Postgres password.                                                                                                                           |
| `agent_config.interactive_platform.public_key` | yes                | `${VAR}` env-ref for the InteractiveAI public key.                                                                                                                    |
| `agent_config.interactive_platform.secret_key` | yes                | `${VAR}` env-ref for the InteractiveAI secret key.                                                                                                                    |
| `agent_config.llms.api_key`                    | yes                | `${VAR}` env-ref for the InteractiveAI LLM router API key.                                                                                                            |
| `agent_config.mcps[].api_key`                  | no                 | `${VAR}` env-ref for the MCP server's API key. Sent as `Authorization: Bearer`. Omit when the server doesn't require auth.                                            |
| `agent_config.runtime.api_key`                 | yes                | Token callers must send to reach this agent, and that the agent sends back on its own autonomous callbacks. Must be a `${VAR}` env-ref — literal values are rejected. |
| `agent_config.search (type: external).api_key` | no                 | `${VAR}` env-ref for the endpoint API key. Sent as `Authorization: Bearer`. Omit when the endpoint requires no auth.                                                  |
| `agent_config.traces.backend.api_key`          | no                 | `${VAR}` env-ref for the traces backend API key. Sent per `api_key_scheme`. Omit for endpoints that don't require auth.                                               |
| `agent_config.webhooks[].secret_env`           | when block present | `${VAR}` env-ref for the HMAC shared secret. Re-read per request, so rotation picks up without restart.                                                               |

Conventional variable names (`AGENT_API_KEY`, `ROUTER_API_KEY`, `INTERACTIVEAI_PUBLIC_KEY`, `INTERACTIVEAI_SECRET_KEY`, `DB_PASSWORD`, `EXTERNAL_SEARCH_KEY`, …) are just convention — the manifest is the source of truth for which names it references.

## Operator variables

Fixed-name knobs that tune runtime behaviour, set by the platform or operator at deploy time. All optional.

| Variable                         | Default  | Purpose                                                                                                                                                                                                                                                         |
| -------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ROUTER_MAX_TOKENS`              | `100000` | Token ceiling per LLM-router call (context window cap).                                                                                                                                                                                                         |
| `SHUTDOWN_DRAIN_TIMEOUT_SECONDS` | `120`    | On SIGTERM, seconds to wait for in-flight engine turns, autonomous callbacks, and event webhooks to finish before the process exits. MUST be below the K8s terminationGracePeriodSeconds (minus the \~10s HTTP connection-drain) or SIGKILL hits mid-drain.     |
| `LLM_PROVIDER_ORDER`             | unset    | Comma-separated provider slugs pinning which upstream providers serve all inference models (chat and evaluation), in preference order. Fallbacks are allowed: a request degrades to other providers when the pinned ones can't serve the model. Unset = no pin. |
| `AGENT_NAME`                     | unset    | Agent deployment name, set by the platform from the Helm release name. Identity falls back to the manifest name when unset.                                                                                                                                     |
| `AGENT_REVISION`                 | unset    | Helm release revision for this agent deploy, the UI #N. Unset outside Kubernetes.                                                                                                                                                                               |

## Fixed runtime facts (not configurable via env)

* HTTP listen port: `8080`.
* Startup failures exit the process non-zero within `10` seconds.
* Model ids are manifest-only (`agent_config.llms.*`) — there is no env-var override. See [Models](https://docs.interactive.ai/agents/concepts/models.md).


---

# 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/environment.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.
