Subagent Extension - Multi-Model Provider Support

Delegate tasks to specialized subagents with isolated context windows and intelligent multi-provider model resolution.

Features

• Isolated context: Each subagent runs in a separate pi process
• Multi-model support: Each agent can use a different model
• Intelligent provider resolution: Automatically finds models across providers
• Provider preference: Configure which providers to prefer for model lookup
• Streaming output: See tool calls and progress as they happen
• Parallel execution: Run multiple agents concurrently
• Chain workflows: Sequential execution with output passing

Model Resolution

When an agent specifies a model ID (e.g., claude-sonnet-4-5), the extension:

1. First tries preferred providers with API keys (in order)
2. Then tries other providers with API keys
3. Falls back to any provider (will fail if no API key configured)

This allows you to:

• Use google-vertex-claude for Claude models (if configured)
• Fall back to anthropic if vertex isn’t available
• Use local models via llama-cpp
• Configure provider preferences globally or per-session

Configuration

Provider Preference

Configure provider preference in three ways (priority order):

1. Command-line flag (highest priority)

pi --subagent-providers google-vertex-claude,google,llama-cpp

2. Settings file (~/.pi/agent/settings.json)

{
  "subagentProviderPreference": [
    "google-vertex-claude",
    "google", 
    "llama-cpp",
    "anthropic",
    "openai"
  ]
}

3. Default behavior (lowest priority)

If not configured, the extension tries all providers, preferring those with API keys.

View Current Configuration

pi
> /subagent-config

Agent Definitions

Create agents in ~/.pi/agent/agents/*.md:

---
name: scout
description: Fast reconnaissance
tools: read, grep, find, ls
model: claude-haiku-4-5
---

You are a scout. Quickly investigate a codebase...

The model: field is just the model ID - the provider is resolved automatically.

Available Models by Provider

Anthropic Claude via Google Vertex:

• claude-opus-4-6
• claude-sonnet-4-5@20250929
• claude-haiku-4-5@20251001

Google Gemini:

• gemini-2.5-flash
• gemini-2.5-pro

Local (llama-cpp):

• Qwen/Qwen3-8B-GGUF:Q4_K_M
• bartowski/DeepSeek-R1-Distill-Qwen-7B-GGUF:Q4_K_M

Usage Examples

Simple Usage

Use scout to find all Tekton tasks

Chain Workflow

Chain: scout finds auth code, planner creates refactor plan, worker implements it

This might use:

• scout → claude-haiku-4-5 via google-vertex-claude
• planner → claude-sonnet-4-5@20250929 via google-vertex-claude
• worker → claude-sonnet-4-5@20250929 via google-vertex-claude

Slash Commands

The subagent-commands.ts extension provides shortcuts:

/scout find all authentication code
/implement add caching to session store
/scout-and-plan refactor database layer
/review-code check security in API handlers

Example Agents

Scout (Fast, Cheap)

---
name: scout
description: Fast reconnaissance
tools: read, grep, find, ls, bash
model: claude-haiku-4-5
---

Quickly investigate and return compressed findings.

Planner (Detailed Analysis)

---
name: planner
description: Creates implementation plans
tools: read, grep, find, ls
model: claude-sonnet-4-5@20250929
---

Receive context and create detailed implementation plans.

Local Researcher

---
name: local-researcher
description: Research using local model
tools: web_search, github_search, stack_overflow_search
model: Qwen/Qwen3-8B-GGUF:Q4_K_M
---

Research using a local model to save API costs.

Cost Optimization

Configure provider preference to optimize costs:

{
  "subagentProviderPreference": [
    "llama-cpp",              // Free (local)
    "google-vertex-claude",   // Discounted Claude via Vertex
    "google",                 // Gemini
    "anthropic"               // Full-price Claude (fallback)
  ]
}

Now agents requesting claude-haiku-4-5 will:

1. Try llama-cpp first (no claude there, skip)
2. Try google-vertex-claude (found! use it)
3. Skip remaining providers

Troubleshooting

“No API key configured for provider”

Problem: Agent fails because the subagent process doesn’t have an API key.

Solution: Add provider preference to route to a configured provider:

{
  "subagentProviderPreference": ["google-vertex-claude"]
}

Model not found

Problem: Agent specifies a model that doesn’t exist on any provider.

Solution: Check available models:

pi --list-models | grep claude-haiku

Update agent definition with correct model ID.

Wrong provider being used

Problem: Agent uses an unexpected provider.

Solution:

1. Check current config: /subagent-config
2. Add explicit preference in settings
3. Or use flag: pi --subagent-providers google-vertex-claude

API Reference

Tool Parameters

{
  agent: "scout",                    // Single mode
  task: "find auth code",
  
  // OR parallel mode:
  tasks: [
    { agent: "scout", task: "..." },
    { agent: "planner", task: "..." }
  ],
  
  // OR chain mode:
  chain: [
    { agent: "scout", task: "find auth" },
    { agent: "planner", task: "plan using {previous}" }
  ],
  
  agentScope: "user" | "project" | "both",  // Default: "user"
  confirmProjectAgents: true,               // Default: true
  cwd: "/path/to/working/dir"              // Optional
}

Settings Schema

{
  "subagentProviderPreference": ["provider1", "provider2", "..."]
}

Command-line Flag

--subagent-providers <comma-separated-list>

Security

Project-local agents (.pi/agents/*.md) can execute arbitrary code. Only use agentScope: "both" or agentScope: "project" for repositories you trust.

By default, only user-level agents (~/.pi/agent/agents/) are loaded.