polpo-agents

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Polpo Agent Design

Polpo Agent 设计

Agent Configuration

Agent 配置

An agent is defined by its

AgentConfig

. Create via API or dashboard.

typescript

{
  name: "coder",                              // unique identifier
  role: "Senior Full-Stack Engineer",         // human-readable role description
  model: "xai:grok-4-fast",                  // provider:model format
  allowedTools: ["bash", "read", "write", "edit", "glob", "grep"],
  systemPrompt: "You are a senior engineer. Write clean, tested code.",
  maxTurns: 150,                              // max LLM turns per session
  maxConcurrency: 3,                          // max parallel tasks
  reasoning: "medium",                        // thinking depth
}

Agent 由其

AgentConfig

定义，可通过API或控制面板创建。

typescript

{
  name: "coder",                              // 唯一标识符
  role: "Senior Full-Stack Engineer",         // 可读的角色描述
  model: "xai:grok-4-fast",                  // 服务商:模型 格式
  allowedTools: ["bash", "read", "write", "edit", "glob", "grep"],
  systemPrompt: "You are a senior engineer. Write clean, tested code.",
  maxTurns: 150,                              // 单会话最大LLM交互轮次
  maxConcurrency: 3,                          // 最大并行任务数
  reasoning: "medium",                        // 思考深度
}

Model Selection

模型选择

Format:

provider:model

. Choose based on task complexity and cost.

Use Case	Recommended	Why
Fast coding tasks	`xai:grok-4-fast`	Fast, capable, good tool use
Complex reasoning	`anthropic:claude-sonnet-4`	Best reasoning
Budget tasks	`xai:grok-3-mini-fast`	Cheap, fast
Vision tasks	`openai:gpt-4o`	Strong multimodal

Browse all available models at polpo.sh/api/gateway/models (JSON) or see docs.polpo.sh/developers/reference/providers for a guide.

格式：

provider:model

，可根据任务复杂度和成本选择。

适用场景	推荐模型	原因
快速编码任务	`xai:grok-4-fast`	速度快、能力强，工具调用表现好
复杂推理任务	`anthropic:claude-sonnet-4`	推理能力最优
低成本任务	`xai:grok-3-mini-fast`	价格低廉、速度快
视觉任务	`openai:gpt-4o`	多模态能力出色

可访问 polpo.sh/api/gateway/models（JSON格式）查看所有可用模型，或参考 docs.polpo.sh/developers/reference/providers 查看使用指南。

Tools

工具

Tools define what an agent can do. Assign only what's needed — follow the principle of least privilege. Every tool must be explicitly listed in

allowedTools

to be available.

工具定义了Agent可执行的操作。仅分配必要的工具——遵循最小权限原则。所有工具必须显式列在

allowedTools

中才会生效。

Coding Tools

编码工具

```
bash
```
— Execute shell commands (sandboxed)
```
read
```
— Read files
```
write
```
— Create/overwrite files
```
edit
```
— Search-and-replace in files
```
glob
```
— Find files by pattern
```
grep
```
— Search file contents

```
bash
```
— 执行shell命令（沙箱环境）
```
read
```
— 读取文件
```
write
```
— 创建/覆盖文件
```
edit
```
— 文件内搜索替换
```
glob
```
— 按规则查找文件
```
grep
```
— 搜索文件内容

Additional Tools

其他工具

Polpo supports additional tool categories (integration, email, image generation, and more). Each must be explicitly assigned in

allowedTools

— agents have no tools by default beyond what you configure.

For the complete tool catalog, see docs.polpo.sh/docs/agents/tools.

Polpo支持更多工具类别（集成、邮件、图像生成等）。每个工具都必须显式分配到

allowedTools

中——默认情况下，除了你配置的工具外，Agent没有任何可用工具。

完整工具目录可查看 docs.polpo.sh/docs/agents/tools。

Security Notes

安全注意事项

All tool execution runs inside an isolated sandbox — agents cannot access the host system or other projects.
```
vault_get
```
only returns credentials explicitly assigned to that agent. Agents cannot access other agents' credentials.
```
email_*
```
tools enforce
```
emailAllowedDomains
```
— restrict which domains an agent can email.
Follow the principle of least privilege — only assign tools an agent actually needs for its role.

所有工具执行都在隔离沙箱中运行——Agent无法访问宿主机系统或其他项目。
```
vault_get
```
仅返回显式分配给该Agent的凭证，Agent无法访问其他Agent的凭证。
```
email_*
```
类工具强制校验
```
emailAllowedDomains
```
——限制Agent可发送邮件的域名范围。
遵循最小权限原则——仅分配Agent完成其角色任务实际需要的工具。

System Prompt

系统提示词

The system prompt defines the agent's behavior. Keep it focused.

You are {name}, a {role}.

{Core instructions — what to do, how to do it}

{Constraints — what NOT to do}

{Output format preferences}

Good system prompt:

You are a code reviewer. Review code for bugs, security issues, and performance problems.
Be concise. Flag critical issues first. Suggest fixes with code examples.
Never approve code with SQL injection or XSS vulnerabilities.

Bad system prompt: Overly long, generic instructions that Claude already knows.

系统提示词定义了Agent的行为，尽量保持内容聚焦。

你是 {name}，一名 {role}。

{核心指令——需要做什么，如何执行}

{约束——禁止做的事}

{输出格式偏好}

优质系统提示词示例：

你是一名代码评审员，负责检查代码中的Bug、安全问题和性能缺陷。
Be concise. Flag critical issues first. Suggest fixes with code examples.
永远不要批准存在SQL注入或XSS漏洞的代码。

劣质系统提示词示例： 过长、过于通用的指令，是Claude本身已经知晓的内容。

Identity

身份

For agents that interact with humans (email, chat, social), define an identity:

typescript

identity: {
  displayName: "Alex",
  title: "Engineering Lead",
  bio: "I help teams ship reliable software.",
  tone: "Direct, technical, no fluff",
  personality: "Pragmatic problem-solver",
  responsibilities: [
    { area: "Code review", description: "Review all PRs", priority: "critical" },
    { area: "Architecture", description: "System design decisions", priority: "high" },
  ],
  socials: { github: "alex-eng", twitter: "@alex_ships" },
}

For more on agent identity, see docs.polpo.sh/docs/agents/definition.

对于需要和人类交互的Agent（邮件、聊天、社交场景），需要定义身份：

typescript

identity: {
  displayName: "Alex",
  title: "Engineering Lead",
  bio: "I help teams ship reliable software.",
  tone: "Direct, technical, no fluff",
  personality: "Pragmatic problem-solver",
  responsibilities: [
    { area: "Code review", description: "Review all PRs", priority: "critical" },
    { area: "Architecture", description: "System design decisions", priority: "high" },
  ],
  socials: { github: "alex-eng", twitter: "@alex_ships" },
}

更多关于Agent身份的内容可查看 docs.polpo.sh/docs/agents/definition。

Memory

记忆

Memory persists across sessions. Two levels:

记忆可跨会话持久化，分为两个层级：

Project Memory

项目记忆

Shared by all agents. Use for project context, conventions, architecture decisions.

undefined

所有Agent共享，用于存储项目上下文、规范、架构决策等内容。

undefined

Project Context

项目上下文

Next.js 15 + TypeScript + Tailwind
PostgreSQL via Drizzle ORM
Deploy on Vercel

Next.js 15 + TypeScript + Tailwind
PostgreSQL via Drizzle ORM
部署在Vercel

Conventions

规范

Use Vitest for tests
Prefer server components
No default exports (except pages)

undefined

使用Vitest进行测试
优先使用服务端组件
无默认导出（页面除外）

undefined

Agent Memory

Agent记忆

Private to one agent. Auto-accumulated as the agent works. Use for agent-specific learnings.

undefined

单个Agent私有，随Agent工作自动积累，用于存储Agent专属的学习内容。

undefined

Learned Preferences

习得偏好

User prefers functional style over classes
Always run tests before committing
Use pnpm, not npm


Memory is read by the agent at the start of each session. Update via API:
- `PUT /v1/memory` — project memory
- `PUT /v1/memory/agent/{name}` — agent memory

For more on memory, see [docs.polpo.sh/docs/agents/memory](https://docs.polpo.sh/docs/agents/memory).

用户偏好函数式编程风格，不喜欢类
提交代码前必须运行测试
使用pnpm，不要用npm


Agent会在每个会话启动时读取记忆内容，可通过API更新：
- `PUT /v1/memory` — 更新项目记忆
- `PUT /v1/memory/agent/{name}` — 更新指定Agent的记忆

更多关于记忆的内容可查看 [docs.polpo.sh/docs/agents/memory](https://docs.polpo.sh/docs/agents/memory)。

Vault

Vault（密钥库）

Store service credentials that agents access at runtime. Credentials are scoped per-agent — an agent can only access entries explicitly assigned to it.

typescript

// Store credentials
POST /v1/vault/entries
{
  agent: "emailer",
  service: "gmail",
  type: "smtp",
  credentials: { host: "smtp.gmail.com", port: 587, user: "...", pass: "..." }
}

// Agent uses vault_get("gmail") at runtime — credentials never in system prompt

Credential types:

smtp

imap

oauth

api_key

login

custom

For more on vault, see docs.polpo.sh/docs/agents/vault.

存储Agent运行时可访问的服务凭证，凭证按Agent划分权限——Agent仅能访问显式分配给它的条目。

typescript

// 存储凭证
POST /v1/vault/entries
{
  agent: "emailer",
  service: "gmail",
  type: "smtp",
  credentials: { host: "smtp.gmail.com", port: 587, user: "...", pass: "..." }
}

// Agent运行时调用 vault_get("gmail") 获取凭证——凭证永远不会出现在系统提示词中

凭证类型包括：

smtp

、

imap

、

oauth

、

api_key

、

login

、

custom

。

更多关于Vault的内容可查看 docs.polpo.sh/docs/agents/vault。

Agent Patterns

Agent 模式

See references/patterns.md for multi-agent architectures, specialization patterns, and reporting hierarchies.

查看 references/patterns.md 了解多Agent架构、专业化模式和汇报层级相关内容。

Need Help Designing Your Agent?

需要帮助设计你的Agent？

Not sure which tools, model, or configuration your agent needs? Ask your coding agent:

"I want to create a Polpo agent that [describe what it should do]. Help me choose the right model, tools, and system prompt. Use the polpo-agents skill for reference."

Your coding agent will help you pick the right configuration based on your use case.

不确定你的Agent需要哪些工具、模型或配置？可以询问你的编码Agent：

"我想创建一个能[描述需求]的Polpo Agent，帮我选择合适的模型、工具和系统提示词，参考polpo-agents skill的内容。"

你的编码Agent会根据你的使用场景帮你选择合适的配置。