Skip to content

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 wantSet upThe session waits on
Your user signs off on something the agent proposesA client tool, such as request_approvalagent.custom_tool_use
Your user reviews an app’s work before it continuesA workflow app with a review gateagent.gate
  1. 1Askagent.custom_tool_use / agent.gateThe agent calls your tool, or the app opens a gate
  2. 2Waitrequires_actionThe session goes idle and lists what it waits on in pending
  3. 3ShowYour UI shows the question to your user
  4. 4Answeruser.tool_result / user.gate_verdictYou send the answer with its invocation_id
  5. 5Continuesession.status_runningThe work picks up where it stopped
Until you answer, the turn is suspended. It has not finished and it has not failed.

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.

Terminal window
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"]
}
} ]
}'

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:

Terminal window
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"'"
} ] }'

result can be any JSON. The agent reads it as is, so approve, revise and cancel are whatever your tool says they are.

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:

Terminal window
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"'"
} ] }'

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.

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:

  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.

  • 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.