Skip to main content
Every Polpo project has a .polpo/ directory. Settings and providers live in polpo.json, while agents and teams are stored in agents.json and teams.json.

​
Your first agent

An agent needs a name, a role, and a model. Define it in .polpo/agents.json: 
[
  {
    "agent": {
      "name": "backend-dev",
      "role": "Senior backend engineer",
      "model": "anthropic/claude-sonnet-4-5"
    },
    "teamName": "default"
  }
]
Each entry wraps an agent config with a teamName. That’s enough to start using your agent via the completions API.

​
Choosing a model

Models use the provider/model format: 
"model": "anthropic/claude-sonnet-4-5"
"model": "openai/gpt-4o"
"model": "google/gemini-2.5-pro"
"model": "openrouter/google/gemini-2.5-flash"
With an LLM gateway configured, all providers are available through a single endpoint. See LLM & Providers for the full list and LLM Configuration for gateway setup.

​
Giving agents tools

By default agents can read and write files. You control exactly which tools they have access to: 
{
  "name": "backend-dev",
  "allowedTools": ["read", "write", "edit", "bash", "glob", "grep", "http_fetch"],
  "allowedPaths": ["src/", "tests/"]
}
allowedPaths sandboxes the agent’s filesystem access. See Tools for the full list.

​
Identity

Give your agent a persona with identity: 
{
  "name": "backend-dev",
  "identity": {
    "displayName": "Alex Chen",
    "title": "Senior Backend Engineer",
    "company": "Acme Corp",
    "email": "alex@acme.com",
    "timezone": "America/New_York"
  }
}
The agent uses this identity when communicating externally (emails, messages, etc.).

​
Responsibilities

Define what the agent is responsible for: 
{
  "identity": {
    "responsibilities": [
      { "area": "API Development", "description": "Design and implement REST APIs", "priority": "critical" },
      { "area": "Testing", "description": "Write unit and integration tests", "priority": "high" },
      "Code review"
    ]
  }
}
Responsibilities can be simple strings or structured objects with area, description, and priority.

​
Tone and personality

Control how the agent communicates: 
{
  "identity": {
    "tone": "Direct, technical, concise",
    "personality": "Analytical, detail-oriented, pragmatic"
  }
}

​
System prompt

The systemPrompt is appended to the base prompt. Use it for specific instructions that don’t fit in role, identity, or skills: 
{
  "name": "backend-dev",
  "systemPrompt": "Write clean, tested TypeScript. Always run tests after changes. Prefer small, focused commits."
}

​
How the prompt is assembled

Polpo builds the final system prompt by combining all the pieces above in this order: 
1. Base prompt        (agent name, role, context tags)
2. Identity           (displayName, title, tone, personality, responsibilities)
3. systemPrompt       (your custom instructions)
4. Memory             (shared + agent-specific, from previous sessions)
5. Skills             (content from assigned SKILL.md files)
Here’s a complete example. Given this agent: 
{
  "name": "backend-dev",
  "role": "Senior backend engineer",
  "identity": {
    "displayName": "Alex Chen",
    "title": "Senior Backend Engineer",
    "tone": "Direct, technical",
    "responsibilities": [
      { "area": "API Development", "description": "Design and implement REST APIs", "priority": "critical" },
      "Code review"
    ]
  },
  "reportsTo": "tech-lead",
  "systemPrompt": "Write clean, tested TypeScript. Prefer small changes.",
  "skills": ["api-security"]
}
Polpo generates this system prompt: 
You are backend-dev, a Senior backend engineer.
Complete your assigned task autonomously. Make reasonable decisions and proceed without asking questions.

Your task description may include context tags:
- <shared-memory> — persistent shared knowledge, visible to all agents
- <agent-memory> — your private memory from previous sessions
- <system-context> — standing instructions from the project owner
- <plan-context> — the plan goal and other tasks in parallel
Use this context to make better decisions, but focus on YOUR assigned task.

## Your Identity
- Name: Alex Chen
- Title: Senior Backend Engineer
Use this identity when communicating externally (emails, messages, etc.).

## Your Responsibilities
- **API Development** [critical]: Design and implement REST APIs
- Code review
Focus on these responsibilities. Escalate if something falls outside your scope.

## Communication Style
Direct, technical

## Organization
You report to: tech-lead
If you encounter blockers or decisions outside your authority, escalate to your manager.

Write clean, tested TypeScript. Prefer small changes.

## Your persistent memory

Customer prefers email over phone.
Last issue: billing dispute — resolved Dec 15.

## Skills: api-security
[skill content injected here]
Your systemPrompt is appended, not a replacement. Don’t repeat information already in role, identity, memory, or skills — everything is injected automatically.

​
Extended thinking

For complex tasks, enable reasoning: 
{
  "name": "architect",
  "model": "anthropic/claude-sonnet-4-5",
  "reasoning": "high"
}
Levels: off, minimal, low, medium, high, xhigh. Higher levels use more tokens but produce better results for complex problems.

​
Agent limits

{
  "name": "backend-dev",
  "maxTurns": 200,
  "maxConcurrency": 3
}
  • maxTurns — max conversation turns per task (default: 150)
  • maxConcurrency — max tasks running in parallel

​
Teams and hierarchy

Agents are organized into teams and can report to other agents for escalation. See Teams for the full guide.

​
Complete example

.polpo/agents.json: 
[
  {
    "agent": {
      "name": "backend-dev",
      "role": "Backend engineer. Writes and maintains server-side code.",
      "model": "anthropic/claude-sonnet-4-5",
      "systemPrompt": "Write clean, tested TypeScript. Prefer small changes.",
      "allowedTools": ["read", "write", "edit", "bash", "glob", "grep", "http_fetch"],
      "allowedPaths": ["src/server", "tests"],
      "maxTurns": 200,
      "reasoning": "medium",
      "reportsTo": "tech-lead",
      "skills": ["api-security", "testing"],
      "identity": {
        "displayName": "Alex Chen",
        "title": "Senior Backend Engineer",
        "tone": "Direct, technical",
        "personality": "Analytical, pragmatic",
        "responsibilities": [
          { "area": "API Development", "description": "Design and implement REST APIs", "priority": "critical" },
          "Code review",
          "Database schema design"
        ]
      }
    },
    "teamName": "engineering"
  },
  {
    "agent": {
      "name": "tech-lead",
      "role": "Technical lead. Reviews code and coordinates the team.",
      "model": "anthropic/claude-sonnet-4-5",
      "reasoning": "high"
    },
    "teamName": "engineering"
  }
]
For the full field-by-field reference, see Agents and Configuration in the Reference.