Admin REST API

CRUD endpoints for managing agents, teams, and workflows via Express.

Admin REST API

The createAdminRouter() function returns an Express router with full CRUD endpoints for agents, teams, and workflows.

---

Endpoints

Agents

Method	Path	Description
POST	/agents	Create agent from blueprint
GET	/agents	List all persisted agent configs
GET	/agents/:name	Get single agent config
PUT	/agents/:name	Update agent (destroy + recreate)
DELETE	/agents/:name	Remove from registry + storage

Teams

Method	Path	Description
POST	/teams	Create team from agent names
GET	/teams	List all persisted team configs
GET	/teams/:name	Get single team config
PUT	/teams/:name	Update team
DELETE	/teams/:name	Remove from registry + storage

Workflows

Method	Path	Description
POST	/workflows	Register workflow metadata
GET	/workflows	List persisted workflow configs
GET	/workflows/:name	Get single workflow config
DELETE	/workflows/:name	Remove from registry + storage

Tools

Method	Path	Description
GET	/tools	List all available tools (static + dynamic toolkit configs)
GET	/tools/:name	Get single tool detail (name, description, parameters)

Toolkit Catalog

Method	Path	Description
GET	/toolkit-catalog	List all available toolkit types with config requirements
GET	/toolkit-catalog/:id	Get single toolkit type detail

Toolkit Configs (Credentials Management)

Method	Path	Description
POST	/toolkit-configs	Save toolkit config (credentials + settings)
GET	/toolkit-configs	List all saved configs (secrets masked)
GET	/toolkit-configs/:name	Get single config (secrets masked)
PUT	/toolkit-configs/:name	Update config (secrets preserved if masked values sent)
DELETE	/toolkit-configs/:name	Remove config and deactivate toolkit

---

Create Agent

curl -X POST http://localhost:3000/admin/agents \
  -H "Content-Type: application/json" \
  -d '{
    "name": "researcher",
    "provider": "openai",
    "model": "gpt-4o",
    "instructions": "You research topics thoroughly.",
    "tools": ["webSearch"]
  }'

{
  "name": "researcher",
  "provider": "openai",
  "model": "gpt-4o",
  "instructions": "You research topics thoroughly.",
  "tools": ["webSearch"],
  "createdAt": "2026-02-27T10:00:00.000Z",
  "updatedAt": "2026-02-27T10:00:00.000Z"
}

The agent is immediately available via the transport layer:

curl -X POST http://localhost:3000/api/agents/researcher/run \
  -H "Content-Type: application/json" \
  -d '{"input": "What is quantum computing?"}'

---

Agent Blueprint

name · string · required

Unique agent name. Used as the identifier in registry and transport routes.

provider · string · required

Model provider id: "openai", "anthropic", "google", "ollama", "vertex".

model · string · required

Model id: "gpt-4o", "gpt-4o-mini", "claude-sonnet-4-20250514", etc.

instructions · string

System prompt for the agent.

tools · string[]

Tool names from the toolLibrary. e.g., ["webSearch", "calculator"].

temperature · number

Model temperature (0-2).

providerConfig · object

Provider-specific config passed to modelRegistry.resolve() (e.g., { apiKey, baseURL }).

---

Update Agent

curl -X PUT http://localhost:3000/admin/agents/researcher \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o-mini", "instructions": "Be concise."}'

The old agent is removed from the registry, a new one is created with the updated config, and the blueprint is persisted.

---

Create Team

curl -X POST http://localhost:3000/admin/teams \
  -H "Content-Type: application/json" \
  -d '{
    "name": "content-team",
    "mode": "coordinate",
    "provider": "openai",
    "model": "gpt-4o",
    "members": ["researcher", "writer"]
  }'

All member agents must already exist in the registry.

---

Team Blueprint

name · string · required

Unique team name.

mode · string · required

Team mode: "coordinate", "route", "broadcast", "collaborate", "handoff".

provider · string · required

Model provider for the team leader.

model · string · required

Model id for the team leader.

members · string[] · required

Agent names that must exist in the registry.

instructions · string

System prompt for the team leader.

---

Validation & Error Codes

Status	Meaning
201	Created successfully
400	Missing required fields
404	Entity not found
409	Name already exists
422	Validation error (unknown provider, missing tool, missing member agent)
500	Internal error