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

# Session metadata

The keys the agent reads or writes on session.metadata, who owns each, and how they surface in traces.

> **Context** — `session.metadata` is one JSON object per session, shared between your integration and the agent. You may store anything in it; this page lists the keys the agent itself reads or writes, so the two never collide.

## Ownership

| Keys                                                                                                                                                                                                                                                                 | Owner     | Rule                                                                                                                                                                                                                 |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `event_webhook_url`, `session_key`                                                                                                                                                                                                                                   | you       | Set them at session creation (or via the metadata update endpoint) to opt into the behaviour each one drives.                                                                                                        |
| `agent_autonomous_session`, `agent_glossary_log`, `agent_handoff`, `agent_scenario_session`, `autonomous_run_id`, `event_webhook_hwm`, `max_engine_iterations_reached`, `max_engine_iterations_value`, `routine_id`, `step_outputs`, `webhook_match`, `webhook_name` | the agent | Runtime state the agent writes during a conversation or an autonomous run. Setting one of these yourself is accepted — existing integrations keep working — but logged as a warning, and the agent may overwrite it. |
| `agent_*`                                                                                                                                                                                                                                                            | the agent | Reserved for future agent-written keys; never use this prefix for your own.                                                                                                                                          |

Every other key is yours and is never read, written, or interpreted by the agent. Keys and values are persisted with the session and returned verbatim by the sessions API.

## Where the keys surface

* `session_key` names the conversation in traces: the trace name is `<agent>: <session_key> (turn: N)` and every turn of the conversation groups under the session `<agent>: <session_key>`. Without it the first 8 characters of the opaque session id are used.
* `event_webhook_url` turns on real-time delivery of [conversation events](https://docs.interactive.ai/agents/reference/events-and-callbacks.md) to that URL, unless `agent_config.event_webhook.url` overrides the destination. Selected metadata keys can also be included through `event_webhook.include.session_metadata`.
* Each trace carries a `session` block (`{id, key, kind}`) and a `trigger` block derived from these keys — see the observability guide.

### Fields

The keys on `session.metadata` that carry meaning for the agent; every other key is the integration's and passes through untouched.

| Field                           | Type          | Required | Default | Description                                                                                                                                                                                                                                                                                                                                                                                                      |
| ------------------------------- | ------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `session_key`                   | string        | no       | `null`  | Integration-set stable identifier for the conversation (a ticket id). Names the trace and groups its turns into one session; the server-generated session id is opaque.                                                                                                                                                                                                                                          |
| `event_webhook_url`             | string        | no       | `null`  | Integration-set URL that receives each conversation event as it is emitted, in addition to the polling stream.                                                                                                                                                                                                                                                                                                   |
| `event_webhook_hwm`             | integer       | no       | `null`  | Engine: offset of the last event delivered to event\_webhook\_url.                                                                                                                                                                                                                                                                                                                                               |
| `autonomous_run_id`             | string        | no       | `null`  | Engine: marks the session as hosting an autonomous routine run.                                                                                                                                                                                                                                                                                                                                                  |
| `routine_id`                    | string        | no       | `null`  | Engine: the routine an autonomous run executes.                                                                                                                                                                                                                                                                                                                                                                  |
| `agent_autonomous_session`      | boolean       | no       | `null`  | Engine: the session exists only to host an autonomous run (one the run created, or a replay's), so it is not a conversation. A chat session an API trigger reuses keeps it unset.                                                                                                                                                                                                                                |
| `agent_scenario_session`        | object        | no       | `null`  | Engine: the replay scenario a session was started from in the agent UI — {dataset, scenario, kind, script, expect, run\_id?} — so the UI can show its script and check the session against it.                                                                                                                                                                                                                   |
| `webhook_match`                 | boolean       | no       | `null`  | Engine: marks the short-lived session the webhook matcher reasons in; deleted after the delivery is dispatched.                                                                                                                                                                                                                                                                                                  |
| `webhook_name`                  | string        | no       | `null`  | Engine: the manifest webhook a matcher session belongs to.                                                                                                                                                                                                                                                                                                                                                       |
| `step_outputs`                  | object        | no       | `null`  | Engine: think-step outputs of an autonomous run, keyed by step id, read by downstream steps.                                                                                                                                                                                                                                                                                                                     |
| `agent_handoff`                 | object        | no       | `null`  | Engine: human-handoff intent recorded by built-in:initiate\_human\_handoff — {reason, internal\_note, customer\_message, silent, metadata}. Written once per session (first write wins). internal\_note is staff-facing; customer\_message was already emitted as the turn's reply (or nothing was, when silent). The integration attaches the note and commits channel-side effects on the turn's ready status. |
| `agent_glossary_log`            | list\[object] | no       | `null`  | Engine: the glossary terms the conversation has retrieved, in the order they entered it — \[{term\_id, anchor}], anchor being the offset of the last event when the term entered. Prompts show each term from that point of the conversation on.                                                                                                                                                                 |
| `max_engine_iterations_reached` | boolean       | no       | `null`  | Engine: the turn hit the per-turn iteration cap.                                                                                                                                                                                                                                                                                                                                                                 |
| `max_engine_iterations_value`   | integer       | no       | `null`  | Engine: the cap that was hit.                                                                                                                                                                                                                                                                                                                                                                                    |


---

# 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/session-metadata.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.
