Skip to main content
An agent is a durable named identity: a description, an avatar, system instructions, session defaults (template and coding agent), an evaluation rubric (evaluator_criteria), and a budget (economics). Sessions launched for the agent inherit its defaults, and the run grader scores each run against its rubric. Agents are distinct from the trigger integrations that launch them. A Slack app, GitHub App, Linear bot, or email inbox binds to an agent through config.agent_id on the integration; the agent row is the source of truth for defaults, and editing them fans out to every linked trigger.

​
Endpoints

All endpoints are organization scoped when the X-Organization-Id header is present; without it they operate on personal agents.

​
The agent object

​
string
Agent ID.
​
string | null
Owning organization, or null for a personal agent.
​
string
Display name (max 200 characters).
​
string | null
Short description (max 2000 characters).
​
object | null
Avatar descriptor, for example {"kind": "icon", "icon": "bot", "color": "blue"}.
​
string | null
Resolved avatar image URL (read only; synced from the avatar).
​
string | null
Instructions injected into every session the agent runs (max 20000 characters).
​
string | null
Org template slug sessions launch from. Editing it fans out to linked triggers.
​
string | null
Coding agent harness, for example claude-code or codex.
​
object | null
The rubric the run grader scores against: {"version": 1, "objective": "...", "checks": ["..."]}. The server bumps version on every edit so grades record which rubric produced them.
​
object | null
Task values and budget: {"tasks": {"triage": {"value_usd": 10, "minutes": 20}}, "default_task": {...}, "budget": {"monthly_usd_cap": 50}}. Feeds the scorecard’s value and budget columns.
​
string | null
Group that may edit, disable or delete the agent. Null = everyone in the org.
​
object | null
Who may launch it: {"humans": true, "groups": ["team_ops"], "agents": [{"agent_id": "...", "approval": {"required_team_id": "team_ops"}}]}. See Who may launch an agent.
​
string | null
Set when the kill switch is on: every launch is refused and the agent’s keys were revoked.
​
boolean | null
Whether this requester may launch it. Null for non-person callers.
​
boolean | null
Whether this requester may edit it — owning-group membership, or an admin override under the role access model.

​
Who may launch an agent

callable_by is a single allowlist spanning people and agents: Naming anyone closes the agent to everyone else, so an agent whose only entry is another agent is delegation-only — a person calling with their own key gets 403 AGENT_NOT_CALLABLE. Org admins keep their override under the role access model; humans: false is the hard switch that bars every person, admins included. An edge may also require an approval before each delegation. Trigger a subagent walks the whole flow. The roster itself is visible to every member of the organization; the restrictions ride on can_launch / can_edit rather than hiding rows.

​
The evaluation loop

  1. Set the rubric: PATCH /api/v1/agents/{id} with evaluator_criteria.
  2. The grader scores each completed run against it.
  3. Read one run’s verdict: Session Grade.
  4. Read the aggregate: Agent Scorecard.

​
CLI