Managing and Running AI Agents

Learn how to list, inspect, and execute AI agents in Agent Manager, including synchronous runs, Human-in-the-Loop approvals, and run cancellation.

Agents are the core execution units in Agent Manager. Each agent is an LLM instance configured with a set of tools, a knowledge base, and a system prompt that defines its behavior and expertise. You interact with agents through a consistent REST API — whether you are running a simple query, handling a sensitive tool that requires human approval, or cancelling an in-flight run.

What is an agent?

An agent is represented by an AgentDefinition object, which describes its identity and type:

id · string · required

Unique identifier for the agent (e.g., finance_agent).

name · string · required

Human-readable display name.

description · string

A short description of what the agent does.

is_team · boolean

When true, this agent is a multi-agent team with a coordinator or router leader. See Multi-Agent Teams for details.

Default agents

Agent Manager seeds three agents on startup:

procurator_assistant

An expert on the Operativus framework. Pre-loaded with knowledge from the official documentation.

finance_agent

Retrieves live stock prices and financial data using built-in market tools.

web_agent

Performs general-purpose web searches to answer open-ended questions.

Listing agents

Retrieve all agents registered in the system:

GET /api/agents

Pass ?includeInactive=true to include agents that have been disabled.

Response:

[
  {
    "id": "procurator_assistant",
    "name": "Procurator Assistant",
    "description": "Expert on the Operativus framework",
    "is_team": false
  },
  {
    "id": "finance_agent",
    "name": "Finance Agent",
    "description": "Retrieves live stock prices",
    "is_team": false
  },
  {
    "id": "web_agent",
    "name": "Web Agent",
    "description": "General web search",
    "is_team": false
  }
]

Getting agent details

Retrieve a single agent by its ID:

GET /api/agents/{agentId}

Returns a single AgentDefinition object or 404 Not Found if the agent does not exist.

Running an agent

Use the synchronous run endpoint to send a message to an agent and receive the full response in one request. This is suitable for automated pipelines, testing, and any scenario where you do not need token-by-token streaming.

POST /api/agents/{agentId}/runs

Request body

message · string · required

The user message or prompt to send to the agent.

sessionId · string

An optional session ID for conversation continuity. If omitted, a new session is created automatically.

userId · string

The ID of the user initiating the run. Used for memory partitioning and audit logging.

stream · boolean · default: "false"

Reserved field. For streaming responses, use the /runs/stream endpoint instead.

media · object[]

Optional array of media attachments for multimodal agents. Each object must include type (MIME type) and data (base64-encoded content or a URL).

generateFollowups · boolean · default: "false"

When true, the agent generates suggested follow-up questions alongside the response.

Example request:

{
  "message": "What is the current price of AAPL?",
  "sessionId": "session-abc-123",
  "userId": "user-42"
}

Response

runId · string

Unique identifier for this run.

sessionId · string

The session ID used for this run (echoed back or newly generated).

content · string

The agent’s final Markdown-formatted response.

metadata · object

Usage statistics and model information (token counts, latency, etc.).

tools · object[]

Audit log of every tool the agent called during this run.

reasoningSteps · string[]

The agent’s captured inner thoughts — what it was reasoning about before each tool call.

status · string

Final run status: COMPLETED, FAILED, or PAUSED.

Example response:

{
  "runId": "run-7f3a9c",
  "sessionId": "session-abc-123",
  "content": "The current price of **AAPL** is $192.45 as of market close.",
  "metadata": {
    "model": "gpt-4o",
    "inputTokens": 34,
    "outputTokens": 22
  },
  "tools": [
    { "name": "get_stock_price", "input": { "ticker": "AAPL" }, "output": "192.45" }
  ],
  "reasoningSteps": [
    "I need to look up the current AAPL stock price using the market data tool."
  ],
  "status": "COMPLETED"
}

Human-in-the-Loop (HITL)

Some tools — such as those that delete data or make external writes — are configured to require human approval before execution. When an agent encounters one of these tools, the run transitions to a PAUSED status and waits for you to approve or reject the action.

Checking if a run is paused

Poll the run status endpoint:

GET /api/agents/{agentId}/runs/{runId}/status

When the status field is PAUSED, the run is waiting for your input.

Resuming a paused run

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

Request body:

action · string · required

Must be either APPROVE to allow the tool to execute, or REJECT to cancel it and let the agent respond gracefully.

Approve

{
  "action": "APPROVE"
}

A paused run will remain in PAUSED state indefinitely until you call /continue. Make sure your application monitors for paused runs if you use tools that require confirmation.

After you submit the action, the run resumes and returns a RunResponse with the final result.

Cancelling a run

To abort an in-progress run, send a DELETE request:

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

A successful cancellation returns 204 No Content. The run is marked as cancelled and no further tokens are consumed.

Background runs

For long-running tasks where you do not want to hold an open HTTP connection, queue the run asynchronously:

POST /api/agents/{agentId}/runs/background

The response returns immediately with a runId and a QUEUED status. You can then poll for completion:

GET /api/agents/{agentId}/runs/{runId}/status

To check the status of multiple background runs at once, pass a list of IDs to the batch endpoint: GET /api/agents/{agentId}/runs/status?runIds=id1,id2,id3. This reduces polling overhead significantly for dashboards tracking many concurrent runs.