AI

Start an agent execution

Runs the tool-using agent (ReAct) loop against a session - the same pipeline the product UI's Agent Mode toggle dispatches to, and the REST equivalent of the agent_execute WebSocket command. The run is asynchronous: this returns 202 with an execution id, and the caller polls GET /api/v1/agent-executions/{id} until status is terminal (completed, failed, or aborted). Nothing is streamed back over REST - for live iteration events, use the WebSocket route instead. Omit agent_id to get the profile the session's own surface resolves to, which is what reproduces the in-app toggle. The final reply is also written to the session as a normal chat message, so it appears in history. Naming a tool in tools also PRE-APPROVES it for the run: there is no interactive client to answer a permission prompt, so a run that calls an approval-gated tool you did not name fails with that tool named in error rather than hanging. Authenticate with an API key (b4m_live_) or a JWT.

post/api/v1/agent-executions

Request

  • Base URL: https://your-deployment.example.com
  • URL: https://your-deployment.example.com/api/v1/agent-executions
  • Auth: one of:
    • HTTP bearer
    • API key in header x-api-key

Request body

session_idstring required
messagestring required
modelstring
agent_idstring
organization_idstring
toolsstring[]
max_iterationsinteger
temperaturenumber
max_tokensinteger
file_idsstring[]
session_file_idsstring[]
enable_mementosboolean
enable_latticeboolean
enable_artifactsboolean

Example request

{
  "session_id": "<sessionId>",
  "message": "Audit this data set and summarize what stands out."
}

Response

Run accepted and dispatched. Poll tracking_info.poll_url for status and the answer.

idstring required
status'pending' required
session_idstring required
modelstring required
timestampstring required

Changes

No recorded changes to this operation across all 1 revision of this API.