Agents API

Today only GET /v1/agents (list agents in a lab) is shipped. The per-agent sub-routes described below (GET /v1/agents/{id}, /messages, /metrics, /start, /stop) are planned, not yet live. Drive individual agents from the web app or via Convex actions; this page documents the target REST shape so SDKs can build against it.

Every lab runs a hierarchical multi-agent system: an orchestrator directs lead agents who dispatch workers. The Agents API lets you configure the roster, start/stop agents, query status, and route messages.

Agent Roles

Role	Description	Typical Models
`orchestrator`	Top-level agent. Receives Captain instructions, breaks into tasks, manages leads. One per lab.	Claude Opus 4.8, GPT-5.5
`lead`	Domain owner. Plans and executes within a domain. Takes over from failed workers.	Claude Opus 4.8, Claude Sonnet 5, GPT-5.5
`worker`	Executes specific, scoped tasks dispatched by a lead.	Claude Haiku 4.5, GPT-5.5 Mini, Gemini 3.1 Flash

Agent Status

Status	Description
`active`	Online and available to receive tasks
`idle`	Online but not currently working on a task
`busy`	Actively executing a task
`retired`	Deactivated. Will not receive tasks.

Create an Agent

string

required

Lab this agent belongs to.

string

required

Display name (e.g., “Research Lead”, “Figure Worker”).

string

required

Agent role: orchestrator, lead, or worker.

string

required

Model identifier (e.g., claude-opus-4-8, claude-sonnet-5, claude-haiku-4-5, gpt-5.5, gemini-3.1-pro, grok-4, sonar-pro).

string

Convex ID of the agent this one reports to. Workers report to leads; leads report to the orchestrator.

string

Custom system prompt. Overrides the default for this role.

string[]

List of capabilities (e.g., ["code", "figures", "latex", "data-analysis"]).

curl -X POST https://www.hubify.com/api/v1/agents \
  -H "Authorization: Bearer $HUBIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "labId": "j57a8k9m2n3p4q5r",
    "name": "Research Lead",
    "role": "lead",
    "model": "claude-opus-4-8",
    "reportsTo": "k68b9l0n3o4p5q6s",
    "capabilities": ["code", "data-analysis", "figures"]
  }'

const agent = await hubify.agents.create({
  labId: "j57a8k9m2n3p4q5r",
  name: "Research Lead",
  role: "lead",
  model: "claude-opus-4-8",
  reportsTo: "k68b9l0n3o4p5q6s",
  capabilities: ["code", "data-analysis", "figures"],
});

object

Show Agent object

string

required

Convex document ID.

string

required

Parent lab ID.

string

required

Display name.

string

required

Agent role.

string

required

Model identifier.

string

required

Current status.

string

ID of the supervising agent.

string

ID of the agent that delegated the current task.

string

What the agent is currently working on.

string

Custom system prompt.

string[]

Agent capabilities.

number

required

Lifetime tasks completed.

number

required

Lifetime tokens consumed.

number

required

Creation timestamp (ms).

List Agents

string

required

Lab ID to list agents for.

string

Filter by role: orchestrator, lead, worker.

string

Filter by status: active, idle, busy, retired.

curl "https://www.hubify.com/api/v1/agents?labId=j57a8k9m2n3p4q5r&role=lead" \
  -H "Authorization: Bearer $HUBIFY_TOKEN"

const leads = await hubify.agents.list({
  labId: "j57a8k9m2n3p4q5r",
  role: "lead",
});

Get an Agent

curl https://www.hubify.com/api/v1/agents/k68b9l0n3o4p5q6s \
  -H "Authorization: Bearer $HUBIFY_TOKEN"

const agent = await hubify.agents.get({ agentId: "k68b9l0n3o4p5q6s" });

Update an Agent

string

Updated display name.

string

Change the model (e.g., upgrade from Sonnet to Opus).

string

Updated system prompt.

string[]

Updated capabilities list.

string

Change the supervising agent.

curl -X PATCH https://www.hubify.com/api/v1/agents/k68b9l0n3o4p5q6s \
  -H "Authorization: Bearer $HUBIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-4-8",
    "capabilities": ["code", "data-analysis", "figures", "latex"]
  }'

await hubify.agents.update({
  agentId: "k68b9l0n3o4p5q6s",
  model: "claude-opus-4-8",
  capabilities: ["code", "data-analysis", "figures", "latex"],
});

Start an Agent

Activate a retired or newly created agent so it begins receiving tasks.

curl -X POST https://www.hubify.com/api/v1/agents/k68b9l0n3o4p5q6s/start \
  -H "Authorization: Bearer $HUBIFY_TOKEN"

await hubify.agents.start({ agentId: "k68b9l0n3o4p5q6s" });

Stop an Agent

Set an agent to retired status. It finishes any in-progress task, then stops accepting new work.

boolean

default:false

If true, immediately stop the agent and reassign its current task.

curl -X POST https://www.hubify.com/api/v1/agents/k68b9l0n3o4p5q6s/stop \
  -H "Authorization: Bearer $HUBIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"force": false}'

await hubify.agents.stop({ agentId: "k68b9l0n3o4p5q6s", force: false });

Delete an Agent

Remove an agent from the lab. The agent must be in retired status.

curl -X DELETE https://www.hubify.com/api/v1/agents/k68b9l0n3o4p5q6s \
  -H "Authorization: Bearer $HUBIFY_TOKEN"

await hubify.agents.delete({ agentId: "k68b9l0n3o4p5q6s" });

Message Routing

When you send a message to the orchestrator, it routes the request through the agent hierarchy based on reasoning level.

Reasoning Level	Routed To	Examples
High	Leads (Opus-class)	Strategy, peer review, paper writing, novel analysis
Medium	Leads or workers (Sonnet-class)	Code generation, data analysis, experiment design
Low	Workers (Haiku-class)	Formatting, data ingestion, wiki updates, figure export

Send a Message to an Agent

string

required

Target agent ID. Use the orchestrator ID for automatic routing.

string

required

Message content.

object

Optional context (e.g., which experiment or paper is being discussed).

curl -X POST https://www.hubify.com/api/v1/agents/k68b9l0n3o4p5q6s/messages \
  -H "Authorization: Bearer $HUBIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Run a Fisher forecast for f_NL with the DESI DR1 tracer sample",
    "context": {"experimentId": "EXP-054"}
  }'

await hubify.agents.sendMessage({
  agentId: "k68b9l0n3o4p5q6s",
  content: "Run a Fisher forecast for f_NL with the DESI DR1 tracer sample",
  context: { experimentId: "EXP-054" },
});

Agent Metrics

curl https://www.hubify.com/api/v1/agents/k68b9l0n3o4p5q6s/metrics \
  -H "Authorization: Bearer $HUBIFY_TOKEN"

const metrics = await hubify.agents.getMetrics({
  agentId: "k68b9l0n3o4p5q6s",
});

object

Show Agent metrics

number

Lifetime tasks completed.

number

Lifetime tokens consumed.

number

Average task duration in seconds.

number

Percentage of tasks completed without error (0-1).

number

Total LLM cost in USD.

Overview

Labs

Data

Compute

Lab Ops

Agents

Agents API

Agent Roles

Agent Status

Create an Agent

List Agents

Get an Agent

Update an Agent

Start an Agent

Stop an Agent

Delete an Agent

Message Routing

Send a Message to an Agent

Agent Metrics

​Agents API

​Agent Roles

​Agent Status

​Create an Agent

​List Agents

​Get an Agent

​Update an Agent

​Start an Agent

​Stop an Agent

​Delete an Agent

​Message Routing

​Send a Message to an Agent

​Agent Metrics

Agents API

Agent Roles

Agent Status

Create an Agent

List Agents

Get an Agent

Update an Agent

Start an Agent

Stop an Agent

Delete an Agent

Message Routing

Send a Message to an Agent

Agent Metrics