Approvals & questions

An interaction is BMA’s record of the agent waiting for a person. There are two kinds:

Kind	Created when
`permission`	A tool with `always_ask` is called
`question`	The agent calls `ask_question` with one or more questions and options

An interaction is open, then resolved (someone answered) or canceled (the turn was interrupted, superseded or archived). Desktop, mobile and integrations all see the same open interactions.

Approvals through the Managed Agents API

When a call needs approval, the stream emits the agent.tool_use and then session.status_idle with stop_reason.type = "requires_action" and the ids to answer. Reply with user.tool_confirmation:

with client.beta.sessions.events.stream(session_id) as stream:
    for event in stream:
        if event.type == "session.status_idle":
            if event.stop_reason.type == "requires_action":
                for tool_use_id in event.stop_reason.event_ids:
                    client.beta.sessions.events.send(
                        session_id,
                        events=[{"type": "user.tool_confirmation",
                                 "tool_use_id": tool_use_id,
                                 "result": "allow"}],
                    )
                continue
            break

curl -sS "$BMA_BASE_URL/v1/sessions/$SESSION/events" "${H[@]}" -d '{
  "events": [{"type": "user.tool_confirmation", "tool_use_id": "<agent.tool_use id>",
              "result": "deny", "deny_message": "Not on production."}]
}'

The tool runs only after allow. A deny is recorded as user.tool_confirmation with your deny_message, and the model is told why.
With always_ask, BMA asks before it creates the session’s machine, so a denied call never provisions one.
The stream announces only prompts that belong to this session. If a history page ends while a prompt is open, BMA appends the same requires_action idle event, so a restarted worker sees it must answer.
user.interrupt cancels open interactions of the interrupted turn.

Native API

GET /orgs/{org}/projects/{project}/agents/{agent}/interactions?state=open lists open interactions with a form description; resolve one with POST …/interactions/{interactionID}/resolve (see the API reference for the answer schema). Use the native API when you build your own approval UI for questions as well as permissions; the /v1 API only carries tool confirmations.

Get started

Concepts

Executor & brains

Approvals through the Managed Agents API

Native API

​Approvals through the Managed Agents API

​Native API

Approvals through the Managed Agents API

Native API