Agent runtime

A Console agent is more than one request and one answer. Behind Build → Agents sits a runtime that keeps a conversation as a session, writes everything that happens in it to an event log, can pause for a person, stop at a budget, hold files in a bucket you choose, run in the background, and tell your own systems about it with signed webhooks.

This section documents that runtime end to end: what each part is, where its switches are in Studio, what the client API looks like, and what the errors mean. Every claim here comes from the control plane's code; where an older document and the code disagreed, the code won.

Two ways to read this section

Operators and agent authors want the Guide pages — the Studio click-path, every setting with its default, and what it changes. Integrators want the API pages (Agent sessions, Webhooks, Agents). Each Guide page carries the same calls as curl and as @cognipeer/console-sdk so you can copy either.

The pieces

Concept	What it is	Page
Session	One conversation with an agent: its messages, files, spend and what it is doing now. The `{id}` in `resp_{id}` is the session id.	Sessions
Turn	One user message and everything the agent does until it answers or stops.	Session events
Event log	An append-only record of every turn: messages, tool calls, requests for a person, spend. Readable afterwards or followed live.	Session events
Action	A request that pauses a turn until someone answers it: a tool approval, a question, or a tool that runs in the host page.	Approvals & questions
Session budget	A cap on what the whole session may spend, with a choice between pause and stop.	Session budgets
Session file	A document or image attached to a session, stored in a Document Store bucket you chose.	Session files
Run	A turn that was queued with `background: true` instead of holding the HTTP call open.	Background runs
Webhook	A signed, retried HTTP call from Console to your URL when something above happens.	Webhooks
Feedback	What a chat surface (a portal, an embedded widget, your own client) builds on an agent: thumbs, titles, regenerate and edit.	Feedback & message actions

                        ┌─────────────── session ───────────────┐
 user message ─► turn ──┤  event log   (every step, 30 days)    │──► SSE / poll
                  │     │  files       (your bucket)            │
                  │     │  budget      (pause / stop)           │
                  │     └───────────────────────────────────────┘
                  │
                  ├─► tool needs approval / agent asks a question
                  │        └─► requires_action ──► person answers ──► turn carries on
                  │
                  ├─► session budget reached ──► budget_paused ──► raise it ──► turn carries on
                  │
                  └─► end_turn / limit / cancelled / error ──► idle
                           │
                           └──► webhooks: session.idled, action.required, budget.reached, agent_run.*, …

A turn that pauses is not lost. Whether it waited for a person or for a budget, the same turn carries on from where it stopped when the request is answered.

Where the switches are

Open Build → Agents, then an agent. Its tabs are Overview, Sessions, Build, Ship, Feedback and Usage. The runtime's settings live in the Build tab, as sections of one page that one Save Configuration button writes.

Build section	What it controls	Stored as	Takes effect
Execution	Synchronous timeout, session budget, background runs, default callback	`config.execution`	Immediately — no publish needed
Files	Whether people can attach files, which bucket, limits, how images are read	`config.attachments`	With the version that runs: the draft in Studio, the published version for API and portal traffic
Approvals & questions	Tool approvals, questions, timeouts, who may answer	`config.humanInTheLoop`	Same — publish again for API and portal traffic

Draft versus published

POST /api/client/v1/agents/responses and portals run the published version of an agent; POST /api/client/v1/responses and the Studio playground run the draft. Files, approvals and experience settings travel with the version, so a change you save in Build reaches API and portal callers only after you publish again. Execution settings are the exception: they are operational and are read from the live agent. See Build and publish an agent for the publish flow.

Two places live outside the agent page:

Build → Agents → Webhooks (/dashboard/agents/webhooks) manages webhook endpoints. They belong to a project or the whole tenant, not to one agent.
Data → Document Store holds the buckets that session files are stored in, and Model Hub holds the input types that decide whether a model is shown images.

Conventions the client API follows

Convention	Detail
Base path and auth	`https://<your-host>/api/client/v1` with `Authorization: Bearer cpeer_…`. A token sees only its own project.
Field names	The agent family — Responses, runs, sessions, events, actions, session files — is `snake_case` (`stop_reason`, `required_action`, `max_cost_usd`). Webhook endpoint objects and webhook event payloads are `camelCase` (`projectId`, `conversationId`). The dashboard's own `/api/…` routes are `camelCase`. Tool `args` and free-form `answers` are never re-keyed.
Identifiers	Response `resp_{conversationId}`, run `run_{id}`, action `act_{id}`, webhook event `evt_{id}`, webhook secret `whsec_…`. A session's `id` is the bare conversation id, with no prefix.
Errors	`{ "error": { "type": "…", "code": "…", "message": "…" } }`, with extra snake_case fields where they help (`pending_action_ids`, `spent_usd`, `max_cost_usd`, `action_status`). A few older Responses errors — a missing `model`, an unknown agent — still answer `{ "error": "message" }`; branch on the status code there.
Unknown values	New event types, stop reasons and webhook events can appear in later releases. Ignore the ones you do not know.

The SDK's responses.create runs the draft

client.agents.responses.create() in @cognipeer/console-sdk calls POST /api/client/v1/responses, which runs the draft version. To exercise the published version from code, call POST /api/client/v1/agents/responses directly (the curl tab on these pages does). Everything else — sessions, events, actions, files, webhooks — is the same for both.

Statuses at a glance

Where	Values	Meaning
Session `runtime_status`	`idle`, `running`, `requires_action`, `budget_paused`	What the session is doing now. `idle` includes a session that has never run.
Session / event `stop_reason`	`end_turn`, `requires_action`, `limit`, `cancelled`, `error`, `budget_reached`	Why the last turn stopped.
Response `status`	`completed`, `incomplete`, `requires_action`	`incomplete` = a limit, a cancel or the session budget ended the turn before a final answer. A Responses `stop_reason` of a normal answer is `completed`; the session's is `end_turn`.
Run `status`	`queued`, `running`, `requires_action`, `succeeded`, `failed`, `canceled`	`requires_action` is the one non-terminal state besides `queued` and `running`.
Pending action `status`	`pending`, `resolved`, `expired`, `cancelled`	An action is answered at most once.

Defaults and limits

What	Value	Where to change it
Session events kept	30 days	`AGENT_SESSION_EVENT_RETENTION_DAYS`
Event `data` size	16 KB, then truncated with `_truncated: true`	—
Synchronous call ceiling	600 s	`AGENT_SYNC_TIMEOUT_MS`, and the agent's Execution setting (it can only lower it)
Background run ceiling	30 min	`AGENT_BACKGROUND_MAX_DURATION_MS`, and the agent's Execution setting
Concurrent background runs per tenant	10	`AGENT_BACKGROUND_MAX_CONCURRENT_RUNS_PER_TENANT`
Background runs kept	30 days	`AGENT_RUN_RETENTION_DAYS`
Approval waits	1440 min (a day), `0` = never	Approvals & questions
Session files	10 per session, 20 MB each, kept 30 days	Files
Webhook delivery	8 attempts over about two days, 10 s timeout	Environment, see Webhooks
Webhook endpoints	50 per tenant	—

What's new

The agent runtime release (October 2026) adds, in one go:

the session event log with a poll endpoint and a resumable Server-Sent-Events stream, and a live Activity tab in Studio;
human in the loop: tool approvals, questions to the user, tools that run in the embedding page, a requires_action Responses status, and input-required over A2A;
session budgets with pause and stop, client overrides, and tenant spend limits that now count agent spend;
webhooks under Build → Agents → Webhooks, with signing, retries, redelivery and secret rotation;
session files stored in a bucket of your project, images that travel by reference, and a view_image tool;
the sessions API: create an empty session, upload, ask, list, delete — and session_id on the Responses API;
model input types in the Model Hub, so an image is only sent to a model that reads images;
a snake_case client wire for everything in the agent family, and a rewritten OpenAPI specification.

An agent that uses none of it behaves as before: without approvals it never pauses, without a budget it never stops on one, and without a bucket it takes no attachments. The one thing to check is a client that sends input_file or input_image parts by habit — those used to be ignored and are now either used or refused, see Session files.

Agent runtime ​

The pieces ​

Where the switches are ​

Conventions the client API follows ​

Statuses at a glance ​

Defaults and limits ​