#Agents & Sub-Agents

Agents live in .wingman/agents/<agent-id>/ and can be defined as either JSON (agent.json) or Markdown (agent.md with frontmatter).

#Discovery vs routing

• Discovery: agent definitions are loaded from .wingman/agents/<agent-id>/.
• Routing & metadata: defaults, display names, workspaces, and channel bindings live in wingman.config.json under agents.list and agents.bindings.

If you want the gateway to route messages to a specific agent (or show a friendly name in the UI), add entries in wingman.config.json. See the agents section in the wingman.config.json guide.

#Bundled agents (starter templates)

Wingman ships with a small set of bundled agents so you can start quickly. These live in the package at:

apps/wingman/.wingman/agents/

When you run wingman init, the templates are copied into your workspace:

.wingman/agents/

You can choose a subset during setup:

wingman init --agents main,coding,stock-trader

To re-copy bundled agents later without changing config or provider settings:

wingman init --mode sync --only agents
wingman init --mode sync --only agents --agents main,coding
wingman init --mode sync --only agents --force

Bundled templates currently include:

• main (general-purpose)
• coding (direct-execution coding specialist with tool-backed completion guard)
• coding-v2 (multi-subagent coding orchestrator with planner/implementor/reviewer split)
• game-dev (game feature orchestrator with specialist sub-agents, browser-assisted WebGL/UI QA, and UV/geometry-aware texture generation guidance)
• image-generator (native prompt-to-image specialist using xai:grok-imagine-image)
• researcher (source-first web research)
• stock-trader (market data research workflows)

Edit these in-place to customize prompts, tools, or sub-agents. Treat them as templates—clone and rename as needed for each project.

wingman init installs the bundled agents into your workspace and lets you choose which explicit agent should be the default.

#Agent overview (including MCP dependency)

MCP dependency levels used below:

• None: the template does not rely on MCP to do its core job.
• Optional: the template can use MCP if configured, but works without it.
• Recommended: MCP materially improves core workflows.
• Required: core workflow assumes MCP tools are available.

browser_control is native to Wingman runtime (CDP with automatic persistent-context fallback when needed). It is not provided through MCP. The bundled game-dev template uses it for browser-backed QA, and when a default browser profile is configured those runs use Playwright persistent-context automatically.

#MCP-focused config examples

#1) No MCP dependency (researcher)

---
name: researcher
description: Source-first research agent
tools:
  - internet_search
  - web_crawler
  - browser_control
promptRefinement: true
---

#2) Required MCP dependency (stock-trader with global finance MCP)

// .wingman/wingman.config.json
{
  "mcp": {
    "servers": [
      {
        "name": "finnhub",
        "transport": "stdio",
        "command": "node",
        "args": ["./node_modules/@wingman-ai/gateway/dist/tools/mcp-finance.js"],
        "env": { "FINNHUB_API_KEY": "your_key_here" }
      }
    ]
  }
}

---
name: stock-trader
mcpUseGlobal: true
---

#3) Recommended MCP dependency (game-dev or main with FAL MCP)

// .wingman/wingman.config.json
{
  "mcp": {
    "servers": [
      {
        "name": "fal-ai",
        "transport": "stdio",
        "command": "node",
        "args": ["./node_modules/@wingman-ai/gateway/dist/tools/mcp-fal-ai.js"],
        "env": { "FAL_API_KEY": "your_key_here" }
      }
    ]
  }
}

---
name: game-dev
mcpUseGlobal: true
---

For readability, the stock-trader agent returns a concise Decision Packet with a direct answer first, followed by short sections that summarize the key signals and risks (no raw tool dumps). Ask it to expand any section if you need deeper detail.

#Provider credentials (env vars)

Agents that talk to model providers require credentials. Use either wingman provider login <provider> or environment variables, for example:

OPENAI_API_KEY
ANTHROPIC_API_KEY
OPENROUTER_API_KEY
XAI_API_KEY

#agent.json example

{
  "name": "wingman",
  "description": "General-purpose coding assistant for this repo.",
  "systemPrompt": "Be concise. Ask clarifying questions when needed.",
  "tools": ["code_search", "git_status", "command_execute", "browser_control", "internet_search"],
  "model": "anthropic:claude-sonnet-4-5",
  "browserProfile": "trading",
  "browserTransport": "auto",
  "promptRefinement": {
    "enabled": true,
    "instructionsPath": "/memories/agents/wingman/instructions.md"
  },
  "blockedCommands": ["rm", "mv"],
  "allowScriptExecution": true,
  "commandTimeout": 300000,
  "mcpUseGlobal": true,
  "voice": {
    "provider": "elevenlabs",
    "elevenlabs": { "voiceId": "voice_123" }
  },
  "subAgents": [
    {
      "name": "reviewer",
      "description": "Reviews code changes for risk.",
      "systemPrompt": "Check for regressions and missing tests.",
      "model": "openai:gpt-4o"
    }
  ]
}

#agent.md example

---
name: researcher
description: Gathers context and produces concise briefs.
model: openrouter:openai/gpt-4o
promptRefinement:
  enabled: true
  instructionsPath: /memories/agents/researcher/instructions.md
tools:
  - internet_search
  - web_crawler
  - browser_control
  - think
---
You are a researcher. Summarize sources and provide citations.

#Sub-agent model overrides

Sub-agents can override any agent field, including model, tools, voice, and command controls. This lets you mix fast/cheap models with deep/reasoning models in one squad.

{
  "name": "wingman",
  "description": "Lead agent that delegates.",
  "systemPrompt": "Delegate to specialists when possible.",
  "subAgents": [
    {
      "name": "planner",
      "description": "Breaks tasks into steps.",
      "systemPrompt": "Produce a short plan before implementation.",
      "model": "openai:gpt-4o"
    },
    {
      "name": "reviewer",
      "description": "Finds regressions and missing tests.",
      "systemPrompt": "Review diffs for correctness.",
      "model": "anthropic:claude-sonnet-4-5"
    }
  ]
}

#Sub-agent prompt files (agent.md)

When using agent.md, sub-agents can load their prompts from separate files with promptFile. This keeps large prompts readable and makes it easier to reuse or iterate on specialist instructions.

---
name: wingman
description: Lead agent with specialist sub-agents.
subAgents:
  - name: planner
    description: Produces concise plans.
    model: openai:gpt-4o
    promptFile: planner.md
  - name: reviewer
    description: Reviews code for risk.
    model: anthropic:claude-sonnet-4-5
    promptFile: reviewer.md
---
You are the lead agent. Delegate to specialists as needed.

File layout:

.wingman/agents/wingman/
  agent.md
  planner.md
  reviewer.md

If a prompt file contains frontmatter, those fields override/extend the sub-agent metadata. Otherwise the file is treated as the sub-agent’s systemPrompt.

#Available tools

Agents can only use the tools listed in the tools array. Available tool names:

• internet_search
• web_crawler
• browser_control
• browser_session_start
• browser_session_action
• browser_session_close
• browser_session_list
• command_execute
• background_terminal
• node_notify
• node_run
• think
• code_search
• git_status
• ui_registry_list
• ui_registry_get
• ui_present

#Sub-agent delegation

subAgents lets you define specialist agents. The parent agent can delegate tasks when needed. Each sub-agent supports the same schema fields as a normal agent.

#Prompt refinement

promptRefinement enables a per-agent instruction overlay that the agent can update over time based on explicit feedback.

• The overlay is stored under /memories/ so it persists across sessions.
• Updates only happen when users give clear, durable preferences (e.g., “always do X”, “never do Y”).
• Keep the file short and stable: preferences, workflow rules, and corrections.

#Browser, MCP, and voice overrides

• browserProfile: named persistent browser_control profile ID (for example trading). Initialize one with wingman browser profile init trading.
• browserTransport: optional transport preference override (auto, playwright, relay) for browser_control or browser_session_*
• browserExtensions: optional extension IDs loaded for this agent (mapped from browser.extensions in wingman.config.json)
• mcp: agent-specific MCP servers
• mcpUseGlobal: include global MCP servers from wingman.config.json
• voice: overrides global voice configuration for this agent
• promptRefinement: enable/disable prompt refinement and set the overlay path

#Browser profile setup patterns

Prefer browser_session_* for normal browser automation. Reserve browser_control for agents that should only act when the user explicitly wants Wingman to use their existing browser or live tab.

• Shared default profile across browser-enabled agents:
  • Run wingman browser profile init trading --default
  • Omit browserProfile in agents and rely on browser.defaultProfile
• Per-agent profile isolation:
  • Run wingman browser profile init <id> for each profile
  • Set browserProfile per agent (research, trading, etc.)
• Per-agent extension set:
  • Run wingman browser extension install --default for Wingman's bundled extension, or wingman browser extension install <id> --source <dir> for a custom one
  • Set browserExtensions in agent config when an agent needs non-default extensions
• Custom storage location:
  • Run wingman browser profile init trading --profiles-dir .wingman/profiles

For full examples, see Browser Automation, Playwright Setup, and Relay Setup.

#Why voice is duplicated in agent config

Voice exists in both global config and agent config so you can set defaults once and override per agent. This allows one agent to speak with ElevenLabs while another uses Web Speech (or stays silent).

// wingman.config.json
{
  "voice": {
    "provider": "web_speech",
    "defaultPolicy": "manual",
    "webSpeech": { "lang": "en-US" }
  }
}

// agent.json
{
  "name": "narrator",
  "description": "Reads summaries aloud.",
  "systemPrompt": "Narrate results.",
  "voice": {
    "provider": "elevenlabs",
    "elevenlabs": { "voiceId": "voice_123" }
  }
}