Run an Agent Synchronously — API Reference

Execute an agent synchronously and receive the complete RunResponse in one request, with built-in HITL pause/resume and cancellation support.

The synchronous run endpoint executes an agent and blocks until the agent produces a final response. This is the simplest way to integrate Agent Manager — send a message, receive the full answer. For long-running tasks or streaming output, see Background Runs and SSE Streaming.

All requests require a valid bearer token in the Authorization header.

---

Execute a synchronous run

POST /api/agents/{agentId}/runs

Runs the agent against the provided message and returns a RunResponse when execution completes. If the agent triggers a Human-in-the-Loop (HITL) tool during execution, the run is suspended and the response returns with status: "PAUSED" — call the continue endpoint to approve or reject.

Path parameters

agentId · string · required

The unique identifier of the agent to run. Retrieve valid IDs from GET /api/agents.

Request body

message · string · required

The user’s input or query. The agent uses this as the primary prompt for the interaction.

sessionId · string

A UUID identifying an existing conversation session. When provided, the agent rehydrates its message history from that session, enabling multi-turn conversations. Omit to start a new session — the server generates and returns a new sessionId.

userId · string

Associates this run with a specific user. Used for memory scoping, audit logs, and per-user analytics. Defaults to the authenticated principal when omitted.

orgId · string

Tenant identifier for multi-tenant deployments. Scopes the run to a specific organization’s agents and knowledge bases.

generateFollowups · boolean · default: "false"

When true, the agent generates a list of suggested follow-up questions to append to the response. Useful for chat UIs that want to prompt the next turn.

media · object[]

An array of multimodal media inputs for vision-capable agents.

Show MediaInput fields

type · string · required

MIME type of the media, e.g. "image/png", "image/jpeg", or "audio/wav".

data · string · required

Either a base64-encoded string of the raw media bytes, or an HTTP/HTTPS URL pointing to the media resource.

options · object

Optional RunOptions object to override model-level settings for this specific run.

Show RunOptions fields

options.model · string

Override the default model for this run (e.g., "gpt-4o", "claude-3-5-sonnet").

options.temperature · number

Sampling temperature, between 0 and 2. Higher values produce more creative responses.

options.maxTokens · number

Maximum number of tokens to generate in the response.

Response

runId · string · required

Unique identifier for this specific run. Use this ID to call the continue or cancel endpoints.

sessionId · string · required

The conversation session associated with this run. Pass this value back in subsequent requests to maintain conversation context.

content · string

The agent’s final answer, rendered as Markdown. Empty when status is "FAILED" or "PAUSED".

metadata · object

Usage statistics and model information for this run.

Show metadata fields

model · string

The model identifier used for this run.

promptTokens · number

Number of tokens consumed by the input prompt.

completionTokens · number

Number of tokens generated in the response.

totalTokens · number

Sum of promptTokens and completionTokens.

tools · object[]

An ordered list of tool calls made during execution. Useful for audit logs and debugging.

Show ToolCall fields

name · string

The name of the tool that was called.

arguments · object

The arguments passed to the tool.

result · string

The output returned by the tool.

reasoningSteps · string[]

Captured inner thoughts from the agent’s reasoning process — what the agent was thinking before each tool call. Useful for explainability and debugging.

status · string · required

Execution status of the run. One of:

• "COMPLETED" — the agent finished successfully and content contains the response.
• "FAILED" — an unrecoverable error occurred during execution.
• "PAUSED" — the agent triggered a Human-in-the-Loop confirmation gate. Call /runs/{runId}/continue to resume.

cURL

curl --request POST \
  --url "http://localhost:8080/api/agents/finance_agent/runs" \
  --header "Authorization: Bearer {token}" \
  --header "Content-Type: application/json" \
  --data '{
    "message": "What is the current stock price of NVIDIA?",
    "sessionId": "550e8400-e29b-41d4-a716-446655440000",
    "userId": "user_abc123",
    "generateFollowups": true
  }'

Example response

{
  "runId": "run_7f3a9c12-4e2b-4d1a-8c5f-abc123def456",
  "sessionId": "550e8400-e29b-41d4-a716-446655440000",
  "content": "The current stock price of NVIDIA (NVDA) is **$875.40**, up 2.3% today.\n\n**Suggested follow-ups:**\n- How does NVDA compare to AMD this quarter?\n- What is NVIDIA's P/E ratio?",
  "metadata": {
    "model": "gpt-4o",
    "promptTokens": 342,
    "completionTokens": 89,
    "totalTokens": 431
  },
  "tools": [
    {
      "name": "get_stock_price",
      "arguments": { "ticker": "NVDA" },
      "result": "875.40"
    }
  ],
  "reasoningSteps": [
    "The user wants the current NVDA stock price. I should call get_stock_price with ticker=NVDA."
  ],
  "status": "COMPLETED"
}

---

Resume a paused run (HITL)

POST /api/agents/{agentId}/runs/{runId}/continue

When a run returns status: "PAUSED", the agent has encountered a tool marked as requiring human approval (for example, delete_database or send_email). Use this endpoint to approve or reject the pending action.

Until you call this endpoint, the paused run holds its state in the database and is consuming a slot in the job queue. Approve or reject promptly to avoid stale runs.

Path parameters

agentId · string · required

The agent that owns the paused run.

runId · string · required

The run ID returned in the original RunResponse with status: "PAUSED".

Request body

action · string · required

The human decision. Must be "APPROVE" to allow the tool to execute, or "REJECT" to cancel the tool call and return control to the agent.

cURL

curl --request POST \
  --url "http://localhost:8080/api/agents/finance_agent/runs/run_7f3a9c12/continue" \
  --header "Authorization: Bearer {token}" \
  --header "Content-Type: application/json" \
  --data '{ "action": "APPROVE" }'

Example response

The server returns a new RunResponse reflecting the outcome after the approved or rejected tool call resolves.

{
  "runId": "run_7f3a9c12-4e2b-4d1a-8c5f-abc123def456",
  "sessionId": "550e8400-e29b-41d4-a716-446655440000",
  "content": "The database deletion has been approved and completed successfully.",
  "metadata": { "model": "gpt-4o", "totalTokens": 512 },
  "tools": [],
  "reasoningSteps": [],
  "status": "COMPLETED"
}

---

Cancel a run

DELETE /api/agents/{agentId}/runs/{runId}

Sends a cancellation signal to an active or paused run. Returns 204 No Content on success. The run status is updated to CANCELLED in the database.

agentId · string · required

The agent that owns the run.

runId · string · required

The unique run identifier to cancel.

cURL

curl --request DELETE \
  --url "http://localhost:8080/api/agents/finance_agent/runs/run_7f3a9c12" \
  --header "Authorization: Bearer {token}"

Returns 204 No Content with an empty body on success.

Use the cancel endpoint to clean up PAUSED runs that you no longer intend to approve, freeing queue capacity.