Agents

TanStack AI sessions with persistent identity. Each agent has a name, role template, filesystem sandbox, tool access, and private memory that carries across sessions.

What Agents Are

An agent is a TanStack AI session wrapped with a persistent identity. Between sessions, the orchestrator preserves everything the agent learned -- architecture decisions, mistakes to avoid, codebase patterns -- in a private memory store. When the agent is spawned again, that memory is injected into the system prompt so it picks up exactly where it left off.

Agents do not chat. They call unified tools: task, message, pin, search_index, fetch, web_search. Thinking is private. Only tool calls produce visible effects.

The Default Team

The Solo Dev Shop template ships with 8 agents covering the full product lifecycle. You choose the names, roles, and count. Multiple agents can share the same role.

This is the default Solo Dev Shop template. You can rename agents, add specialists, or remove roles you do not need. The CEO agent can also modify the roster at runtime.

Role Templates

A role defines the default system prompt, behavior rules, tool access, and filesystem scope for an agent. There are 8 built-in roles. You can also create custom roles.

Custom roles go in /company/team/roles/. Any agent assigned to the custom role inherits its prompt, tools, and default FS scope.

id: qa
name: "Quality Assurance"
description: "Writes and runs tests, validates against specs"

system_prompt: |
  You are a QA specialist. Your job is to ensure code quality through
  testing. You write unit tests, integration tests, and end-to-end tests.
  You validate implementations against their specs.

  Rules:
  - Every implementation must have corresponding tests
  - Test both happy paths and edge cases
  - Report test coverage metrics
  - If coverage is below 80%, create a task for more tests

default_tools: [fs, terminal, task, message]

default_fs_scope:
  read: ["/projects/**", "/knowledge/technical/**"]
  write: ["/projects/*/code/tests/**"]

Defining Agents in YAML

Agents are defined in /company/team/agents.yaml. Each entry specifies a unique ID, display name, role template, description, filesystem scope, and available tool groups.

agents:
  - id: ceo
    name: "CEO Agent"
    role: meta
    description: "Decomposes high-level intents into tasks, manages company structure"
    fs_scope:
      read: ["/**"]
      write: ["/team/**", "/dashboard/**"]
    tools: ["fs", "terminal", "task", "message", "pin", "search_index", "web_search"]

  - id: sam
    name: "Sam"
    role: strategist
    description: "Scopes features, writes specs, defines business requirements"
    fs_scope:
      read: ["/knowledge/**", "/projects/*/docs/**"]
      write: ["/projects/*/docs/**"]
    tools: ["fs", "terminal", "task", "message", "pin", "search_index", "web_search"]

  - id: max
    name: "Max"
    role: developer
    description: "Implements features, writes code, creates branches and PRs"
    fs_scope:
      read: ["/knowledge/technical/**", "/projects/**"]
      write: ["/projects/*/code/**"]
    tools: ["fs", "terminal", "task", "message", "pin", "search_index", "git", "web_search"]

  - id: riley
    name: "Riley"
    role: reviewer
    description: "Reviews code quality, architecture decisions, suggests improvements"
    fs_scope:
      read: ["/knowledge/technical/**", "/projects/**"]
      write: []
    tools: ["fs", "terminal", "task", "message", "pin", "search_index", "git", "web_search"]

Per-Agent Model Selection

The company-level company.yaml sets the default model for all agents. Individual agents can override it with the model field.

# company.yaml -- default model for all agents
settings:
  agent_model: "claude-sonnet-4-6"

# agents.yaml -- per-agent overrides
agents:
  - id: max
    role: developer
    model: "claude-sonnet-4-20250514"     # Full model ID

  - id: riley
    role: reviewer
    model: "claude-sonnet-4-6"            # Short alias

Filesystem Scope

Every agent is sandboxed. The orchestrator enforces filesystem scope at the provider level -- agents cannot read or write outside their defined paths.

# FS scope is defined per agent in agents.yaml
fs_scope:
  read: ["/knowledge/technical/**", "/projects/**"]
  write: ["/projects/*/code/**"]

# What happens when an agent tries to access outside scope:
max> read_file("/secrets/stripe.yaml")
ERROR: Access denied. /secrets/ is outside your read scope.

max> write_file("/team/agents.yaml", "...")
ERROR: Access denied. /team/ is outside your write scope.

                    meta  strat  dev  review  plan  devops  mktg  design
────────────────────────────────────────────────────────────────────────
Company overview     read  read   —      —      —     —      —      —
All tasks            read  read   own    own    own   own    own    own
Code repos           —     —      r/w    read   read  read   —      —
Infrastructure       —     —      —      —      —     r/w    —      —
Brand & marketing    —     read   —      —      —     —      r/w    r/w
Knowledge (all)      read  read   tech   tech   tech  infra  brand  brand
Other agents' memory NEVER NEVER  NEVER  NEVER  NEVER NEVER  NEVER  NEVER
Own memory           read  read   read   read   read  read   read   read
Comms channels       r/w   r/w    r/w    r/w    r/w   r/w    r/w    r/w

Memory System

After every session, the Memory Extractor (a lightweight Haiku call) scans the session transcript and extracts structured facts: architecture decisions, codebase patterns, mistakes made, lessons learned. These are appended to the agent's private memory.yaml file and ranked by relevance before the next session.

# After Max finishes implementing TASK-003:

# Memory Extractor output → /context/memory/max/memory.yaml
memories:
  - id: mem-k8x2
    type: decision
    content: "Auth library: chose jose over jsonwebtoken for edge runtime compat"
    source_task: TASK-003
    confidence: high

  - id: mem-k8x3
    type: pattern
    content: "Stripe checkout flow: always set metadata.task_id for traceability"
    source_task: TASK-003
    confidence: high

Agent Lifecycle

Every agent session follows the same 8-step lifecycle:

1. Trigger fires -- task assigned, schedule fires, webhook received, agent mentioned, message received
2. Context Assembler runs -- builds role-scoped system prompt from 6 layers
3. Agent spawns -- TanStack AI session created with tools, MCP servers, hooks, and FS sandbox
4. Agent works -- reads files, writes code, calls primitives, communicates with other agents
5. Session streams -- all tool calls captured as JSONL for autopilot attach and replay
6. Session ends -- work completed or timeout reached
7. Memory Extractor -- Haiku extracts facts, decisions, learnings, session summary
8. Workflow routes -- engine checks transitions, spawns next agent if needed

Context Assembly (6 Layers)

Before every session, the Context Assembler builds a system prompt from six sources. Each layer has a different purpose, update frequency, and token budget.

• L1 Identity (~2K tokens) — Role definition, behavioral rules, team roster, available tools, company conventions. Loaded from agents.yaml and company.yaml. Never changes within a session. Never truncated.
• L2 Company State (~5K tokens) — Real-time, role-scoped snapshot generated fresh before each session. Developer sees active tasks, branches, review queue. CEO sees all projects, team status, human inbox.
• L3 Memory Store (~20K tokens) — Persistent agent memory from past sessions. Facts about the codebase, architecture decisions, known mistakes to avoid, patterns noticed. Ranked by relevance before loading.
• L4 Task Context (~15K tokens) — Everything about the current task: YAML definition, spec and plan documents, task history, dependencies, related messages, code context.
• L5 Skills Discovery — Available skills from the filesystem, matched to the agent's role and current task.
• L6 Tool List — Complete tool definitions and usage instructions for all tools available to the agent.

Managing Agents

Agents can be added and removed at any time without restarting the orchestrator. The filesystem watcher detects changes to agents.yaml and updates the roster live.

# Add a new agent via CLI
$ autopilot agent add --name "Alice" --role developer --desc "Frontend specialist"
Added agent "alice" (developer) to team/agents.yaml

# Remove an agent
$ autopilot agent remove alice
Removed agent "alice" from team/agents.yaml

# List all agents and their status
$ autopilot agents

# The CEO agent can also manage the roster
$ autopilot ask "Add a QA agent for testing"

# Or edit the YAML directly — the watcher picks it up
$ vim team/agents.yaml

Agent Tools

Agents interact with the system through 12 unified tools. Each tool is a multipurpose function with validated input and output.

Agents also use native read_file/write_file from their LLM SDK for filesystem operations (knowledge, artifacts, config, skills).

See the Tools page for full documentation on every tool with code examples.