Skip to main content
A team is a named group of agents that work together on a project — like a company department. Each agent has a role, an identity (who they are, how they communicate), credentials (vault), and a place in the org chart (reportsTo). 
{
  "team": {
    "name": "marketing",
    "description": "Marketing department",
    "agents": [
      {
        "name": "marco",
        "role": "team lead",
        "identity": { "displayName": "Marco Rossi", "title": "Marketing Director" }
      },
      {
        "name": "alice",
        "role": "social media manager",
        "reportsTo": "marco",
        "identity": {
          "displayName": "Alice Chen",
          "title": "Social Media Manager",
          "tone": "Professional but warm. Uses first names.",
          "personality": "Empathetic, data-driven, creative with content."
        },
        "allowedTools": ["read", "write", "edit", "bash", "glob", "grep", "ls", "email_*"]
      },
      {
        "name": "bob",
        "role": "content writer",
        "reportsTo": "marco",
        "identity": { "displayName": "Bob Smith", "title": "Content Writer" }
      }
    ]
  }
}

​
Managing Teams

You manage teams through Polpo: 
// Get the current team
const team = orchestrator.getTeam();

// Add an agent at runtime
orchestrator.addAgent({
  name: "specialist",
  role: "developer",
  model: "anthropic:claude-sonnet-4-20250514",
});

// Remove an agent
orchestrator.removeAgent("specialist");

// Rename the team
orchestrator.renameTeam("new-name");
Or via the TUI, which has built-in commands for team management.

​
Org Chart and Escalation

Use reportsTo to build a hierarchy within the team. This drives automatic escalation — when an agent’s task fails and no explicit fallbackAgent is set, Polpo escalates to the agent’s manager. 
marco (Marketing Director)
├── alice (Social Media Manager)  [email, browser]
└── bob (Content Writer)
View the org chart: polpo agent list. View an agent’s full profile: polpo agent show alice.
Teams with reportsTo hierarchies work like company departments: the lead supervises, individual contributors do the work, and escalation flows upward automatically.

​
Volatile Teams

Sometimes a mission needs agents that don’t exist in your main config. Volatile teams let a mission define its own temporary agents that exist only for the duration of that mission. 
{
  "group": "data-migration",
  "team": [
    {
      "name": "db-specialist",
      "role": "database engineer",
      "model": "anthropic:claude-sonnet-4-20250514",
      "systemPrompt": "You are a PostgreSQL migration expert."
    }
  ],
  "tasks": [
    {
      "title": "Write migration scripts",
      "assignTo": "db-specialist",
      "description": "Create SQL migrations for the new schema"
    }
  ]
}
When this mission executes:
  1. Polpo creates db-specialist as a volatile agent (marked volatile: true, missionGroup: "data-migration")
  2. The agent works on its tasks like any other agent
  3. When the mission completes, the volatile agent is automatically removed

​
Volatile Team Settings

SettingTypeDefaultDescription
enableVolatileTeamsbooleantrueWhether missions can define their own agents
volatileCleanup"on_complete" | "manual""on_complete"When to remove volatile agents
Set volatileCleanup: "manual" if you want volatile agents to stick around after mission completion (useful for debugging).

​
Default Config

When you initialize a new Polpo project (polpo init), it generates a minimal config with one default agent: 
{
  "org": "my-project",
  "team": {
    "name": "default",
    "description": "Default Polpo team",
    "agents": [
      { "name": "dev-1", "role": "developer" }
    ]
  },
  "settings": { }
}
From there, add more agents, configure models, or define missions with volatile teams.