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

1. Export your API key

   Set at least one provider key in your shell. Agent Manager activates whichever providers have valid keys on startup.

   export OPENAI_API_KEY=sk-...
   
2. Start the database

   From the backend directory, bring up PostgreSQL:

   docker-compose up -d
   

   This starts PostgreSQL on port 5432. Wait a few seconds for it to be ready before proceeding.

3. Run the application

   Use the Maven wrapper to start the application:

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

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.

cURL

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?"
  }'

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:

{
  "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.

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.

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:

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.

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.

Next steps

Key concepts

Learn what agents, runs, sessions, and memory mean in Agent Manager.

Multi-agent teams

Coordinate multiple agents using Coordinator or Router orchestration.

Knowledge base

Ingest documents and let agents search them with RAG.

API reference

Full request and response documentation for every endpoint.