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