Build Your Team

After polpo init you have one default agent. This guide shows how to build a full team — multiple agents with different roles, models, and constraints.

Add agents to your config

Edit .polpo/polpo.json:

{
  "org": "my-project",
  "team": {
    "name": "my-team",
    "agents": [
      {
        "name": "backend-dev",
        "role": "Backend developer specializing in Node.js, Express, and databases",
        "model": "anthropic:claude-sonnet-4-6"
      },
      {
        "name": "frontend-dev",
        "role": "Frontend developer specializing in React and TypeScript",
        "model": "anthropic:claude-sonnet-4-6"
      },
      {
        "name": "reviewer",
        "role": "Senior code reviewer focused on architecture and best practices",
        "model": "anthropic:claude-sonnet-4-6"
      }
    ]
  }
}

Or run polpo setup to reconfigure your team interactively.

Agent options

Each agent supports these fields:

Field	Type	Default	Description
`name`	`string`	required	Unique identifier
`role`	`string`	—	What this agent does (included in its system prompt)
`model`	`string`	—	`"provider:model"` format. See Providers
`identity`	`AgentIdentity`	—	Persona: name, title, responsibilities, tone, personality. See Identity
`reportsTo`	`string`	—	Org chart parent — automatic escalation on failure. See Org chart
`allowedTools`	`string[]`	all core tools	Restrict which tools the agent can use. Include `"browser_"` for browser access, `"email_"` for email tools, `"vault_"` for vault credential access, `"image_"` for image generation/analysis, `"video_"` for video generation, `"audio_"` for speech-to-text and text-to-speech, `"search_*"` for web search via Exa AI
`allowedPaths`	`string[]`	project root	Filesystem sandbox — agent can only access these paths
`systemPrompt`	`string`	—	Custom instructions prepended to the default prompt
`skills`	`string[]`	—	Named skill files to load
`maxTurns`	`number`	`150`	Maximum tool-use turns before the agent is stopped

The role field matters. Polpo includes it in the agent’s system prompt, so be specific: “Backend developer specializing in Node.js and PostgreSQL” works better than just “developer”.

Manage teams from the TUI

Inside the TUI you can manage your team without editing JSON:

/team                    # view current team
/team add <name> <role>  # add an agent
/team remove <name>      # remove an agent

The /team command also supports AI team generation — describe your project and Polpo suggests the right agents.

Volatile teams

Missions can define their own temporary agents that exist only for that mission’s duration. Useful for one-off specialists:

{
  "group": "data-migration",
  "team": [
    {
      "name": "db-specialist",
      "role": "PostgreSQL migration expert",
      "model": "anthropic:claude-sonnet-4-6"
    }
  ],
  "tasks": [
    {
      "title": "Write migration scripts",
      "assignTo": "db-specialist",
      "description": "Create SQL migrations for the new schema"
    }
  ]
}

Volatile agents are created when the mission starts and removed when it completes. See Teams for details.

Different models per agent

You can mix providers and models across agents:

{
  "agents": [
    {
      "name": "planner",
      "role": "System architect who designs before coding",
      "model": "anthropic:claude-sonnet-4-6"
    },
    {
      "name": "coder",
      "role": "Fast implementation developer",
      "model": "groq:llama-3.3-70b-versatile"
    }
  ]
}

Polpo resolves each agent’s model independently. Set POLPO_MODEL as a fallback for agents without an explicit model.

Agent identity and persona

Give agents a rich identity — name, title, responsibilities, communication style, and personality traits. Polpo injects all of this into the agent’s system prompt so it behaves consistently.

{
  "name": "alice",
  "role": "social media manager",
  "identity": {
    "displayName": "Alice Chen",
    "title": "Social Media Manager",
    "company": "Acme Corp",
    "email": "alice@acme.com",
    "responsibilities": [
      {
        "area": "Social Media Management",
        "description": "Create and publish content across all platforms. Track engagement metrics.",
        "priority": "high"
      },
      {
        "area": "Customer Relations",
        "description": "Respond to customer inquiries within 2 hours. Escalate complaints.",
        "priority": "critical"
      }
    ],
    "tone": "Professional but warm. Uses first names. Keeps emails under 3 paragraphs. Uses bullet points for lists.",
    "personality": "Empathetic and detail-oriented. Anticipates customer concerns. Prefers data-backed decisions — always cites engagement metrics."
  }
}

Responsibilities support both simple strings ("Manage social media") and structured objects with area, description, and priority. The structured format is recommended — it helps the agent prioritize work and understand scope boundaries. Tone defines HOW the agent communicates — register, format, length. Personality defines WHO the agent IS — character traits, working style, decision approach. Together they produce realistic, consistent behavior. You can edit the JSON manually, or use the interactive onboarding wizard (recommended).

Onboard your agents

Instead of writing JSON by hand, polpo agent onboard walks you through every aspect of an agent’s setup in a guided wizard.

polpo agent onboard alice

The wizard runs through 5 steps:

Identity — The agent’s public persona.

Step 1: Identity

Display name (e.g. Alice Chen): Alice Chen
Job title [social media manager]: Social Media Manager
Company: Acme Corp
Email: alice@acme.com
Timezone (e.g. Europe/Rome): America/New_York
Bio (optional): Manages Acme's social presence across all platforms.

These fields are injected into the agent’s system prompt and used when it writes emails or external messages. The email field also serves as the default SMTP from address.

Persona — Responsibilities, tone, and personality.

Step 2: Persona

Use structured responsibilities (area + description + priority)? (Y/n): Y
Enter responsibilities (empty area to finish):
  Area: Social Media Management
  Description: Create and publish content across all platforms
  Priority: 1. (skip)  2. critical  3. high  4. medium  5. low
  Choice [1]: 3

  Area: Customer Relations
  Description: Respond to inquiries within 2h, escalate complaints
  Priority: Choice [1]: 2

  Area:

Communication tone: Professional but warm. Uses first names. Keeps emails under 3 paragraphs.
Personality traits: Empathetic and detail-oriented. Data-driven. Creative but disciplined.

Structured responsibilities (recommended) give each area a name, description, and priority. The agent uses priority to decide what to focus on first. You can also enter simple one-line strings if you prefer. Tone controls the form of communication — length, register, format preferences. Personality controls the substance — character traits, decision-making approach, working style.

Hierarchy — Org chart placement.
```
Step 3: Hierarchy

Reports to:
  1. (none — top-level)
  2. marco
Choice [1]: 2
```
Sets reportsTo for automatic escalation. If the agent’s task fails, Polpo escalates to its manager. See Escalation.

Email — SMTP and IMAP vault configuration.

Step 4: Email

Enable email tools? (y/N): y
Configure SMTP (send)? (Y/n): Y
  SMTP host [smtp.gmail.com]: smtp.gmail.com
  SMTP port [587]: 587
  SMTP user (e.g. ${ALICE_SMTP_USER}): ${ALICE_SMTP_USER}
  SMTP pass (e.g. ${ALICE_SMTP_PASS}): ${ALICE_SMTP_PASS}
  From address [alice@acme.com]: alice@acme.com

Configure IMAP (read)? (Y/n): Y
  IMAP host [imap.gmail.com]: imap.gmail.com
  ...

This creates vault entries (type "smtp" and "imap") and adds email_* to allowedTools. Use ${ENV_VAR} syntax for secrets — Polpo resolves them at runtime from environment variables. Enabling email gives the agent 8 tools: email_send, email_draft, email_verify, email_list, email_read, email_search, email_count, email_download_attachment. See Email Tools.

Vault — Additional credentials.

Step 5: Additional Credentials

Add a vault entry (API key, login, etc.)? (y/N): y
  Service name: twitter
  Credential type: 1. api_key  2. oauth  3. login  4. custom
  Choice [1]: 1
  Label [twitter]: Twitter API
  Enter credential fields (empty key to stop):
    Key: api_key
    Value: ${TWITTER_API_KEY}
    Key:

Add vault entries for any service the agent needs — API keys, OAuth tokens, login credentials. Each entry gets a type for semantic meaning and ${ENV_VAR} references for secrets.

The wizard saves agent config to .polpo/polpo.json and vault entries to .polpo/vault.enc (AES-256-GCM encrypted). Run it again anytime to update an agent’s configuration.

Verify the result

After onboarding, inspect the agent:

polpo agent show alice    # detailed view (credentials masked)
polpo agent list          # org chart with all agents

Workflow: Use polpo init → polpo setup to create your project and first agent, then polpo agent onboard <name> to set up each agent’s identity, credentials, and persona. The setup wizard handles the project; onboarding handles the agent.

Org chart (reportsTo)

Build a hierarchy so Polpo knows who to escalate to when tasks fail:

{
  "agents": [
    { "name": "marco", "role": "team lead" },
    { "name": "alice", "role": "developer", "reportsTo": "marco" },
    { "name": "bob", "role": "developer", "reportsTo": "marco" }
  ]
}

When alice’s task fails and the retry policy has no explicit fallbackAgent, Polpo automatically escalates to marco. View the org chart with polpo agent list.

Per-agent credentials (vault)

Each agent can have its own credentials for email, APIs, logins, etc. Vault entries are stored in .polpo/vault.enc (AES-256-GCM encrypted), not in polpo.json. Manage vault entries via:

CLI: polpo agent onboard <name> — the Email and Vault steps write to the encrypted store
TUI / Chat: Use the built-in tools — set_vault_entry, remove_vault_entry, list_vault

Credential values support ${ENV_VAR} references — Polpo resolves them at runtime from environment variables. See Configuration — Encrypted Vault for vault entry fields, key management, and supported credential types.

Next steps

Your team is ready. Now create a mission to put them to work:

Your First Mission

Create a multi-task mission with dependencies and automated assessment.

Overview

First Steps

Usage

Deploy

Build Your Team

Add agents to your config

Agent options

Manage teams from the TUI

Volatile teams

Different models per agent

Agent identity and persona

Onboard your agents

Verify the result

Org chart (reportsTo)

Per-agent credentials (vault)

Next steps

Your First Mission

Overview

First Steps

Usage

Deploy

​Add agents to your config

​Agent options

​Manage teams from the TUI

​Volatile teams

​Different models per agent

​Agent identity and persona

​Onboard your agents

​Verify the result

​Org chart (reportsTo)

​Per-agent credentials (vault)

​Next steps

Your First Mission

Add agents to your config

Agent options

Manage teams from the TUI

Volatile teams

Different models per agent

Agent identity and persona

Onboard your agents

Verify the result

Org chart (reportsTo)

Per-agent credentials (vault)

Next steps