Agent

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

[
  {
    "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, 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, Identity, and Skills for their complete behavior.

Prompt assembly

For each run, Polpo builds the system context from:

the base agent prompt, including name and role;
identity, responsibilities, communication style, and reportsTo;
systemPrompt;
shared and private memory;
assigned skill context (progressive skill tools in Cloud, full assigned bodies in the OSS prompt builder);
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

[
  {
    "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 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.

Getting Started

Platform

Agents

Orchestration

Common fields

Prompt assembly

Complete example

Agentic Loops

API shape

​Common fields

​Prompt assembly

​Complete example

​Agentic Loops

​API shape

Common fields

Prompt assembly

Complete example

Agentic Loops

API shape