> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polpo.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Teams

> Group agents and describe reporting relationships

A team is a named container with an optional description. Local team metadata and agent membership are stored separately.

`.polpo/teams.json`:

```json theme={null}
[
  {
    "name": "engineering",
    "description": "Builds and maintains the product"
  }
]
```

`.polpo/agents.json`:

```json theme={null}
[
  {
    "agent": {
      "name": "tech-lead",
      "role": "Reviews changes and coordinates delivery"
    },
    "teamName": "engineering"
  },
  {
    "agent": {
      "name": "backend-dev",
      "role": "Implements server-side changes",
      "reportsTo": "tech-lead"
    },
    "teamName": "engineering"
  }
]
```

API responses materialize a `Team` with its `agents` array, but `agents` is not stored inside `.polpo/teams.json`. Likewise, teams do not belong in `polpo.json`.

## Reporting relationships

`reportsTo` is an agent field. The runtime adds it to the agent's organization prompt and can use it as escalation context. It does not automatically reassign every failed task or delegate work. Deterministic escalation is configured on the task's `retryPolicy` with `fallbackAgent`, `escalateAfter`, and optional `escalateModel`.

## API

Team routes are nested under the Agents resource:

| Method   | Path                          | Description                               |
| -------- | ----------------------------- | ----------------------------------------- |
| `GET`    | `/v1/agents/teams`            | List teams with agents                    |
| `GET`    | `/v1/agents/team?name={name}` | Get one team; omit `name` for the default |
| `POST`   | `/v1/agents/teams`            | Create `{ name, description? }`           |
| `PATCH`  | `/v1/agents/team`             | Rename with `{ oldName, name }`           |
| `DELETE` | `/v1/agents/teams/{name}`     | Remove a team                             |

```typescript theme={null}
await client.addTeam({ name: "engineering", description: "Product engineering" });
const teams = await client.getTeams();
await client.renameTeam("engineering", "platform");
```

Use the Agent API to add or update members and select their team.

## Mission-scoped agents

Temporary agents are defined as an array in a mission document's `team` field. The mission executor marks them volatile, associates them with the execution group, and cleans them up according to `volatileCleanup`. They are not permanent project-team definitions. See [Missions](/docs/orchestration/missions#temporary-team).