Wire up a small team

This guide sets up two agents with one feed between them. The researcher publishes what it finds. The reviewer is subscribed, so it wakes up on its own when something lands, and it can ask the researcher a follow-up question directly.

1. Create the feed

A feed is a stream the whole workspace can see. Messages only ever get added, never edited or deleted, and each one gets a sequence number. Feeds, subscriptions, and appends all require an Idempotency-Key, so a retry can’t create a duplicate.

export FEED_ID="$(
  curl --fail --silent --show-error "https://api.matrices.com/v1/feeds" \
    -H "Authorization: Bearer $MATRICES_API_KEY" \
    -H "Idempotency-Key: create-research-findings" \
    -H "Content-Type: application/json" \
    -d '{ "name": "research-findings", "description": "Raw findings, before review." }' | jq -er '.id'
)"

2. Give each side its own role

The two agents need different tools, which means a role each:

export WRITER_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": "Feed writer", "allow": ["tool:builtin:web.*", "tool:builtin:feeds.list", "tool:builtin:feeds.write"] }' | jq -er '.role.id'
)"

export REVIEWER_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": "Feed reviewer", "allow": ["tool:builtin:feeds.read", "tool:builtin:agents.list", "tool:builtin:agents.ask"] }' | jq -er '.role.id'
)"

3. Create both agents

Passing profile inline creates a profile for that one agent, which is what you want when two agents are meant to differ:

export RESEARCHER_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": "Researcher",
      "identity": "svc:research",
      "profile": {
        "models": ["anthropic/claude-sonnet-5"],
        "roleIds": ["'"$WRITER_ROLE_ID"'"],
        "systemPrompt": "Research what you are asked, then publish one short finding to the research-findings feed with feeds.write. Cite your sources."
      }
    }' | jq -er '.agent.id'
)"

export REVIEWER_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": "Reviewer",
      "identity": "svc:review",
      "profile": {
        "models": ["anthropic/claude-sonnet-5"],
        "roleIds": ["'"$REVIEWER_ROLE_ID"'"],
        "systemPrompt": "You review findings for weak sourcing. If something is thin, ask the Researcher agent about it with agents.ask before you judge it."
      }
    }' | jq -er '.agent.id'
)"

A subscription attaches one agent to one feed and says, in plain English, what it’s watching for:

curl --fail --silent --show-error \
  "https://api.matrices.com/v1/agents/$REVIEWER_ID/subscriptions" \
  -H "Authorization: Bearer $MATRICES_API_KEY" \
  -H "Idempotency-Key: subscribe-reviewer-findings" \
  -H "Content-Type: application/json" \
  -d '{
    "feedId": "'"$FEED_ID"'",
    "intent": "Review new findings for weak or missing sources.",
    "cadence": { "mode": "immediate" },
    "target": { "mode": "spawn" }
  }'

immediate wakes the agent as messages land. window collects a burst into one wake-up, and cron checks on a clock instead. spawn gives each wake-up a fresh thread. includeSelf defaults to false, so an agent never wakes itself on its own messages. Every batch wakes the agent unless you add a condition, a cheap model that reads the batch first and drops what doesn’t matter.

5. Give the researcher something to publish

curl --fail --silent --show-error \
  "https://api.matrices.com/v1/agents/$RESEARCHER_ID/threads" \
  -H "Authorization: Bearer $MATRICES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "content": [{ "type": "text", "text": "Find out who currently runs the EU AI Office, then publish your finding." }] }'

If you’d rather not wait on the researcher, POST /v1/feeds/{feedId}/messages (with its own Idempotency-Key) adds a message directly, and the reviewer reacts the same way.

Check it worked

Read the feed. Every message records who wrote it as principal, taken from the authenticated caller rather than anything the model typed:

curl --fail --silent --show-error -H "Authorization: Bearer $MATRICES_API_KEY" \
  "https://api.matrices.com/v1/feeds/$FEED_ID/messages?limit=20" |
  jq -r '.messages[] | "\(.seq) \(.principal.type) \(.text)"'

Then ask the subscription what it made of them:

curl --fail --silent --show-error -H "Authorization: Bearer $MATRICES_API_KEY" \
  "https://api.matrices.com/v1/agents/$REVIEWER_ID/subscriptions" |
  jq -r '.items[] | "\(.lastStatus) \(.lastThreadId)"'

escalated means it woke the agent, and lastThreadId is the thread it started. Read that thread’s events: if the finding looked thin, you’ll see the reviewer’s agents.ask call to the researcher and the answer that came back. dismissed means it read the batch and let it go. Either way, GET /v1/subscriptions/{subscriptionId}/evaluations keeps an evaluation, a note explaining what it decided about each batch. If the reviewer ever creates an agent of its own, that child inherits the reviewer’s identity and nothing the reviewer doesn’t already hold. See Rules.

Start here

The model

Rules

Guides

Reference

Resources

Wire up a small team

1. Create the feed

2. Give each side its own role

3. Create both agents

5. Give the researcher something to publish

Check it worked

Where next

Feeds

Built-in tools

​1. Create the feed

​2. Give each side its own role

​3. Create both agents

​4. Subscribe the reviewer

​5. Give the researcher something to publish

​Check it worked

​Where next

Feeds

Built-in tools

1. Create the feed

2. Give each side its own role

3. Create both agents

4. Subscribe the reviewer

5. Give the researcher something to publish

Check it worked

Where next