Approvals & questions

Interactions pause an agent when it needs a person to approve an action or answer a question. The agent resumes when someone responds; if the current work is canceled, the interaction is canceled too. There are two kinds:

`interaction_kind`	Created when	Typical form
`permission`	A tool with `always_ask` permission is called	”Permission requested for run_command” with Allow/Deny
`question`	The agent uses the `ask_question` built-in tool	Whatever the agent wants to know, with options it composed

Both ride on the same tool-call machinery: the parent tool call waits while the interaction is open. An interaction ends in one of two states — resolved (someone answered) or canceled (the work it guarded was canceled, superseded, or archived).

export BASE="$OMNARA_API/orgs/$ORG/projects/$PROJ"
export AGENT="agt_v4qtrwz3jehcyd5n6a2bfgik7m"

Find open interactions

API
Dashboard

The examples assume the client, $ORG/orgID, and $PROJ/projectID setup from the quickstart, plus the $AGENT/agentID value above. The CLI has no interactions commands — respond from the dashboard or the API.

curl "$BASE/agents/$AGENT/interactions?state=open" \
  -H "Authorization: Bearer $OMNARA_TOKEN"

const interactions = await sdk.listAgentInteractions({
  client,
  path: { orgID, projectID, agentID },
  query: { state: 'open' },
})
console.log(interactions.data)

{
  "data": [
    {
      "id": "int_rwz3jehcyd5n6a2bfgik7mv4qt",
      "org_id": "org_k7mv4qtrwz3jehcyd5n6a2bfgi",
      "project_id": "proj_7mv4qtrwz3jehcyd5n6a2bfgik",
      "agent_id": "agt_v4qtrwz3jehcyd5n6a2bfgik7m",
      "interaction_kind": "permission",
      "state": "open",
      "request": {
        "title": "Permission requested for run_command",
        "context": [
          { "label": "Command", "value": "rm -rf ./build && npm run build" },
          { "label": "Machine", "value": "mch_aaaaaaaaaaaaaaaaaaaaaaaaae" },
          { "label": "Shell", "value": "bash" }
        ],
        "questions": [
          {
            "prompt": "Allow this tool call?",
            "options": [
              { "label": "Allow" },
              { "label": "Deny", "allows_text": true }
            ]
          }
        ]
      },
      "created_at": "2026-08-03T19:13:20Z"
    }
  ],
  "next_cursor": null
}

Filter by state (open, resolved, canceled) or omit it for everything; results are cursor-paginated, oldest first. Open interactions announce themselves through tool_call_update frames on the event stream and configured webhooks; use this endpoint to fetch the form to render.

Full schema and playground: List agent interactions.

Render the form

Every interaction’s request is the same small form structure, designed to render without special-casing:

title — one line saying what’s being asked.
context — optional label/value pairs to display verbatim (the command about to run, the machine it targets). Show all of them; they’re the approver’s evidence.
questions — one or more, in order. Each has a prompt and at least one option. multiple: true means the answer may select several options; an option with allows_text: true invites free text alongside the selection (in permission forms, that’s the “Deny” option — the text becomes the reason the model sees).

Permission forms always have exactly one question with Allow at index 0 and Deny at index 1. Question forms are composed by the agent, so treat them generically.

Resolve it

API
Dashboard

Answer with one entry per question, in order. option_indices are zero-based positions into that question’s options. The response is the interaction in its final state:

curl "$BASE/agents/$AGENT/interactions/int_rwz3jehcyd5n6a2bfgik7mv4qt/resolve" \
  -H "Authorization: Bearer $OMNARA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "answers": [ { "option_indices": [0] } ] }'

const resolved = await sdk.resolveAgentInteraction({
  client,
  path: { orgID, projectID, agentID, interactionID: 'int_rwz3jehcyd5n6a2bfgik7mv4qt' },
  body: { answers: [{ option_indices: [0] }] },
})
console.log(resolved.data)

{
  "id": "int_rwz3jehcyd5n6a2bfgik7mv4qt",
  "interaction_kind": "permission",
  "state": "resolved",
  "request": { "title": "Permission requested for run_command", "...": "..." },
  "resolution": { "answers": [ { "option_indices": [0] } ] },
  "resolved_by_input_id": "ain_fgik7mv4qtrwz3jehcyd5n6a2b",
  "resolved_at": "2026-08-03T19:14:01Z",
  "...": "..."
}

To deny with a reason, select the Deny option and attach text:

curl "$BASE/agents/$AGENT/interactions/int_rwz3jehcyd5n6a2bfgik7mv4qt/resolve" \
  -H "Authorization: Bearer $OMNARA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "answers": [ { "option_indices": [1], "text": "Not on the build server — use a pool machine." } ] }'

await sdk.resolveAgentInteraction({
  client,
  path: { orgID, projectID, agentID, interactionID: 'int_rwz3jehcyd5n6a2bfgik7mv4qt' },
  body: {
    answers: [{ option_indices: [1], text: 'Not on the build server — use a pool machine.' }],
  },
})

Two operational notes:

Resolution is first-writer-wins. Re-sending the same answers replays idempotently — 200 with the already-resolved interaction. Sending different answers, or resolving a canceled interaction, returns 409 with code idempotency_key_conflict. Whoever answers first, wins; build your approval UI to handle the race gracefully.
Attribution works like inputs. Services relaying human decisions pass actor alongside answers so resolved_by_input_id traces to the real person — see actors.

Full schema and playground: Resolve agent interaction.

When interactions cancel

You never delete an interaction; it cancels when the work it guarded goes away:

Sending input with cancel_open_interactions: true — your new message supersedes the pending prompts; their tool calls complete as canceled.
Stopping the agent or archiving it — everything in flight, interactions included, is canceled.

Canceled interactions keep their request and stay listable, so audit trails show what was asked even when nobody answered.

Present interactions in your own app

Your application decides where to display questions and approvals. Read the interaction’s request, present the form, and resolve it through the ordinary project-authorized API. The dashboard remains available if delivery fails. Reconcile the interaction list on reconnect and periodically while connected; stream hints alone are insufficient. For an interaction routed to an integration handler, list and resolve responses include its captured destination. Its integration_id and integration_target_id are public IDs; handler_key identifies the handler and conversation contains the provider fields, using the same format as integration subscriptions. This snapshot stays fixed when the agent’s current destination changes. Optional presentation_receipt contains recorded provider message metadata. These fields describe integration delivery; your application can present interactions without them. See Integrations for handler configuration and integration-specific behavior, or Custom integrations for presenting interactions through your own service.

Artifacts

Download the files agents produce and reference

Agent configuration

Decide which tools require approval in the first place

Get started

Examples

Agents

Inputs & events

Tools

Machines

Organization

Integrations

Approvals & questions

Find open interactions

Render the form

Resolve it

When interactions cancel

Present interactions in your own app

Next

Artifacts

Agent configuration

​Find open interactions

​Render the form

​Resolve it

​When interactions cancel

​Present interactions in your own app

​Next

Artifacts

Agent configuration

Find open interactions

Render the form

Resolve it

When interactions cancel

Present interactions in your own app

Next