Build your first agent

The Quickstart gave the agent every tool in the workspace. This time you’ll pick the tools yourself, keep the behavior in a profile other agents can share, and give the agent an identity you can trace its calls back to.

1. Create a role

An agent gets its tools from a role and nowhere else. This one reads the web and keeps notes:

export ROLE_ID="$(
  curl --fail --silent --show-error "https://api.matrices.com/v1/roles" \
    -H "Authorization: Bearer $MATRICES_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Research reader",
      "description": "Reads the web and keeps its own notes.",
      "allow": ["tool:builtin:web.*", "tool:builtin:memory.*"]
    }' | jq -er '.role.id'
)"

Every workspace also comes with an Administrator role that grants tool:*. That’s fine while you’re poking around, but too much for an agent you leave running.

2. Create a profile

A profile is everything about how the agent behaves: the models it may use, the instructions it always carries, and the roles its tools come from.

export PROFILE_ID="$(
  curl --fail --silent --show-error "https://api.matrices.com/v1/profiles" \
    -H "Authorization: Bearer $MATRICES_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Research assistant",
      "configuration": {
        "models": ["anthropic/claude-sonnet-5"],
        "roleIds": ["'"$ROLE_ID"'"],
        "systemPrompt": "Answer with sources. Cite every URL you used, and save anything worth remembering with memory.write."
      }
    }' | jq -er '.profile.id'
)"

Leave hooks out and you get the six default approvals.

3. Create the agent

The agent is the part that sticks around. It owns the threads and the memory:

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": "Research assistant",
      "profileId": "'"$PROFILE_ID"'",
      "identity": "svc:research"
    }' | jq -er '.agent.id'
)"

identity is required, and you can’t change it later. Use a stable value from your own system: user_123 for a person, svc:research for your product. See Identities.

4. Start a thread

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": "What changed in the EU AI Act this month? Cite your sources." }
      ]
    }' | jq -er '.threadId'
)"

Check it worked

Ask what the agent can call. This is the same answer Matrices enforces at run time:

curl --fail --silent --show-error -H "Authorization: Bearer $MATRICES_API_KEY" \
  "https://api.matrices.com/v1/agents/$AGENT_ID/effective-permissions" | jq '.builtIns'

That should be the web.* and memory.* tools and nothing else. Now read the thread’s log:

curl --fail --silent --show-error -H "Authorization: Bearer $MATRICES_API_KEY" \
  "https://api.matrices.com/v1/threads/$THREAD_ID/events?limit=100" |
  jq -r '.events[] | "\(.seq) \(.type)"'

Each tool call shows up as a tool_intent followed by its tool_result. The answer is an assistant_message. See Thread events.

Start here

The model

Rules

Guides

Reference

Resources

Build your first agent

1. Create a role

2. Create a profile

3. Create the agent

4. Start a thread

Check it worked

Where next

Narrow the permissions

Connect a service

​1. Create a role

​2. Create a profile

​3. Create the agent

​4. Start a thread

​Check it worked

​Where next

Narrow the permissions

Connect a service

1. Create a role

2. Create a profile

3. Create the agent

4. Start a thread

Check it worked

Where next