pi-subagent-workflows

Inline-defined subagents and workflow orchestration for Pi.

There are no prebuilt agent roles. Every subagent is defined at spawn time by the orchestrating agent: a task, and optionally a role, model, thinking level, and tool/skill allowlists. For large batches, the orchestrator writes a workflow script that fans out workers and returns one consolidated result.

Install

pi install npm:pi-subagent-workflows

Or add "npm:pi-subagent-workflows" to the packages array in ~/.pi/agent/settings.json.

Tools

spawn_subagent

Runs a fresh-context subagent synchronously and returns its final reply.

| Param | | | |---|---|---| | task | required | Objective, scope, boundaries, expected output | | role | optional | System-prompt instructions for the worker | | model | optional | Exact ID from get_scoped_models | | thinking | optional | off–max | | tools / skills | optional | Allowlists; omit for all, [] for none | | label | optional | Short display name |

Output is plain text: a subagent_id: <id> header line followed by the worker's reply.

Workers are normal Pi AgentSessions. They automatically discover and bind all global extensions in print mode, except copies of this package's own extension, which are identified by package manifest and excluded to prevent recursion. No third-party extension is singled out. Tool selection then operates on Pi's effective tool surface, so same-named tools supplied by another extension remain available. Child resource selection is limited to tools and skills; there is no per-child extensions option.

message_subagent

Continues a spawned subagent by subagent_id. The full resolved spec (role, model, thinking, tools, skills) is persisted at spawn time, so follow-ups recreate the session deterministically.

get_scoped_models

Lists exact model IDs permitted by Pi's enabledModels.

Workflow library

pi-subagent-workflows/workflow is a programmatic orchestration layer for scripts run outside the Pi process:

import { createWorkflowRuntime } from "pi-subagent-workflows/workflow";

const wf = await createWorkflowRuntime({ budget: { maxTotalAgents: 30 } });
const audits = await wf.pipeline(files, async (file) => ({
  file,
  finding: (await wf.agent(`Audit ${file} for missing auth checks.`, { tools: ["read", "grep"] })).output,
}));
console.log(audits.filter((a) => a.finding !== "NONE"));

• agent(task, options) — one fresh Pi-native worker; options match spawn_subagent, plus schema for JSON-Schema-validated structured output with correction retries. Results may include warnings from resource selection or extensions.
• parallel(thunks) — barrier concurrency.
• pipeline(items, ...stages) — streaming stages, no barrier.
• Budgets — maxConcurrentAgents, maxTotalAgents, maxRuntime, maxRetriesPerItem, maxTotalTokens, maxTotalCost.
• Journal — completed calls are cached on disk keyed by task + spec; unchanged calls are served from cache on rerun.

Workflow workers use the same global extension discovery as direct workers and bind extensions before active tools are selected. Successful runs emit Pi's shutdown event and dispose before their final warnings are journaled and returned. Both paths keep projectTrusted: false. This package is the only extension package filtered from workers.

The packaged subagent-workflows skill teaches the orchestrating model both surfaces.

Settings

Under subagentWorkflows in Pi settings:

| Key | Default | | |---|---|---| | defaultModel | parent model | provider/model | | defaultThinking | parent level | | | maxConcurrentSubagents | 4 | Also the default workflow concurrency | | softTimeoutMinutes | 30 | Worker asked to wrap up | | hardTimeoutMinutes | 45 | Worker aborted | | summarizeOnTimeout | false | Summarize aborted runs | | timeoutSummaryModel | defaultModel | |

Development

npm test   # typecheck + node:test unit tests

License: 0BSD