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

# Quickstart

Let's get an agent running. You'll create one with its model, instructions, and
tools, then start a thread with your first prompt.

Grab an API key from [**Matrices**](https://matrices.com/): create a workspace,
then create a key for it. You'll also need **curl** and **jq** for the commands
below. Copy the key and export it to your shell:

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
export MATRICES_API_KEY="mtx_sk_example"
```

That one key authenticates every call below.

## 1. Create an agent

An agent gets its tools from the roles in its profile. Every new workspace comes
with an `Administrator` role that grants all tools (`tool:*`). Grab its ID:

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
export ROLE_ID="$(
  curl --fail --silent --show-error "https://api.matrices.com/v1/roles?limit=50" \
    -H "Authorization: Bearer $MATRICES_API_KEY" |
    jq -er '.roles[] | select(.name == "Administrator") | .id'
)"
```

Now create the agent and its profile together:

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
export AGENT_ID="$(
  curl --fail --silent --show-error "https://api.matrices.com/v1/agents" \
    -H "Authorization: Bearer $MATRICES_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Workspace guide",
      "identity": "svc:quickstart",
      "profile": {
        "models": ["anthropic/claude-sonnet-5"],
        "roleIds": ["'"$ROLE_ID"'"],
        "systemPrompt": "Be concise. When asked about available agents, use the agents.list tool."
      }
    }' | jq -er '.agent.id'
)"
```

That's a complete agent:

* `identity` is who it acts for, and it never changes. See [Identities](/model/identities).
* `roleIds` is where every tool comes from. See [Roles](/model/roles).
* `models` lists the models it may use, in order, as exact IDs or wildcards. See [Models](/reference/models).
* `systemPrompt` is the instructions it always carries. See [Profiles](/model/profiles).

Passing `profile` inline creates a profile just for this agent. Create profiles
separately when several agents should share one.

<Tip>
  To call your own tools, register a client or MCP [toolset](/model/toolsets),
  then grant its names in a role, such as `tool:workspace:billing.lookup_invoice`.
</Tip>

## 2. Start a thread

Start a thread by sending the agent its first user prompt as a text content block:

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
export THREAD_ID="$(
  curl --fail --silent --show-error \
    "https://api.matrices.com/v1/agents/$AGENT_ID/threads" \
    -H "Authorization: Bearer $MATRICES_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "content": [
        {
          "type": "text",
          "text": "Which agents are available in this workspace? Summarize each in one sentence."
        }
      ]
    }' | jq -er '.threadId'
)"
```

The response also includes a `turnId` and a status. The turn runs in the
background.

## 3. Stream the result

Connect to the thread's event stream to watch the agent reply:

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
curl --no-buffer --fail --silent --show-error \
  "https://api.matrices.com/v1/threads/$THREAD_ID/events/stream" \
  -H "Authorization: Bearer $MATRICES_API_KEY"
```

The stream is Server-Sent Events, and it's for watching the turn as it
happens. The durable record is the log at `GET /v1/threads/{threadId}/events`,
which you can read back any time. See [Threads](/model/threads).

## What's next

<CardGroup cols={2}>
  <Card title="How it fits together" icon="layers" href="/model/how-it-fits-together">
    Every noun, and what owns what.
  </Card>

  <Card title="Build a real agent" icon="box" href="/guides/first-agent">
    Roles, profiles, and identity, in the order they matter.
  </Card>

  <Card title="Narrow the permissions" icon="shield" href="/guides/narrow-permissions">
    Cut an agent down to the tools it should have.
  </Card>

  <Card title="Connect a service" icon="link" href="/guides/connect-a-service">
    Give an agent credentials without showing the model a secret.
  </Card>
</CardGroup>


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