An agent is a named AI worker on Polpo’s team. Each agent gets a model, a role, an identity (who they are, how they communicate), a credential vault (what services they can access), and a place in the org chart (who they report to).
Copy
Ask AI
{ "name": "alice", "role": "social media manager", "model": "anthropic:claude-sonnet-4-6", "reportsTo": "marco", "identity": { "displayName": "Alice Chen", "title": "Social Media Manager", "company": "Acme Corp", "email": "alice@acme.com", "responsibilities": [ { "area": "Social Media", "description": "Manage all company social accounts", "priority": "high" }, { "area": "Customer Relations", "description": "Respond to inquiries within 2 hours", "priority": "critical" } ], "tone": "Professional but warm. Uses first names. Keeps emails under 3 paragraphs.", "personality": "Empathetic and detail-oriented. Data-driven — always cites metrics." }, "allowedTools": ["read", "write", "edit", "bash", "glob", "grep", "ls", "email_*"], "allowedPaths": ["./content", "./reports"]}
An agent’s identity defines who it is — not just what it does. Polpo injects identity fields into the agent’s system prompt:
Display name, title, company — used when the agent writes emails or external messages
Responsibilities — structured by area with priority levels, so the agent knows what to focus on and what to escalate. Supports both simple strings ("Manage social media") and structured objects ({ "area": "...", "description": "...", "priority": "high" })
Tone — communication style: HOW the agent communicates (register, format, length preferences)
Personality — character traits: WHO the agent IS (approach, values, working style)
Timezone — for time-aware decisions
Tone vs. Personality: Tone controls the form of communication — “Professional but warm. Keeps emails under 3 paragraphs. Uses bullet points.” Personality controls the substance — “Empathetic and detail-oriented. Anticipates concerns. Prefers data-backed decisions.” Together, they produce consistent, realistic agent behavior.
While you can write identity JSON by hand, the recommended approach is the onboarding wizard:
Copy
Ask AI
polpo agent onboard alice
This interactive CLI walks through 5 steps — identity, persona (responsibilities + tone + personality), hierarchy, email, and additional vault credentials. Agent config is written to .polpo/polpo.json; vault entries are stored in .polpo/vault.enc (AES-256-GCM encrypted).After onboarding, verify the result:
Copy
Ask AI
polpo agent show alice # full profile with masked credentialspolpo agent list # org chart tree
Each agent can have its own set of credentials for different services (SMTP, IMAP, OAuth, API keys, logins). Vault entries are stored in .polpo/vault.enc, encrypted with AES-256-GCM — they are not part of polpo.json.Manage vault entries via:
CLI: polpo agent onboard <name> — the Email and Vault steps write to the encrypted store
TUI / Chat: Use the built-in tools — set_vault_entry, remove_vault_entry, list_vault
Credential values support ${ENV_VAR} references — Polpo resolves them at runtime from environment variables. Credential resolution order: tool parameters > vault > environment variables.See Configuration — Encrypted Vault for vault entry fields and key management.
The reportsTo field creates an org chart. When a task fails and the retry policy has no explicit fallbackAgent, Polpo automatically escalates to the agent’s manager:
Copy
Ask AI
marco (Team Lead)├── alice (Social Media Manager)└── bob (Backend Developer)
Polpo runs agents on its built-in engine — a multi-provider LLM runtime powered by pi-agent-core. It supports 18+ providers (OpenAI, Anthropic, Google, Groq, Mistral, Ollama, etc.) and runs in-process.The model format is provider:model-id. If you omit the provider prefix, Polpo resolves it from your configured providers.
