> ## 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.

# Agent

> Define and configure an agent in Polpo

Agents are project resources. In a local project, `.polpo/agents.json` stores an array of wrappers containing an `agent` config and its `teamName`:

```json theme={null}
[
  {
    "agent": {
      "name": "backend-dev",
      "role": "Senior backend engineer",
      "model": "anthropic/claude-sonnet-4-5"
    },
    "teamName": "engineering"
  }
]
```

Only `name` is required by `AgentConfig`; `role` and `model` are optional. A model identifier uses `provider/model`. Available identifiers depend on the configured [LLM gateway](/docs/platform/llm-gateway), so query the model catalog instead of assuming an identifier is enabled.

## Common fields

| Field                 | Type      | Purpose                                                              |
| --------------------- | --------- | -------------------------------------------------------------------- |
| `name`                | string    | Unique agent identifier                                              |
| `role`                | string    | Operational description added to the base prompt                     |
| `model`               | string    | Default text model                                                   |
| `systemPrompt`        | string    | Additional standing instructions                                     |
| `allowedTools`        | string\[] | Optional tool allowlist                                              |
| `allowedPaths`        | string\[] | Filesystem roots available to file and shell tools                   |
| `skills`              | string\[] | Assigned project skill names                                         |
| `reportsTo`           | string    | Manager agent name                                                   |
| `identity`            | object    | Persona, responsibilities, and communication style                   |
| `maxTurns`            | number    | Maximum model turns per run; default `150`                           |
| `maxConcurrency`      | number    | Maximum concurrent work for this agent                               |
| `reasoning`           | string    | `off`, `minimal`, `low`, `medium`, `high`, or `xhigh`                |
| `browserProfile`      | string    | Persistent profile used by browser tools; defaults to the agent name |
| `assignedLoops`       | string\[] | Project-level Agentic Loops this agent may run                       |
| `emailAllowedDomains` | string\[] | Recipient-domain restriction for outbound email                      |

Media and provider-specific selection can be configured with `image_model`, `video_model`, `vision_model`, `transcribe_model`, `tts_model`, and `search_provider`.

See [Tools](/docs/agents/tools), [Identity](/docs/agents/identity), and [Skills](/docs/agents/skills) for their complete behavior.

## Prompt assembly

For each run, Polpo builds the system context from:

1. the base agent prompt, including `name` and `role`;
2. identity, responsibilities, communication style, and `reportsTo`;
3. `systemPrompt`;
4. shared and private [memory](/docs/agents/memory);
5. assigned skill context (progressive skill tools in Cloud, full assigned bodies in the OSS prompt builder);
6. runtime context such as workspace, caller instructions, task, or loop context.

Chat mode adjusts the base instructions for interactive conversation. `systemPrompt` extends the base prompt; it does not replace it.

## Complete example

```json theme={null}
[
  {
    "agent": {
      "name": "backend-dev",
      "role": "Builds and maintains server-side TypeScript.",
      "model": "anthropic/claude-sonnet-4-5",
      "systemPrompt": "Run relevant tests after each change.",
      "allowedTools": ["read", "write", "edit", "bash", "glob", "grep", "memory_*"],
      "allowedPaths": ["src/server", "tests"],
      "maxTurns": 200,
      "maxConcurrency": 3,
      "reasoning": "medium",
      "reportsTo": "tech-lead",
      "skills": ["api-security"],
      "assignedLoops": ["qa-flow"],
      "identity": {
        "displayName": "Alex Chen",
        "title": "Senior Backend Engineer",
        "tone": "Direct and technical",
        "responsibilities": [
          {
            "area": "API development",
            "description": "Design and implement REST APIs",
            "priority": "critical"
          },
          "Code review"
        ]
      }
    },
    "teamName": "engineering"
  }
]
```

## Agentic Loops

Loop definitions are project resources under `.polpo/loops/`; agents only store loop names in `assignedLoops`. A chat request can select an assigned loop with its `loop` field. Legacy inline `loops` and `pipeline` fields are accepted for compatibility but should not be used for new configurations.

See the [Loops API](/agent-api/loops) for the current graph, permissions, policies, hooks, and execution contracts.

## API shape

The local file uses the wrapper shown above. The Agent API uses a flat agent object: `POST /v1/agents?team=engineering` accepts `AgentConfig`, while `GET /v1/agents` returns agent configurations. Do not send the local `{ agent, teamName }` wrapper to the REST endpoint.

For a field-by-field reference, see [Agents reference](/developers/reference/agents).