Agents API

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.6, gpt-5.4
lead	Domain owner. Plans and executes within a domain. Takes over from failed workers.	Claude Opus 4.6, Claude Haiku 4.5, gpt-5.4
worker	Executes specific, scoped tasks dispatched by a lead.	Claude Haiku 4.5, gpt-5.4-mini

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

Lab this agent belongs to.

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

Agent role: orchestrator, lead, or worker.

Model identifier (e.g., claude-opus-4-6, gpt-5.4, gemini-2.5-pro, grok-3).

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

Custom system prompt. Overrides the default for this role.

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

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

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

Convex document ID.
Parent lab ID.
Display name.
Agent role.
Model identifier.
Current status.
ID of the supervising agent.
ID of the agent that delegated the current task.
What the agent is currently working on.
Custom system prompt.
Agent capabilities.
Lifetime tasks completed.
Lifetime tokens consumed.
Creation timestamp (ms).

List Agents

Lab ID to list agents for.

Filter by role: orchestrator, lead, worker.

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

curl "https://api.hubify.com/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://api.hubify.com/v1/agents/k68b9l0n3o4p5q6s \
  -H "Authorization: Bearer $HUBIFY_TOKEN"

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

Update an Agent

Updated display name. Change the model (e.g., upgrade from Sonnet to Opus). Updated system prompt. Updated capabilities list. Change the supervising agent.

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

await hubify.agents.update({
  agentId: "k68b9l0n3o4p5q6s",
  model: "claude-opus-4-6",
  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://api.hubify.com/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.

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

curl -X POST https://api.hubify.com/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://api.hubify.com/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

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

Message content.

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

curl -X POST https://api.hubify.com/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://api.hubify.com/v1/agents/k68b9l0n3o4p5q6s/metrics \
  -H "Authorization: Bearer $HUBIFY_TOKEN"

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

Lifetime tasks completed.
Lifetime tokens consumed.
Average task duration in seconds.
Percentage of tasks completed without error (0-1).
Total LLM cost in USD.