docs

Multi-Agent

Define multiple agents in a single agentfile.yaml. They run as separate Docker containers on a shared bridge network and communicate via HTTP handoffs.

Define a multi-agent file

agentfile.yaml

agents:
  orchestrator:
    metadata:
      role: Task coordinator
      goal: Analyze requests and delegate to the right specialist
    runtime:
      provider: anthropic
      model: claude-sonnet-4-6
    collaborators: [researcher, writer]   # can hand off to either

  researcher:
    metadata:
      role: Web researcher
      goal: Find accurate information using search
    runtime:
      provider: anthropic
      model: claude-haiku-4-5-20251001
    tools:
      - { name: web_search, source: mcp://brave-search }

  writer:
    metadata:
      role: Content writer
      goal: Write polished documents based on research
    runtime:
      provider: openai
      model: gpt-4o

Start the network

Bash

ninetrix up      # starts all agents on a Docker bridge network
ninetrix status  # show running containers
ninetrix invoke  # send a message to the entry agent
ninetrix logs    # stream logs from all agents with [agent_name] prefix
ninetrix down    # clean shutdown

How handoffs work

Each agent with collaborators automatically gets a transfer_to_agent tool. When called, it POSTs the message to the target agent's /invoke endpoint on the bridge network and streams the response back.

Each container is named ninetrix-{agent_name} and reachable via DNS on the bridge
Peer URLs are injected as AGENTFILE_PEER_{NAME}_URL=http://{agent_name}:9000
Handoffs are traced — the dashboard shows the full multi-agent call tree
parent_trace_id links sub-agent runs back to the parent

Parallel handoffs

If an agent has 2+ collaborators, it also receives a transfer_to_agents_parallel tool for concurrent delegation:

YAML

collaborators: [researcher, analyst, writer]  # 3 collaborators → parallel tool available

Network architecture

Detail	Value
Docker network	`ninetrix-{entry_agent}-swarm`
Container names	`ninetrix-{agent_name}`
Entry agent port	9000 (mapped to host)
Other agents	9001, 9002, ... (internal only)
Inter-agent calls	`http://{agent_name}:9000`
Pool state	`~/.agentfile/pools/{swarm_name}.json`

Invoke a running agent

Bash

# Send a message to the entry agent
ninetrix invoke --message "Research the latest AI news"

# Send to a specific agent
ninetrix invoke --agent researcher --message "What is RAG?"

#Define a multi-agent file

#Start the network

#How handoffs work

#Parallel handoffs