Agent wait tool (`agent_wait`)

Canonical URL: /docs/07_ai-agents-and-mcp/17_agent_wait_tool

MCP-backed chat agents (Support Agent, Platform Engineer Agent, Trace AI) can call the agent_wait tool to pause inside an active tool loop without ending the chat turn. Users see a live progress message (and optional countdown fields) while the agent waits for external work to settle.

Document information

Field	Value
Version (published date)	`2026-05-25`
Tags	`ai`, `mcp`, `agents`, `tool-loop`

What it does

Behavior	Description
In-loop pause	The agent calls `agent_wait`, the platform sleeps for a bounded number of seconds, then returns a tool result so the model can continue with more tools in the same user message.
User feedback	Parameter `user_message` is shown in the chat progress panel. During streaming, the UI may receive periodic `tool_progress` updates with remaining time.
Policy caps	Deployments enforce per-call max seconds, per-turn total wait, max calls per turn, and a per-user rate limit (see operations below).

When agents should use it

Use `agent_wait`	Use something else
Short gap between arbitrary tool steps (rate limits, queue drain, “let external system catch up”)	`execute_tenant_integration` when waiting for a configured integration run to finish
Bounded delay before the next lookup or write	Ending the turn with “I’ll check back later” (stops the tool loop)
Transparent pause with a clear user-facing message	Shell `sleep` or ad-hoc command-runner delays

Tool parameters

Parameter	Required	Description
`seconds`	Yes	Integer seconds to wait (capped by deployment policy, typically 1–60 per call).
`user_message`	Yes	Plain-language status shown to the user while waiting (present tense).
`reason`	No	Optional internal note for audit logs.

Models may also set progress_indicator on any tool call (including agent_wait); the chat runtime uses it for progress text when present.

Example (conceptual)

{
  "action": "agent_wait",
  "progress_indicator": "Waiting for the webhook queue to drain before fetching results.",
  "parameters": {
    "seconds": 20,
    "user_message": "Waiting for the webhook queue to drain before fetching results."
  }
}

After the wait completes, the tool result includes waited_seconds and resume_at. The agent should then call the next tool or give a final answer.

Streaming events

When chat streaming is enabled, the client may receive:

SSE type	When
`tool_call`	Wait starts
`tool_progress`	Initial message and ~1s heartbeats with optional `remaining_seconds`, `wait_until`
`tool_result`	Wait finished
`chunk` / `complete`	Final assistant reply

See Platform Agent SSE contract for field details.

Operations and configuration

Requires TOOL_CALL_LOOP_ENABLED=1 on the API deployment and the agent_wait row active in mcp_resources (migration 122_add_agent_wait_mcp_tool.sql).

Environment variable	Typical default	Purpose
`AGENT_WAIT_ENABLED`	`true`	Kill switch for the handler
`AGENT_WAIT_MAX_SECONDS_PER_CALL`	`7200` (2h)	Max seconds per invocation (capped by chat turn budget)
`AGENT_WAIT_MAX_SECONDS_PER_TURN`	`14400` (4h)	Max total wait per user message / tool loop
`CHAT_AGENT_TURN_TIMEOUT_MS`	`14400000` (4h)	Overall turn wall clock (parent budget for waits and tools)
`AGENT_WAIT_MAX_CALLS_PER_TURN`	`5`	Max `agent_wait` calls per loop
`AGENT_WAIT_HEARTBEAT_INTERVAL_MS`	`1000`	Progress heartbeat interval
`AGENT_WAIT_RATE_LIMIT_PER_USER_PER_MINUTE`	`30`	Abuse guard per user

Full list: backend-next configuration guide.

Limitations

Waits are synchronous inside the HTTP request handling the chat turn. Multi-hour waits are supported when CHAT_AGENT_TURN_TIMEOUT_MS and your reverse proxy allow it; use async integrations when work should continue after the HTTP connection closes.
Per-user rate limiting uses an in-process counter on each API instance (sufficient for typical single-node or low fan-out; not a global cluster quota).
Each agent_wait consumes one tool-loop iteration toward TOOL_CALL_MAX_ITERATIONS.

Agent wait tool (agent_wait)