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

# Agent Manager Quickstart: First Run in Minutes

> Boot the Agent Manager backend, make your first synchronous agent run via the REST API, and open the management UI — all in under ten minutes.

This guide walks you through starting the Agent Manager backend, executing your first agent run, and launching the UI. By the end you will have a working local environment and a real API response in hand.

## Prerequisites

Before you start, make sure you have the following:

* **Java 21 or later** — confirm with `java -version`. `JAVA_HOME` must be set.
* **Docker Desktop** — running and accessible. It is required for PostgreSQL and the Python code-execution sandbox.
* **An LLM API key** — at least one of `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, or `GOOGLE_API_KEY`.
* **Node.js 20 or later** — only needed for the UI.

## Start the backend

<Steps>
  <Step title="Export your API key">
    Set at least one provider key in your shell. Agent Manager activates whichever providers have valid keys on startup.

    ```bash theme={null}
    export OPENAI_API_KEY=sk-...
    ```
  </Step>

  <Step title="Start the database">
    From the backend directory, bring up PostgreSQL:

    ```bash theme={null}
    docker-compose up -d
    ```

    This starts PostgreSQL on port `5432`. Wait a few seconds for it to be ready before proceeding.
  </Step>

  <Step title="Run the application">
    Use the Maven wrapper to start the application:

    ```bash theme={null}
    ./mvnw spring-boot:run
    ```

    The server starts on `http://localhost:8080`. On first boot it seeds three default agents: `procurator_assistant`, `finance_agent`, and `web_agent`.
  </Step>
</Steps>

## Make your first API call

Once the server is running, send a synchronous run request to one of the seeded agents. The endpoint is `POST /api/agents/{agentId}/runs`.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST http://localhost:8080/api/agents/procurator_assistant/runs \
    -H "Content-Type: application/json" \
    -d '{
      "message": "What is Agent Manager and what can it do?"
    }'
  ```

  ```json Request body theme={null}
  {
    "message": "What is Agent Manager and what can it do?",
    "session_id": "550e8400-e29b-41d4-a716-446655440000"
  }
  ```
</CodeGroup>

The `session_id` field is optional. If you omit it, the server generates a new UUID for you and includes it in the response — use it in subsequent requests to continue the same conversation.

## Understand the response

A successful run returns a `RunResponse` object:

```json theme={null}
{
  "runId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "sessionId": "550e8400-e29b-41d4-a716-446655440000",
  "content": "Agent Manager is an enterprise AI agent orchestration platform...",
  "status": "COMPLETED",
  "tools": [
    {
      "name": "search_knowledge_base",
      "input": { "query": "Agent Manager capabilities" },
      "output": "..."
    }
  ],
  "reasoningSteps": [
    "The user is asking about the platform itself. I should search the knowledge base first."
  ],
  "metadata": {
    "model": "gpt-4o",
    "promptTokens": 312,
    "completionTokens": 187
  },
  "metrics": {
    "durationMs": 2140
  }
}
```

| Field            | Description                                                                       |
| :--------------- | :-------------------------------------------------------------------------------- |
| `runId`          | Unique identifier for this execution.                                             |
| `sessionId`      | Conversation context. Pass this back in the next request to continue the session. |
| `content`        | The agent's final answer in Markdown.                                             |
| `status`         | `COMPLETED`, `FAILED`, `PAUSED`, or `CANCELLED`.                                  |
| `tools`          | Ordered list of tool calls the agent made, with inputs and outputs.               |
| `reasoningSteps` | The agent's internal reasoning trace, captured before the final answer.           |
| `metadata`       | Model name and token usage for this run.                                          |
| `metrics`        | Execution timing and other per-run telemetry.                                     |

<Tip>
  If `status` is `PAUSED`, the agent encountered a sensitive tool call and is waiting for human approval. Send a `POST /api/agents/{agentId}/runs/{runId}/continue` request with `{"action": "APPROVE"}` or `{"action": "REJECT"}` to resume.
</Tip>

## Start the UI

The Agent Manager UI runs as a separate Node.js development server. Open a new terminal, navigate to the UI directory, and run:

```bash theme={null}
npm install
npm run dev
```

Open your browser to `http://localhost:5173`. The UI connects to the backend at `http://localhost:8080/api` by default.

From the UI you can:

* Chat with any registered agent and see streaming tokens and reasoning steps in real time.
* Browse and configure agents in the registry.
* Upload PDFs or trigger URL ingestion for the knowledge base.
* Inspect session history and long-term user memories.
* Approve or reject paused HITL runs with a single click.

<Warning>
  The UI expects the backend to be running before it loads. If you see connection errors, confirm that `./mvnw spring-boot:run` completed successfully and the server is listening on port `8080`.
</Warning>

## Next steps

<CardGroup cols={2}>
  <Card title="Key concepts" icon="book-open" href="/concepts">
    Learn what agents, runs, sessions, and memory mean in Agent Manager.
  </Card>

  <Card title="Multi-agent teams" icon="users" href="/features/teams">
    Coordinate multiple agents using Coordinator or Router orchestration.
  </Card>

  <Card title="Knowledge base" icon="database" href="/knowledge/knowledge-base">
    Ingest documents and let agents search them with RAG.
  </Card>

  <Card title="API reference" icon="code" href="/api/agents/run">
    Full request and response documentation for every endpoint.
  </Card>
</CardGroup>