Agent

Agents are project resources. Each local agent has its own directory:

.polpo/agents/backend-dev/
├── agent.json
└── instructions.md

The directory name is the agent ID. agent.json contains structured configuration:

{
  "role": "Senior backend engineer",
  "model": "anthropic/claude-sonnet-4-5",
  "team": "engineering"
}

Standing instructions live in .polpo/agents/backend-dev/instructions.md:

Build reliable backend services and run the relevant tests before finishing.

The authored file does not contain name, systemPrompt, or createdAt. Polpo derives the name from the directory, reads the prompt from instructions.md, and adds runtime metadata when it materializes the agent. 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
`role`	string	Operational description added to the base prompt
`model`	string	Default text model
`team`	string	Non-default team ID
`allowedTools`	string[]	Optional tool allowlist
`toolLoading.mode`	string	`auto` (default), `direct`, or `progressive` runtime tool loading
`chat.allowedTools`	string[]	Optional restriction applied only to direct chat turns
`channels.allowedTools`	string[]	Optional restriction applied only to messaging Channel turns
`allowedPaths`	string[]	Filesystem roots available to file and shell tools
`sandbox`	object	Default isolation, lifecycle, and narrowed persistent-volume selection
`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.

Tool access by execution mode

allowedTools is the agent-wide ceiling. Optional mode policies can narrow that ceiling without creating separate agents:

{
  "allowedTools": ["ask_user_question", "apply_site_change", "site_*"],
  "chat": {
    "allowedTools": ["ask_user_question", "apply_site_change"]
  },
  "channels": {
    "allowedTools": ["ask_user_question", "apply_site_change"]
  }
}

Omitting a mode policy inherits the agent-wide set. An explicit empty array denies all tools in that mode. Policies only restrict: they can never grant a tool outside agent.allowedTools or a trusted runtime grant. When a direct chat or Channel turn starts a Project Loop, Polpo recalculates access for Loop mode. The preceding chat.allowedTools, channels.allowedTools, and Channel Route policy do not leak into the Loop; the same Session, canonical history, trusted identity, metadata, and grants are preserved. 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;
the contents of instructions.md;
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. instructions.md extends the base prompt; it does not replace it.

Complete example

{
  "role": "Builds and maintains server-side TypeScript.",
  "model": "anthropic/claude-sonnet-4-5",
  "team": "engineering",
  "allowedTools": ["read", "write", "edit", "bash", "glob", "grep", "memory_*"],
  "toolLoading": { "mode": "auto" },
  "chat": {
    "allowedTools": ["read", "glob", "grep"]
  },
  "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"
    ]
  }
}

.polpo/agents/backend-dev/instructions.md:

Run relevant tests after each change.

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 Agent API uses a flat runtime object. POST /v1/agents?team=engineering accepts AgentConfig, including name and optional systemPrompt, while GET /v1/agents returns materialized agent configurations. The filesystem layout separates those fields so each agent definition remains readable and independently editable. For a field-by-field reference, see Agents reference.

Getting Started

Platform

Agents

Orchestration

Common fields

Tool access by execution mode

Prompt assembly

Complete example

Agentic Loops

API shape

​Common fields

​Tool access by execution mode

​Prompt assembly

​Complete example

​Agentic Loops

​API shape

Common fields

Tool access by execution mode

Prompt assembly

Complete example

Agentic Loops

API shape