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

# Agents

> The long-lived thing you talk to.

An agent is the long-lived thing. The record itself is small: a
[profile](/model/profiles) reference, an [identity](/model/identities), 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](/model/threads),
its private [memory](/model/memory), [schedules](/model/schedules), feed
[subscriptions](/model/feeds), 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.

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

A persistent per-agent sandbox for running commands and keeping files is
coming. Today, use the built-in `artifacts.*` tools for durable files.

<Info>
  **Belongs to** a workspace · **Has one** profile and one identity (immutable) ·
  **Owns** threads · memory · schedules · subscriptions · artifacts
</Info>

## Rules

* Tools come from the profile's roles, never from the agent. See
  [Rules](/model/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`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.