Skip to main content
Agents are stored in .polpo/agents.json as an array of AgentEntry objects. Each entry wraps an AgentConfig with a teamName.

AgentEntry

The file format — each element in the agents.json array:
interface AgentEntry {
  agent: AgentConfig;
  teamName: string;
}

AgentConfig

interface AgentConfig {
  name: string;
  role?: string;
  model?: string;
  systemPrompt?: string;
  allowedTools?: string[];
  allowedPaths?: string[];
  skills?: string[];
  maxTurns?: number;
  maxConcurrency?: number;
  reasoning?: ReasoningLevel;
  reportsTo?: string;
  identity?: AgentIdentity;
  volatile?: boolean;
  missionGroup?: string;
  browserProfile?: string;
  emailAllowedDomains?: string[];
  createdAt?: string;
  version?: string;
  author?: string;
  tags?: string[];
}

AgentIdentity

interface AgentIdentity {
  displayName?: string;
  title?: string;
  company?: string;
  email?: string;
  bio?: string;
  timezone?: string;
  avatar?: string;
  tone?: string;
  personality?: string;
  responsibilities?: (string | AgentResponsibility)[];
  socials?: Record<string, string>;
}

AgentResponsibility

interface AgentResponsibility {
  area: string;
  description: string;
  priority?: "critical" | "high" | "medium" | "low";
}

Example

A complete agents.json file:
[
  {
    "agent": {
      "name": "backend-dev",
      "role": "Senior backend engineer",
      "model": "anthropic/claude-sonnet-4-5",
      "systemPrompt": "Focus on clean, tested TypeScript code.",
      "allowedTools": ["read", "write", "edit", "bash", "glob", "grep"],
      "skills": ["api-security", "database-design"],
      "maxTurns": 200,
      "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",
          "Database schema design"
        ]
      }
    },
    "teamName": "engineering"
  }
]

Vault entries

Each agent can have encrypted credentials stored in the vault:
interface VaultEntry {
  type: "smtp" | "imap" | "oauth" | "api_key" | "login" | "custom";
  label?: string;
  credentials: Record<string, string>;
}

Teams

Teams are stored separately in .polpo/teams.json. Each agent references its team via teamName in the AgentEntry wrapper.
interface Team {
  name: string;
  description?: string;
}