Skip to main content
An agent is the long-lived thing. The record itself is small: a profile reference, an identity, a name and description, up to 32 tags, an optional avatar, and an optional budget that caps USD spend per 24h, 7d, or total. Tools aren’t on that list on purpose. They come from the profile’s roles. What an agent does own is everything it produces: its threads, its private memory, schedules, feed subscriptions, and its artifacts, sites, and images. No other agent can read any of that directly; it has to ask. In practice you usually want one agent per end user. That agent’s identity is the person, so their history, notes, and credentials all hang off it, while the behavior everyone shares lives in one profile. Give a person a second agent only when the work needs separate memory and threads. Agents can also work with other agents. agents.ask asks a sibling a question and waits for the answer. agents.create makes a new one, always under the caller’s own identity and never with more access than the caller has.
Coming soon. This capability is part of where Matrices is heading, but its public API is not generally available yet. The shapes shown here describe the intended contract and may change before release.
A persistent per-agent sandbox for running commands and keeping files is coming. Today, use the built-in artifacts.* tools for durable files.
Belongs to a workspace · Has one profile and one identity (immutable) · Owns threads · memory · schedules · subscriptions · artifacts

​
Rules

  • Tools come from the profile’s roles, never from the agent. See Rules.
  • An agent that creates an agent can only pass down access it already has, and always passes down its identity.
  • Disabling the identity stops every agent under it from taking new work.

​
API

  • GET/POST /v1/agents, PATCH/DELETE /v1/agents/{agentId}.
  • POST /v1/agents also accepts an inline profile instead of a profileId.