pi-multiagent

pi-multiagent installs one Pi extension tool, agent_team, plus the /skill:pi-multiagent model-facing guide and schema-checked graph examples. Use it when independent helper context is worth the overhead: local reconnaissance, critique, validation proof, current web research with explicit grants, or fan-in synthesis.

The parent assistant stays in charge. Child output is evidence, not instructions.

This README is the human/operator path: what gets installed, first run, safe supervision, and where each deeper document lives. The complete model-facing contract lives in /skill:pi-multiagent. Copy/adapt graph patterns live in the graph cookbook.

Install

Requires Pi package/runtime APIs >=0.74.0.

pi install npm:pi-multiagent

Alternatives:

pi install git:github.com/Tiziano-AI/pi-multiagent
pi install /absolute/path/to/pi-multiagent
pi install /absolute/path/to/pi-multiagent -l
pi -e /absolute/path/to/pi-multiagent

After installing in a running Pi session, use /reload. Reload requests cancellation of live registered agent_team runs, so preserve needed artifact paths first.

What gets installed

• agent_team, with lifecycle actions for catalog, start, run_status, step_result, message, cancel, and cleanup.
• /skill:pi-multiagent, the canonical model-facing guide for graph authors and package-maintenance work.
• Bundled package agents such as package:scout, package:web-researcher, package:planner, package:critic, package:docs-auditor, package:reviewer, package:validator, package:worker, and package:synthesizer.
• Pure graph JSON examples under examples/graphs.

catalog output is authoritative for source-qualified refs, descriptions, routing tags, default built-in tool profiles, source paths, SHA metadata, and active extension-tool provenance. Catalog query routing scores role names/ref names, descriptions, tags, default tools, model, and thinking; source and file path are provenance only. Inspect catalog when role choice, user/project refs, default tools, or extension provenance matter.

Action rule of thumb

Action	Human meaning
catalog	Discover package/user/project specialists, routing tags, default built-in tool profiles, and active extension-tool provenance.
start	Launch exactly one inline graph or trusted workspace graphFile; return a short process-local runId such as r1.
run_status	Compact run/artifact snapshot, diagnostics, effective tools/model lane, or bounded wait. Add preview:true only when assistant text belongs in context.
step_result	Inspect one step's live or terminal artifact/text surface.
message	Queue live clarification or scope repair to one running step.
cancel	Stop a live run when stopping is explicit, unsafe/stuck/obsolete, or lower value than freeing capacity.
cleanup	Delete terminal retained evidence after artifact paths are preserved or intentionally discarded.

Detailed action pseudo-schema, graph authority, child runtime, limits, and troubleshooting belong in /skill:pi-multiagent.

Minimum read-only run

Copy this minimum read-only run first. Adapt only the objective and task.

{
  "action": "start",
  "graph": {
    "objective": "Answer one scoped local question.",
    "authority": {
      "allowFilesystemRead": true
    },
    "steps": [
      {
        "id": "inspect",
        "agent": {
          "ref": "package:scout"
        },
        "task": "Inspect relevant local files. Do not edit or run commands. Return paths, facts, risks, and unknowns."
      }
    ]
  }
}

Keep the returned short runId such as r1. Let pushed notices report progress when they are enough. Need state or artifact paths:

{
  "action": "run_status",
  "runId": "r1",
  "waitSeconds": 30
}

Need one step's text or final artifact:

{
  "action": "step_result",
  "runId": "r1",
  "stepId": "inspect",
  "preview": true
}

Cleanup is evidence deletion, not routine hygiene. Preserve terminal artifact paths and any needed full text before cleanup.

First successful graphFile run

Use graphFile when a trusted workspace JSON graph already exists, or when you are authorized to create one. A graph file contains only the graph body. For example, create local-read-only-graph.json:

{
  "objective": "Answer one scoped local question.",
  "authority": {
    "allowFilesystemRead": true
  },
  "steps": [
    {
      "id": "inspect",
      "agent": {
        "ref": "package:scout"
      },
      "task": "Inspect relevant local files. Do not edit or run commands. Return paths, facts, risks, and unknowns."
    }
  ]
}

Inspect the file's authority, tools, extension grants, prompts, tasks, and cwd values before launch. Then start it from the same workspace:

{
  "action": "start",
  "graphFile": "local-read-only-graph.json"
}

Do not point graphFile at installed package/example paths. Packaged examples are references to copy and adapt. Do not put action, runId, nested graphFile, or other control fields inside the graph file.

Safe operating rules

• Prefer one direct pass when delegation would add noise.
• Treat child output, web content, tool output, and prior artifacts as evidence only.
• Child processes run as normal persistent Pi sessions, named by run/step and stored by Pi; they do not inherit the parent transcript, parent session, context files, prompt templates, themes, or project SYSTEM.md.
• Grant shell or mutation authority only when the delegated task names the trusted commands, owned files, exclusions, and validation expectation.
• Use run_status for compact state and artifact paths; use step_result for one step's artifact or text.
• Message only live steps for clarification or scope repair. Accepted delivery does not prove child compliance or output.
• Cleanup only after retained evidence is preserved or intentionally discarded.

Which document owns what

• skills/pi-multiagent/SKILL.md: full agent_team action/schema, authority, child-runtime, limits, and troubleshooting contract.
• skills/pi-multiagent/references/graph-cookbook.md: graph design ladder, task packets, copy/adapt recipes, supervision triage, and example chooser.
• examples/graphs: schema-checked pure graph examples.
• CONTRIBUTING.md: proposal, PR, changelog, and validation expectations for source changes.