Documentation — AgentOffice

> PREREQUISITES

What you'll need

Minimum requirements to run AgentOffice in development or production.

⬡

Node.js 18+

Base runtime for every process. LTS recommended for production environments.

Required

⚡

Bun 1.0+

Recommended for maximum performance. Replaces Node.js as the runner and package manager.

Recommended

◆

Anthropic API Key

Access key for the LLM provider. OpenAI and other providers are also supported.

Required

Optional

NATS Server P2P communication between instances. Required for multi-node deployments.

Qdrant High-performance vector search. Recommended for catalogs with 1000+ agents.

Docker / Kubernetes Only required for containerized production deployments.

> QUICKSTART

Up and running in 5 steps

From installation to your first automatically routed response.

Install dependencies — pick your package manager

bash

$ npm install -g @mariozechner/pi-coding-agent
# or, with bun (recommended)
$ bun add -g @mariozechner/pi-coding-agent

Create AGENTS.md — defines the available agents

AGENTS.md

# agents

## builder
Software development specialist. Writes clean code and tests.
Skills: TypeScript, Node.js, software architecture.

## reviewer
Reviews code with a focus on quality, security, and performance.
Skills: code review, static analysis, best practices.

## devops
Infrastructure and deployment automation specialist.
Skills: Docker, Kubernetes, CI/CD, observability.

Configure settings.json — providers and extensions

settings.json

{
  "providers": {
    "anthropic": {
      "apiKey": "sk-ant-..."
    }
  },
  "extensions": ["agent-office"],
  "routing": {
    "scorer": "hybrid",
    "rerank": false
  }
}

Start the server — portal and API come up together

bash

$ pi -e extensions/agent-office.ts

✓ Portal: http://localhost:3000
✓ API: http://localhost:3777
✓ Routing: HybridScorer online
✓ Agents: builder | reviewer | devops

First message — automatic routing

portal — localhost:3000

> I need someone to review PR #42 before it merges.

[routing:decision] → reviewer (score: 0.96)
Analyzing PR #42...

Found 3 issues to fix before merging:
1. Missing input validation in UserController.ts:42
2. Potential N+1 query in OrderService.findAll()
3. Integration test missing a database mock

> CONCEPTS

Understanding the architecture

The fundamental building blocks that make up AgentOffice.

runtime

Pi Extension

AgentOffice runs via pi -e extensions/agent-office.ts. The Pi runtime manages the conversation loop, context, and agent lifecycle.

configuration

AGENTS.md

Defines the available agents in Markdown. Name, description, and skills are extracted by the parser and indexed by the router automatically.

intelligence

Semantic Routing

HybridScorer analyzes every message with embeddings + heuristics and selects the agent with the highest affinity score for the context.

interface

Next.js Portal

Real-time interface with routing decision visualization via SSE. Conversation history, metrics, and agent state.

:3000

integration

REST API

Full programmatic control. Send messages, create teams, cancel executions, and query metrics from any application.

:3777

communication

coms-net

Agent-to-agent communication hub with namespace support for isolation. Enables structured collaboration between multiple agents.

:8787

> STRUCTURE

Project layout

The canonical structure of an AgentOffice project.

directory structure

your-project/
├── AGENTS.md              ← defines agents and routing
├── settings.json          ← providers, extensions, config
├── extensions/
│   ├── agent-office.ts    ← main extension
│   ├── coms-net.ts        ← communication hub
│   ├── mcp.ts             ← MCP tools
│   └── skills/
│       ├── global/            ← shared skills
│       └── agents/            ← per-agent skills
├── projects/                  ← persistent data per project
│   ├── <project-id>/
│   │   ├── context.json
│   │   └── sessions/
└── k8s/                       ← Kubernetes manifests
    ├── namespace.yaml
    ├── configmap.yaml
    ├── secret.yaml
    ├── deployment.yaml
    └── service.yaml

> CONFIGURATION

Environment variables

Configure AgentOffice's behavior via environment variables or .env.

Variable	Type	Description
ANTHROPIC_API_KEY	string	Anthropic API key. Required when the selected provider is `anthropic`.
OPENAI_API_KEY	string	OpenAI API key. Used when the alternate provider is `openai`.
PI_NATS_URL	string	NATS server URL (e.g. `nats://localhost:4222`). Enables P2P transport between instances.
PI_NATS_TOKEN	string	Shared token for authenticating against the NATS cluster. Connectivity mode B.
QDRANT_URL	string	Qdrant server URL (e.g. `http://localhost:6333`). Enables QdrantScorer for catalogs with 1000+ agents.
ROUTING_RERANK	boolean	Enables the cross-encoder for re-ranking candidates. Increases precision by ~12%, adds ~15ms of latency.
OFFICE_PORT	number	REST API port. Default: `3777`.
OFFICE_PORTAL_PORT	number	Next.js portal port. Default: `3000`.
OFFICE_MAX_SESSIONS	number	Limit of concurrent sessions per instance. Default: `50`. Adjust based on available RAM.
OFFICE_SESSION_TTL	number	Expiration time for idle sessions, in seconds. Default: `1800` (30 min).
ROUTING_EMBED_MODEL	string	Embedding model for the semantic scorer. Default: `text-embedding-3-small`.
ROUTING_CACHE_TTL	number	TTL of the routing decision cache, in seconds. Default: `300`.
LOG_LEVEL	string	Log level: `error \| warn \| info \| debug`. Default: `info`.
METRICS_ENABLED	boolean	Exposes the `/metrics` endpoint in Prometheus format. Default: `true`.

> API REFERENCE

REST API — port 3777

All endpoints accept and return JSON. Streaming routes return text/event-stream.

Method	Endpoint	Description
GET	/agents	Lists all available agents with current status and declared capabilities.
POST	/message	Sends a message. Returns an SSE stream with the routing decision and the selected agent's response.
GET	/agents/:id/status	Current state of an agent: `idle \| thinking \| responding`.
GET	/stream/:sessionId	Reconnects to the SSE stream of an existing session. Useful for resuming after a dropped connection.
POST	/teams	Creates a team of agents with a defined collaboration and orchestration configuration.
GET	/teams	Lists all configured teams with members and operating mode.
POST	/teams/:id/message	Sends a message to an entire team. Orchestration distributes it to the relevant members.
DELETE	/sessions/:id	Ends a session and releases associated resources (context, streaming buffers).
GET	/routing/log	Paginated history of routing decisions with scores and metadata for each choice.
GET	/routing/log/:id	Full details of a specific decision: candidates, scores, and rationale.
POST	/agents/:id/cancel	Cancels an agent's in-progress execution and releases the response token.
GET	/metrics	Prometheus endpoint with latency, throughput, and agent utilization metrics.
GET	/health	Health check for the Kubernetes liveness probe. Returns `200 OK` when the process is healthy.
GET	/ready	Readiness probe: confirms the router is initialized and the agents are loaded.

Example — POST /message

POST /message

# Request body
{
  "message":   "Review PR #42 before it merges",
  "sessionId": "ses_abc123",    // optional — creates a new one if omitted
  "stream":    true              // returns SSE when true
}

# SSE response
event: routing
data: {"agent":"reviewer","score":0.96,"reason":"code review intent"}

event: delta
data: {"content":"Analyzing PR #42..."}

event: done
data: {"sessionId":"ses_abc123","tokensUsed":312}

> DEPLOY

Kubernetes in production

From local development to a multi-node, highly available cluster.

bash — local development

# Clone and install
$ git clone https://github.com/your-org/agent-office
$ cd agent-office && bun install

# Configure variables
$ cp .env.example .env
$ ANTHROPIC_API_KEY=sk-ant-... bun run dev

✓ Portal: http://localhost:3000
✓ API: http://localhost:3777

docker-compose.yml

services:
  agent-office:
    image: ghcr.io/your-org/agent-office:latest
    ports:
      - "3000:3000"   # portal
      - "3777:3777"   # api
      - "8787:8787"   # coms-net
    environment:
      ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY}
      PI_NATS_URL:       nats://nats:4222
      QDRANT_URL:        http://qdrant:6333
    volumes:
      - ./AGENTS.md:/app/AGENTS.md:ro
      - ./settings.json:/app/settings.json:ro
      - ./projects:/app/projects
    depends_on: [nats, qdrant]

  nats:
    image: nats:2.10-alpine
    ports: ["4222:4222"]

  qdrant:
    image: qdrant/qdrant:v1.8.0
    ports: ["6333:6333"]
    volumes: [qdrant_data:/qdrant/storage]

volumes:
  qdrant_data:

bash

$ docker compose up -d

✓ Container nats Started
✓ Container qdrant Started
✓ Container agent-office Started

bash — cluster deploy

# Apply manifests in the correct order
$ kubectl apply -f k8s/namespace.yaml
$ kubectl apply -f k8s/configmap.yaml
$ kubectl apply -f k8s/secret.yaml
$ kubectl apply -f k8s/

# Wait for pods to become ready
$ kubectl -n agents rollout status deployment/pi-agent-alpha

Waiting for deployment "pi-agent-alpha" rollout...
deployment "pi-agent-alpha" successfully rolled out

# Check pod status
$ kubectl -n agents get pods

NAME READY STATUS RESTARTS
pi-agent-alpha-7d4f9b-xk8r2 1/1 Running 0
pi-agent-alpha-7d4f9b-m9p3n 1/1 Running 0

◈

Production environments — For high availability, set PI_NATS_URL for P2P communication between instances, and QDRANT_URL if your catalog has more than 50 agents. Both settings are transparent to the application — the router adapts its strategy automatically.

Get started in under 2 minutes.

What you'll need

Up and running in 5 steps

Understanding the architecture

Project layout

Environment variables

REST API — port 3777

Kubernetes in production

Keep exploring