Approvals and review
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, such as request_approval | agent.custom_tool_use |
| Your user reviews an app’s work before it continues | A workflow app with a review gate | agent.gate |
How a pause works
Section titled “How a pause works”- 1Ask
agent.custom_tool_use / agent.gateThe agent calls your tool, or the app opens a gate - 2Wait
requires_actionThe session goes idle and lists what it waits on in pending - 3ShowYour UI shows the question to your user
- 4Answer
user.tool_result / user.gate_verdictYou send the answer with its invocation_id - 5Continue
session.status_runningThe work picks up where it stopped
Set up an approval with a client tool
Section titled “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 -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"] } } ] }'import jsonimport 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,)const BASE = "https://agents.lumalabs.ai/v1";
async function post( path: string, body: unknown, token: string, headers: Record<string, string> = {},) { 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 -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"'" } ] }'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,)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
Section titled “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 -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"'" } ] }'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,)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.
Read what is waiting
Section titled “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.
{ "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:
- Answer by
invocation_id, never byevent_id. - Send the event type that
answer_typenames. Don’t work it out fromkind. - Answer every item, including ones you can’t handle. For a tool call you can’t run, send
{ "error": "…" }as theresult. 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
Section titled “Details”pendingitems can also carryrun_id(the run they belong to) andexpires_at(when they stop being answerable).- Two other kinds can appear:
consent, answered byquote_idwithuser.consent, andconnector_action, answered byaction_idwithuser.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_INVOCATIONmeans 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 acallback_url. Webhook calls never appear inpending.
- Tools: call your code: everything a client tool can do.
- Workflow apps: start an app and follow it.