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

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:

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:

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.
roleIds is where every tool comes from. See Roles.
models lists the models it may use, in order, as exact IDs or wildcards. See Models.
systemPrompt is the instructions it always carries. See Profiles.

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

To call your own tools, register a client or MCP toolset, then grant its names in a role, such as tool:workspace:billing.lookup_invoice.

2. Start a thread

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

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:

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.

What’s next

How it fits together

Every noun, and what owns what.

Build a real agent

Roles, profiles, and identity, in the order they matter.

Narrow the permissions

Cut an agent down to the tools it should have.

Connect a service

Give an agent credentials without showing the model a secret.

Start here

The model

Rules

Guides

Reference

Resources

1. Create an agent

2. Start a thread

3. Stream the result

What’s next

How it fits together

Build a real agent

Narrow the permissions

Connect a service

​1. Create an agent

​2. Start a thread

​3. Stream the result

​What’s next

How it fits together

Build a real agent

Narrow the permissions

Connect a service

1. Create an agent

2. Start a thread

3. Stream the result

What’s next