--- title: Approvals and review | Luma Agents description: Read what a session is waiting on, answer each action, and approve a workflow app's review steps. --- A session pauses for a person only when you set it up to. You do that in one of two ways: declare a client tool that your UI answers, or run a workflow app that has a review step. Without either, the agent works through the brief and finishes on its own. | You want | Set up | The session waits on | | --------------------------------------------------- | ------------------------------------------------------------------- | ----------------------- | | Your user signs off on something the agent proposes | A [client tool](/agents/tools/index.md), such as `request_approval` | `agent.custom_tool_use` | | Your user reviews an app’s work before it continues | A [workflow app](/agents/workflow-apps/index.md) with a review gate | `agent.gate` | ## How a pause works 1. 1**Ask**`agent.custom_tool_use / agent.gate`The agent calls your tool, or the app opens a gate 2. 2**Wait**`requires_action`The session goes idle and lists what it waits on in pending 3. 3**Show**Your UI shows the question to your user 4. 4**Answer**`user.tool_result / user.gate_verdict`You send the answer with its invocation\_id 5. 5**Continue**`session.status_running`The work picks up where it stopped Until you answer, the turn is suspended. It has not finished and it has not failed. ## Set up an approval with a client tool Declare a tool on the session with `"invocation": "client"`, and describe when the agent should call it. The agent decides from the description, so say exactly when approval is needed. - [cURL](#tab-panel-0-0) - [Python](#tab-panel-0-1) - [TypeScript](#tab-panel-0-2) ```bash curl -s -X POST https://agents.lumalabs.ai/v1/sessions \ -H "Authorization: Bearer $SESSION_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "scope_id": "'"$WORKSPACE_ID"'", "tools": [ { "name": "request_approval", "description": "Show the user the proposed images and ask them to approve before you make any video. Returns approved: true or false, with notes.", "invocation": "client", "parameters": { "type": "object", "properties": { "asset_ids": { "type": "array", "items": { "type": "string" } } }, "required": ["asset_ids"] } } ] }' ``` ```python import json import urllib.request BASE = "https://agents.lumalabs.ai/v1" def post(path, body, token, headers=None): request = urllib.request.Request( BASE + path, method="POST", data=json.dumps(body).encode(), headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json", **(headers or {})}, ) with urllib.request.urlopen(request) as response: return json.load(response) session = post( "/sessions", { "scope_id": workspace_id, "tools": [{ "name": "request_approval", "description": "Show the user the proposed images and ask them to approve before you make any video. Returns approved: true or false, with notes.", "invocation": "client", "parameters": { "type": "object", "properties": {"asset_ids": {"type": "array", "items": {"type": "string"}}}, "required": ["asset_ids"], }, }], }, session_token, ) ``` ```typescript const BASE = "https://agents.lumalabs.ai/v1"; async function post( path: string, body: unknown, token: string, headers: Record = {}, ) { const response = await fetch(BASE + path, { method: "POST", headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json", ...headers, }, body: JSON.stringify(body), }); if (!response.ok) throw new Error(`${response.status} ${await response.text()}`); return response.json(); } const session = await post( "/sessions", { scope_id: workspaceId, tools: [ { name: "request_approval", description: "Show the user the proposed images and ask them to approve before you make any video. Returns approved: true or false, with notes.", invocation: "client", parameters: { type: "object", properties: { asset_ids: { type: "array", items: { type: "string" } }, }, required: ["asset_ids"], }, }, ], }, sessionToken, ); ``` Always send `"invocation": "client"`. It defaults to `webhook`, which sends the call to your server instead of the stream, so your UI would never see it. When the agent calls the tool, an `agent.custom_tool_use` arrives on the stream with `tool`, `params` and an `invocation_id`. Show the question, then send your user’s answer: - [cURL](#tab-panel-1-0) - [Python](#tab-panel-1-1) - [TypeScript](#tab-panel-1-2) ```bash curl -s -X POST https://agents.lumalabs.ai/v1/sessions/$SESSION_ID/events \ -H "Authorization: Bearer $SESSION_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "events": [ { "type": "user.tool_result", "invocation_id": "'"$INVOCATION_ID"'", "result": { "approved": false, "notes": "Warmer light, and lose the second loaf." }, "idempotency_key": "tool-'"$INVOCATION_ID"'" } ] }' ``` ```python post( f"/sessions/{session_id}/events", {"events": [{ "type": "user.tool_result", "invocation_id": invocation_id, "result": {"approved": False, "notes": "Warmer light, and lose the second loaf."}, "idempotency_key": f"tool-{invocation_id}", }]}, session_token, ) ``` ```typescript await post( `/sessions/${sessionId}/events`, { events: [ { type: "user.tool_result", invocation_id: invocationId, result: { approved: false, notes: "Warmer light, and lose the second loaf.", }, idempotency_key: `tool-${invocationId}`, }, ], }, sessionToken, ); ``` `result` can be any JSON. The agent reads it as is, so approve, revise and cancel are whatever your tool says they are. ## Review an app’s work A workflow app that wants a person’s decision opens a review gate. An `agent.gate` event arrives, and its `invocation_id` is at `interaction.invocation_id`. Answer with a `user.gate_verdict`: - [cURL](#tab-panel-2-0) - [Python](#tab-panel-2-1) - [TypeScript](#tab-panel-2-2) ```bash curl -s -X POST https://agents.lumalabs.ai/v1/sessions/$SESSION_ID/events \ -H "Authorization: Bearer $SESSION_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "events": [ { "type": "user.gate_verdict", "invocation_id": "'"$INVOCATION_ID"'", "verdict": { "verdict": "revise", "notes": "Keep the palette, raise the headline contrast." }, "idempotency_key": "gate-'"$INVOCATION_ID"'" } ] }' ``` ```python post( f"/sessions/{session_id}/events", {"events": [{ "type": "user.gate_verdict", "invocation_id": invocation_id, "verdict": {"verdict": "revise", "notes": "Keep the palette, raise the headline contrast."}, "idempotency_key": f"gate-{invocation_id}", }]}, session_token, ) ``` ```typescript await post( `/sessions/${sessionId}/events`, { events: [ { type: "user.gate_verdict", invocation_id: invocationId, verdict: { verdict: "revise", notes: "Keep the palette, raise the headline contrast.", }, idempotency_key: `gate-${invocationId}`, }, ], }, sessionToken, ); ``` The shape of `verdict` belongs to the app. In this app, `revise` asks for another attempt and `proceed` accepts the work. Read what an app accepts from `GET /v1/apps/{slug}/artifact-schema` and `GET /v1/apps/{slug}/surface-template` before you build its review screen. A revise produces a new sample and a new gate with a new `invocation_id`. Answer that one in turn. In a session with no app, the agent can start an app itself when your API key can run apps. It may then answer that app’s gate for your user, but only after your user has sent a message since the gate was shown. To keep these decisions with your user, turn the app tools off (see [Tools](/agents/tools/index.md)). ## Read what is waiting When the session pauses, `session.status_idle` arrives with `stop_reason.type: "requires_action"` and a `pending` list. The same list is on `GET /v1/sessions/$SESSION_ID`, so a client that connects late sees it too. ```json { "type": "session.status_idle", "stop_reason": { "type": "requires_action", "pending": [ { "kind": "custom_tool", "invocation_id": "toolu_01…", "answer_type": "user.tool_result" }, { "kind": "gate", "run_id": "4265445c-…", "invocation_id": "toolu_02…", "answer_type": "user.gate_verdict" } ] } } ``` Three rules cover every answer: 1. Answer by `invocation_id`, never by `event_id`. 2. Send the event type that `answer_type` names. Don’t work it out from `kind`. 3. Answer every item, including ones you can’t handle. For a tool call you can’t run, send `{ "error": "…" }` as the `result`. An item you never answer holds the turn until its deadline or the end of the session. Answering one item of two sends a new `session.status_idle` listing the one left. When the last is answered, the session goes back to running. ## Details - `pending` items can also carry `run_id` (the run they belong to) and `expires_at` (when they stop being answerable). - Two other kinds can appear: `consent`, answered by `quote_id` with `user.consent`, and `connector_action`, answered by `action_id` with `user.connector_action`. Skip a kind your code doesn’t handle rather than failing to parse the list. - An answer of the wrong type is refused with `422 TOOL_RESPONSE.INVALID_TOOL_KIND`, and the item stays pending. - `TOOL_RESPONSE.UNKNOWN_INVOCATION` means nothing waits for that answer any more: an old gate, a gate the agent already answered, or a call from a turn Luma retried. Don’t resend it. - A verdict the gate doesn’t accept is rejected with `GATE.INVALID_RESULT`. - If approvals come from your backend rather than a person in your UI, declare the tool with `"invocation": "webhook"` and a `callback_url`. Webhook calls never appear in `pending`. ## Next - [Tools: call your code](/agents/tools/index.md): everything a client tool can do. - [Workflow apps](/agents/workflow-apps/index.md): start an app and follow it.