> ## Documentation Index
> Fetch the complete documentation index at: https://hubify.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Agents

> Configure, start, stop, and monitor AI agents in your lab's hierarchical multi-agent system.

# Agents API

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

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

<ParamField body="labId" type="string" required>
  Lab this agent belongs to.
</ParamField>

<ParamField body="name" type="string" required>
  Display name (e.g., "Research Lead", "Figure Worker").
</ParamField>

<ParamField body="role" type="string" required>
  Agent role: `orchestrator`, `lead`, or `worker`.
</ParamField>

<ParamField body="model" type="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`).
</ParamField>

<ParamField body="reportsTo" type="string">
  Convex ID of the agent this one reports to. Workers report to leads; leads report to the orchestrator.
</ParamField>

<ParamField body="systemPrompt" type="string">
  Custom system prompt. Overrides the default for this role.
</ParamField>

<ParamField body="capabilities" type="string[]">
  List of capabilities (e.g., `["code", "figures", "latex", "data-analysis"]`).
</ParamField>

<CodeGroup>
  ```bash curl theme={null}
  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"]
    }'
  ```

  ```typescript TypeScript SDK theme={null}
  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"],
  });
  ```
</CodeGroup>

<ResponseField name="data" type="object">
  <Expandable title="Agent object">
    <ResponseField name="_id" type="string" required>Convex document ID.</ResponseField>
    <ResponseField name="labId" type="string" required>Parent lab ID.</ResponseField>
    <ResponseField name="name" type="string" required>Display name.</ResponseField>
    <ResponseField name="role" type="string" required>Agent role.</ResponseField>
    <ResponseField name="model" type="string" required>Model identifier.</ResponseField>
    <ResponseField name="status" type="string" required>Current status.</ResponseField>
    <ResponseField name="reportsTo" type="string">ID of the supervising agent.</ResponseField>
    <ResponseField name="parentAgentId" type="string">ID of the agent that delegated the current task.</ResponseField>
    <ResponseField name="currentTaskDescription" type="string">What the agent is currently working on.</ResponseField>
    <ResponseField name="systemPrompt" type="string">Custom system prompt.</ResponseField>
    <ResponseField name="capabilities" type="string[]">Agent capabilities.</ResponseField>
    <ResponseField name="totalTasks" type="number" required>Lifetime tasks completed.</ResponseField>
    <ResponseField name="totalTokens" type="number" required>Lifetime tokens consumed.</ResponseField>
    <ResponseField name="createdAt" type="number" required>Creation timestamp (ms).</ResponseField>
  </Expandable>
</ResponseField>

## List Agents

<ParamField query="labId" type="string" required>
  Lab ID to list agents for.
</ParamField>

<ParamField query="role" type="string">
  Filter by role: `orchestrator`, `lead`, `worker`.
</ParamField>

<ParamField query="status" type="string">
  Filter by status: `active`, `idle`, `busy`, `retired`.
</ParamField>

<CodeGroup>
  ```bash curl theme={null}
  curl "https://www.hubify.com/api/v1/agents?labId=j57a8k9m2n3p4q5r&role=lead" \
    -H "Authorization: Bearer $HUBIFY_TOKEN"
  ```

  ```typescript TypeScript SDK theme={null}
  const leads = await hubify.agents.list({
    labId: "j57a8k9m2n3p4q5r",
    role: "lead",
  });
  ```
</CodeGroup>

## Get an Agent

<CodeGroup>
  ```bash curl theme={null}
  curl https://www.hubify.com/api/v1/agents/k68b9l0n3o4p5q6s \
    -H "Authorization: Bearer $HUBIFY_TOKEN"
  ```

  ```typescript TypeScript SDK theme={null}
  const agent = await hubify.agents.get({ agentId: "k68b9l0n3o4p5q6s" });
  ```
</CodeGroup>

## Update an Agent

<ParamField body="name" type="string">Updated display name.</ParamField>
<ParamField body="model" type="string">Change the model (e.g., upgrade from Sonnet to Opus).</ParamField>
<ParamField body="systemPrompt" type="string">Updated system prompt.</ParamField>
<ParamField body="capabilities" type="string[]">Updated capabilities list.</ParamField>
<ParamField body="reportsTo" type="string">Change the supervising agent.</ParamField>

<CodeGroup>
  ```bash curl theme={null}
  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"]
    }'
  ```

  ```typescript TypeScript SDK theme={null}
  await hubify.agents.update({
    agentId: "k68b9l0n3o4p5q6s",
    model: "claude-opus-4-8",
    capabilities: ["code", "data-analysis", "figures", "latex"],
  });
  ```
</CodeGroup>

## Start an Agent

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

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://www.hubify.com/api/v1/agents/k68b9l0n3o4p5q6s/start \
    -H "Authorization: Bearer $HUBIFY_TOKEN"
  ```

  ```typescript TypeScript SDK theme={null}
  await hubify.agents.start({ agentId: "k68b9l0n3o4p5q6s" });
  ```
</CodeGroup>

## Stop an Agent

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

<ParamField body="force" type="boolean" default={false}>
  If `true`, immediately stop the agent and reassign its current task.
</ParamField>

<CodeGroup>
  ```bash curl theme={null}
  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}'
  ```

  ```typescript TypeScript SDK theme={null}
  await hubify.agents.stop({ agentId: "k68b9l0n3o4p5q6s", force: false });
  ```
</CodeGroup>

## Delete an Agent

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

<CodeGroup>
  ```bash curl theme={null}
  curl -X DELETE https://www.hubify.com/api/v1/agents/k68b9l0n3o4p5q6s \
    -H "Authorization: Bearer $HUBIFY_TOKEN"
  ```

  ```typescript TypeScript SDK theme={null}
  await hubify.agents.delete({ agentId: "k68b9l0n3o4p5q6s" });
  ```
</CodeGroup>

## 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

<ParamField body="agentId" type="string" required>
  Target agent ID. Use the orchestrator ID for automatic routing.
</ParamField>

<ParamField body="content" type="string" required>
  Message content.
</ParamField>

<ParamField body="context" type="object">
  Optional context (e.g., which experiment or paper is being discussed).
</ParamField>

<CodeGroup>
  ```bash curl theme={null}
  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"}
    }'
  ```

  ```typescript TypeScript SDK theme={null}
  await hubify.agents.sendMessage({
    agentId: "k68b9l0n3o4p5q6s",
    content: "Run a Fisher forecast for f_NL with the DESI DR1 tracer sample",
    context: { experimentId: "EXP-054" },
  });
  ```
</CodeGroup>

## Agent Metrics

<CodeGroup>
  ```bash curl theme={null}
  curl https://www.hubify.com/api/v1/agents/k68b9l0n3o4p5q6s/metrics \
    -H "Authorization: Bearer $HUBIFY_TOKEN"
  ```

  ```typescript TypeScript SDK theme={null}
  const metrics = await hubify.agents.getMetrics({
    agentId: "k68b9l0n3o4p5q6s",
  });
  ```
</CodeGroup>

<ResponseField name="data" type="object">
  <Expandable title="Agent metrics">
    <ResponseField name="totalTasks" type="number">Lifetime tasks completed.</ResponseField>
    <ResponseField name="totalTokens" type="number">Lifetime tokens consumed.</ResponseField>
    <ResponseField name="averageTaskDuration" type="number">Average task duration in seconds.</ResponseField>
    <ResponseField name="successRate" type="number">Percentage of tasks completed without error (0-1).</ResponseField>
    <ResponseField name="costUsd" type="number">Total LLM cost in USD.</ResponseField>
  </Expandable>
</ResponseField>