> ## Documentation Index
> Fetch the complete documentation index at: https://operativusai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

<ResponseField name="id" type="string" required>
  Unique identifier for the agent (e.g., `finance_agent`).
</ResponseField>

<ResponseField name="name" type="string" required>
  Human-readable display name.
</ResponseField>

<ResponseField name="description" type="string">
  A short description of what the agent does.
</ResponseField>

<ResponseField name="is_team" type="boolean">
  When `true`, this agent is a multi-agent team with a coordinator or router leader. See [Multi-Agent Teams](/features/teams) for details.
</ResponseField>

## Default agents

Agent Manager seeds three agents on startup:

<CardGroup cols={3}>
  <Card title="procurator_assistant" icon="book-open">
    An expert on the Operativus framework. Pre-loaded with knowledge from the official documentation.
  </Card>

  <Card title="finance_agent" icon="chart-line">
    Retrieves live stock prices and financial data using built-in market tools.
  </Card>

  <Card title="web_agent" icon="globe">
    Performs general-purpose web searches to answer open-ended questions.
  </Card>
</CardGroup>

## Listing agents

Retrieve all agents registered in the system:

```bash theme={null}
GET /api/agents
```

<Note>
  Pass `?includeInactive=true` to include agents that have been disabled.
</Note>

**Response:**

```json theme={null}
[
  {
    "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:

```bash theme={null}
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.

```bash theme={null}
POST /api/agents/{agentId}/runs
```

### Request body

<ParamField body="message" type="string" required>
  The user message or prompt to send to the agent.
</ParamField>

<ParamField body="sessionId" type="string">
  An optional session ID for conversation continuity. If omitted, a new session is created automatically.
</ParamField>

<ParamField body="userId" type="string">
  The ID of the user initiating the run. Used for memory partitioning and audit logging.
</ParamField>

<ParamField body="stream" type="boolean" default="false">
  Reserved field. For streaming responses, use the `/runs/stream` endpoint instead.
</ParamField>

<ParamField body="media" type="object[]">
  Optional array of media attachments for multimodal agents. Each object must include `type` (MIME type) and `data` (base64-encoded content or a URL).
</ParamField>

<ParamField body="generateFollowups" type="boolean" default="false">
  When `true`, the agent generates suggested follow-up questions alongside the response.
</ParamField>

**Example request:**

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

### Response

<ResponseField name="runId" type="string">
  Unique identifier for this run.
</ResponseField>

<ResponseField name="sessionId" type="string">
  The session ID used for this run (echoed back or newly generated).
</ResponseField>

<ResponseField name="content" type="string">
  The agent's final Markdown-formatted response.
</ResponseField>

<ResponseField name="metadata" type="object">
  Usage statistics and model information (token counts, latency, etc.).
</ResponseField>

<ResponseField name="tools" type="object[]">
  Audit log of every tool the agent called during this run.
</ResponseField>

<ResponseField name="reasoningSteps" type="string[]">
  The agent's captured inner thoughts — what it was reasoning about before each tool call.
</ResponseField>

<ResponseField name="status" type="string">
  Final run status: `COMPLETED`, `FAILED`, or `PAUSED`.
</ResponseField>

**Example response:**

```json theme={null}
{
  "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:

```bash theme={null}
GET /api/agents/{agentId}/runs/{runId}/status
```

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

### Resuming a paused run

```bash theme={null}
POST /api/agents/{agentId}/runs/{runId}/continue
```

**Request body:**

<ParamField body="action" type="string" required>
  Must be either `APPROVE` to allow the tool to execute, or `REJECT` to cancel it and let the agent respond gracefully.
</ParamField>

<CodeGroup>
  ```json Approve theme={null}
  {
    "action": "APPROVE"
  }
  ```

  ```json Reject theme={null}
  {
    "action": "REJECT"
  }
  ```
</CodeGroup>

<Warning>
  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.
</Warning>

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:

```bash theme={null}
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:

```bash theme={null}
POST /api/agents/{agentId}/runs/background
```

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

```bash theme={null}
GET /api/agents/{agentId}/runs/{runId}/status
```

<Tip>
  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.
</Tip>