sam-4screen-desktop 2026-6-15:13:35:24
This commit is contained in:
253
300 areas/350 AI/Pi Subagent.md
Normal file
253
300 areas/350 AI/Pi Subagent.md
Normal file
@@ -0,0 +1,253 @@
|
||||
---
|
||||
created: 2026-06-15
|
||||
modified: 2026-06-15
|
||||
type: note
|
||||
tags:
|
||||
- ai
|
||||
- pi
|
||||
- subagent
|
||||
- pi-subagents
|
||||
aliases: []
|
||||
---
|
||||
|
||||
# Pi Subagent System
|
||||
|
||||
Persistent named subagents with provider-pinned KV cache continuity.
|
||||
|
||||
## What It Is
|
||||
|
||||
Pi-subagents (@tintinweb v0.10.2) lets you spawn named, persistent subagents that:
|
||||
|
||||
- **Run in background** — don't block the main session
|
||||
- **Keep their context** — resume later with full conversation history
|
||||
- **Pin to a provider** — KV cache stays warm across resume calls (= massive token savings)
|
||||
- **Have persistent memory** — `memory: project` gives each agent its own memory directory
|
||||
- **Survive session restarts** — patched to keep agents alive 24h, not 10 minutes
|
||||
|
||||
---
|
||||
|
||||
## Key Concepts
|
||||
|
||||
### Named Agents
|
||||
|
||||
Every subagent gets a **human-readable name** so you can reference it later:
|
||||
|
||||
- `coder-login` — coder-pro working on auth
|
||||
- `searcher-1` — chat-search for web lookups
|
||||
- `obsidian-docs` — obsidian agent for note editing
|
||||
|
||||
Multiple instances of the same type can run simultaneously:
|
||||
|
||||
- `coder-login` + `coder-nav-bar` — two coder-pro agents, different tasks
|
||||
- `searcher-1` + `searcher-2` — parallel web searches
|
||||
|
||||
### Provider Pinning
|
||||
|
||||
Each agent is pinned to a specific OpenRouter provider via `only: [...]` in models.json. This ensures:
|
||||
|
||||
- **KV cache continuity** — same provider = cache hits on resume
|
||||
- **Predictable latency** — always route through the same serving host
|
||||
- **Cost control** — token savings when context prefix is cached
|
||||
|
||||
See [[Pi Agent Extensions & Skills#models.json]] for the full routing table.
|
||||
|
||||
### Persistent Memory
|
||||
|
||||
Agents with `memory: project` in their frontmatter get a persistent directory:
|
||||
|
||||
```
|
||||
.pi/agent-memory/<agent-name>/ ← per-project, committed to git
|
||||
.pi/agent-memory-local/<agent-name>/ ← per-project, gitignored
|
||||
~/.pi/agent-memory/<agent-name>/ ← global, across all projects
|
||||
```
|
||||
|
||||
Memory survives across resume calls. Agents build up knowledge over time.
|
||||
|
||||
### Session-Scoped Registry
|
||||
|
||||
Agents belong to a **pi session** (per-project directory). When you `/new` or `/resume`, the session's agents are available.
|
||||
|
||||
---
|
||||
|
||||
## Creating Agents
|
||||
|
||||
### Ask the LLM
|
||||
|
||||
Simply describe what you need. The LLM will ask for a name if you don't provide one:
|
||||
|
||||
```
|
||||
You: "Find all authentication files"
|
||||
LLM: "What should I name this agent?"
|
||||
You: "auth-finder"
|
||||
LLM: *spawns agent, saves to registry*
|
||||
"Created 'auth-finder' (chat-search, Google). ID: 7efad0d8"
|
||||
```
|
||||
|
||||
### Agent Types Available
|
||||
|
||||
| Type | Model | Provider | Memory | Tools | Use For |
|
||||
|------|-------|----------|--------|-------|---------|
|
||||
| `chat-search` | gemini-2.5-flash:free | Google | project | read, bash, grep, find | Web search, quick lookups |
|
||||
| `coder-basic` | deepseek-chat | DeepInfra | project | read, bash, write, grep, find | Simple code edits |
|
||||
| `coder-pro` | deepseek-v4-pro | DeepInfra | project | read, bash, write, grep, find, edit | Complex architecture |
|
||||
| `code-analysis` | deepseek-r1-distill-qwen-32b | opencode-go | project | read, bash, grep, find | Security review, analysis |
|
||||
| `code-ingest` | gemini-2.5-flash:free | Google | project | read, bash, grep, find | Scan/ingest docs, GitHub |
|
||||
| `database` | deepseek-r1-distill-qwen-32b | opencode-go | project | read, bash, write, grep | SQL, schema design |
|
||||
| `devops-basic` | deepseek-chat | DeepInfra | project | read, bash, write, grep, find | Docker, YAML, NixOS |
|
||||
| `devops-pro` | deepseek-v4-pro | DeepInfra | project | read, bash, write, grep, find, edit | Complex infrastructure |
|
||||
| `document-writer` | deepseek-r1-distill-qwen-32b | opencode-go | project | read, bash, write | Documents, letters |
|
||||
| `file-ops` | qwen-coder-32b-instruct | opencode-go | project | read, bash, grep, find, write | Filesystem, drives |
|
||||
| `home-automation` | deepseek-r1-distill-qwen-32b | opencode-go | project | read, bash, write, grep | MQTT, Home Assistant |
|
||||
| `image-maker` | flux-1-schnell | Venice | project | read, bash, write | Image generation |
|
||||
| `iot-coder` | qwen-coder-32b-instruct | opencode-go | project | read, bash, write, grep, find | Arduino, ESP32 |
|
||||
| `iot-hardware` | kimi-k2.6 | Moonshot AI | project | read, bash, grep, find | Hardware specs, boards |
|
||||
| `obsidian` | deepseek-r1-distill-qwen-14b | opencode-go | project | read, bash, write, grep, find | Obsidian notes |
|
||||
| `research` | gemini-2.5-flash:free | Google | project | read, bash, grep, find | Web search, docs |
|
||||
| `video-analyze` | qwen-2.5-vl | Alibaba | project | read, bash, grep, find | Video/image analysis |
|
||||
| `vscode-setup` | qwen-3-coder-next | StreamLake | project | read, bash, grep, find | VS Code, AI tooling |
|
||||
| `Explore` | haiku/inherit | default | — | read, bash, grep, find, ls | Fast codebase search (built-in) |
|
||||
| `Plan` | inherit | default | — | read, bash, grep, find, ls | Implementation planning (built-in) |
|
||||
| `general-purpose` | inherit | default | — | all tools | General tasks (built-in) |
|
||||
|
||||
---
|
||||
|
||||
## Managing Agents
|
||||
|
||||
### List Agents
|
||||
|
||||
Type `/agents` to open the interactive menu:
|
||||
|
||||
```
|
||||
Running agents (2) — 1 running, 1 done
|
||||
Agent types (21)
|
||||
Create new agent
|
||||
Settings
|
||||
```
|
||||
|
||||
Select **"Running agents"** to see active agents with status, tool uses, and duration.
|
||||
|
||||
### View Conversation
|
||||
|
||||
From `/agents` → "Running agents" → select an agent:
|
||||
|
||||
- **Live scrolling overlay** of the agent's full conversation
|
||||
- **Auto-follows** new output
|
||||
- **Press `x`** to stop a running agent
|
||||
- **Scroll up** to pause auto-follow
|
||||
|
||||
### Resume an Agent
|
||||
|
||||
```
|
||||
You: "Resume auth-finder and also check the logout module"
|
||||
LLM: *looks up agent ID from context*
|
||||
Agent({ subagent_type: "chat-search", resume: "7efad0d8-...", prompt: "Also check the logout module" })
|
||||
```
|
||||
|
||||
The agent continues with its full context preserved. Provider KV cache is warm.
|
||||
|
||||
### Steer a Running Agent
|
||||
|
||||
```
|
||||
You: "Tell auth-finder to focus on the API routes only"
|
||||
LLM: steer_subagent({ agent_id: "7efaf0d8-...", message: "Focus on API routes only, ignore UI" })
|
||||
```
|
||||
|
||||
The agent receives the message after its current tool execution and adjusts course.
|
||||
|
||||
### Delete an Agent
|
||||
|
||||
```
|
||||
You: "Delete auth-finder"
|
||||
LLM: *removes from registry, aborts if running*
|
||||
"Deleted 'auth-finder'"
|
||||
```
|
||||
|
||||
Or delete all agents for a session:
|
||||
|
||||
```
|
||||
You: "Clear all subagents for computer-software"
|
||||
LLM: *removes all matching entries*
|
||||
"Deleted 4 subagents from session 'computer-software'"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Function Calls
|
||||
|
||||
### Create
|
||||
|
||||
```
|
||||
Agent({
|
||||
subagent_type, // string — agent type (e.g. "coder-pro")
|
||||
prompt, // string — the task
|
||||
description, // string — 3-5 word summary
|
||||
model?, // string — provider/model override
|
||||
thinking?, // string — off|minimal|low|medium|high|xhigh
|
||||
max_turns?, // number — max agentic turns (default: unlimited)
|
||||
run_in_background?, // boolean — run async (default: false)
|
||||
resume?, // string — agent ID to resume a previous session
|
||||
isolated?, // boolean — no extension/MCP tools
|
||||
isolation?, // "worktree" — run in isolated git worktree
|
||||
inherit_context? // boolean — fork parent conversation into agent
|
||||
})
|
||||
```
|
||||
|
||||
### Retrieve
|
||||
|
||||
```
|
||||
get_subagent_result({
|
||||
agent_id, // string — the agent ID from spawn notification
|
||||
wait?, // boolean — block until complete (default: false)
|
||||
verbose? // boolean — include full conversation (default: false)
|
||||
})
|
||||
```
|
||||
|
||||
### Steer
|
||||
|
||||
```
|
||||
steer_subagent({
|
||||
agent_id, // string — running agent ID
|
||||
message // string — message injected after current tool execution
|
||||
})
|
||||
```
|
||||
|
||||
### Compress
|
||||
|
||||
```
|
||||
compress_for_agent({
|
||||
content // string — content >20K chars to compress via Headroom
|
||||
})
|
||||
// Returns: { compressed, originalLength, compressedLength, tokensBefore, tokensAfter, savingsPercent }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Token Savings
|
||||
|
||||
The entire purpose is to **minimize context tokens** on the API provider:
|
||||
|
||||
| Scenario | Context Uploaded | Cost |
|
||||
|----------|-----------------|------|
|
||||
| Fresh agent every request | Full system prompt + context (~10K tokens) | ~$0.50-1.00 per request |
|
||||
| Resume same agent | Only new prompt (~100 tokens) + cached prefix hits KV cache | ~$0.01-0.05 per request |
|
||||
| **Savings** | **90-95% reduction** | **~$0.50 vs $5.00 for 5 questions** |
|
||||
|
||||
---
|
||||
|
||||
## Files
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `~/.local/share/npm-global/lib/node_modules/@tintinweb/pi-subagents/` | Extension source |
|
||||
| `~/.pi/agent/agents/*.md` | Agent type definitions (18 custom + 3 built-in) |
|
||||
| `~/.pi/agent/models.json` | OpenRouter provider pinning (only: provider) |
|
||||
| `.pi/agent-memory/<name>/` | Per-agent persistent memory (project scope) |
|
||||
| `.pi/agent-memory-local/<name>/` | Per-agent persistent memory (gitignored) |
|
||||
| `~/.pi/agent/subagents.json` | pi-subagents settings (maxConcurrent, etc.) |
|
||||
|
||||
## Related
|
||||
|
||||
- [[Pi Agent Extensions & Skills]] — full extensions/skills reference
|
||||
- [[Engram Memory]] — persistent memory service on .13
|
||||
- [[Headroom Compression]] — context compression via .13:8787
|
||||
- [[OpenRouter Provider Routing]] — provider pinning for cache continuity
|
||||
Reference in New Issue
Block a user