Write a YAML file. Run a team of agents.

The Idea ​

Suzumio is a YAML-based multi-agent system. You write a project file that says:

• what the project is trying to accomplish;
• which agents exist;
• what each agent is allowed to do;
• agent coordination rules;
• which Docker runner and model presets to use.

The runtime stores state in SQLite, starts Docker activations, delivers messages as signals, applies priority rules, mounts shared files, and records tool calls.

A Tiny Project ​

This is the smallest useful shape. One pm agent receives user messages, can message the user or other agents, can wait for future signals, and can submit a final report.

name: tiny-research
task: |
  Answer the user's question carefully. If you are missing information,
  ask a follow-up instead of pretending.

tools:
  toolpacks:
    - core

agents:
  pm:
    role: project-manager
    displayName: Yuki
    prompt: |
      You coordinate the project. Keep a short working memory in your messages.
      Submit only when the answer is ready for the user.
    tools:
      - messages.send
      - coordination.wait_for_signal
      - completion.submit

Run it with:

suzumio config render tiny-research.yaml
suzumio init tiny-research.yaml
suzumio serve --host 0.0.0.0 --port 39400
suzumio start tiny-research
suzumio send tiny-research pm P1 "Start."

Documentation Order ​

The Default Collaboration Loop ​

1. A user sends a message to an agent, usually pm.
2. That message becomes a pending message.created signal.
3. The scheduler starts one Docker activation for the idle target agent.
4. The agent can send messages, run tools, write /artifacts/<agent-id> files, wait, or submit.
5. If it messages another agent, that creates a pending signal for the recipient.
6. If it calls coordination.wait_for_signal, the activation ends cleanly and the agent stays quiet.
7. If it calls completion.submit, the project is marked submitted and a final report is written.

Good YAML Produces Good Coordination ​

The most important design skill is not writing long prompts. It is assigning clear responsibilities and giving each agent just enough tools.

Use a PM when:

• the project needs delegation;
• multiple reports must be merged;
• someone must decide when the final answer is ready.

Use workers when:

• tasks can be explored independently;
• you want separate attempts, experiments, or proofs;
• you want the PM to compare evidence rather than invent everything alone.

Use a critic/checker when:

• final output needs review;
• hallucinated certainty is dangerous;
• workers may produce incompatible claims.

Use shell.exec when:

• the agent runs Python, tests, scripts, or local searches;
• the result is saved under /artifacts/<agent-id>;
• evidence matters more than prose.

Project Layout ​

After suzumio init, the runtime root contains the project state generated from YAML:

$SUZUMIO_ROOT/tiny-research/
  suzumio.sqlite      durable project database
  source.yaml         original project config
  resolved.yaml       fully resolved config
  agents/             per-agent workspaces
  artifacts/          per-agent shared files
  activations/        activation input directories
  logs/               reserved for runtime logs

Where To Go Next ​