polpo-sdk

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Polpo SDK Integration

Polpo SDK 集成

Install

安装

bash

npm install @polpo-ai/sdk

bash

npm install @polpo-ai/sdk

Client Setup

客户端配置

typescript

import { PolpoClient } from "@polpo-ai/sdk";

// baseUrl is the root URL — SDK appends /v1/ internally.
// Do NOT add /v1/ or /api/v1/ to baseUrl.
const polpo = new PolpoClient({
  baseUrl: "https://api.polpo.sh",  // local dev: http://localhost:3890
  apiKey: process.env.POLPO_API_KEY,
});

typescript

import { PolpoClient } from "@polpo-ai/sdk";

// baseUrl为根地址 — SDK会在内部自动拼接/v1/
// 请勿在baseUrl中添加/v1/或/api/v1/前缀
const polpo = new PolpoClient({
  baseUrl: "https://api.polpo.sh",  // 本地开发地址: http://localhost:3890
  apiKey: process.env.POLPO_API_KEY,
});

Chat Completions (Non-Streaming)

聊天补全（非流式）

typescript

const response = await polpo.chatCompletion({
  agent: "coder",
  messages: [{ role: "user", content: "Write a fibonacci function" }],
});

console.log(response.choices[0].message.content);

typescript

const response = await polpo.chatCompletion({
  agent: "coder",
  messages: [{ role: "user", content: "Write a fibonacci function" }],
});

console.log(response.choices[0].message.content);

Chat Completions (Streaming SSE)

聊天补全（SSE流式传输）

typescript

const stream = await polpo.chatCompletionStream({
  agent: "coder",
  messages: [{ role: "user", content: "Explain recursion" }],
});

// stream.sessionId — persisted session ID from server
for await (const chunk of stream) {
  const delta = chunk.choices[0]?.delta?.content;
  if (delta) process.stdout.write(delta);
}

typescript

const stream = await polpo.chatCompletionStream({
  agent: "coder",
  messages: [{ role: "user", content: "Explain recursion" }],
});

// stream.sessionId — 服务端返回的持久化会话ID
for await (const chunk of stream) {
  const delta = chunk.choices[0]?.delta?.content;
  if (delta) process.stdout.write(delta);
}

Sessions

会话

Sessions persist conversation history. The server auto-creates sessions; use

sessionId

to continue a conversation.

typescript

// List sessions
const sessions = await polpo.listChatSessions();

// Get messages from a session
const { session, messages } = await polpo.getChatSessionMessages(sessionId);

// Continue a session
const stream = await polpo.chatCompletionStream({
  agent: "coder",
  sessionId: existingSessionId,
  messages: [{ role: "user", content: "Now refactor it" }],
});

会话会持久化存储对话历史。服务端会自动创建会话，你可以使用

sessionId

来延续对话。

typescript

// 列出会话
const sessions = await polpo.listChatSessions();

// 获取单个会话的消息内容
const { session, messages } = await polpo.getChatSessionMessages(sessionId);

// 延续会话
const stream = await polpo.chatCompletionStream({
  agent: "coder",
  sessionId: existingSessionId,
  messages: [{ role: "user", content: "Now refactor it" }],
});

Agents

Agent管理

typescript

// List agents
const agents = await polpo.getAgents();

// Create agent
await polpo.addAgent({
  name: "reviewer",
  role: "Code reviewer",
  model: "xai:grok-4-fast",
  allowedTools: ["bash", "read", "grep"],
  systemPrompt: "You review code for bugs and security issues.",
});

// Update agent
await polpo.updateAgent("reviewer", { model: "anthropic:claude-sonnet-4" });

typescript

// 列出所有Agent
const agents = await polpo.getAgents();

// 创建Agent
await polpo.addAgent({
  name: "reviewer",
  role: "Code reviewer",
  model: "xai:grok-4-fast",
  allowedTools: ["bash", "read", "grep"],
  systemPrompt: "You review code for bugs and security issues.",
});

// 更新Agent配置
await polpo.updateAgent("reviewer", { model: "anthropic:claude-sonnet-4" });

Memory

记忆功能

typescript

// Project memory (shared across all agents)
const { content } = await polpo.getMemory();
await polpo.saveMemory("# Project Context\n\nThis is a Next.js e-commerce app...");

// Agent memory (private to one agent)
const agentMem = await polpo.getAgentMemory("coder");
await polpo.saveAgentMemory("coder", "Prefers TypeScript, uses Vitest for tests.");

typescript

// 项目记忆（所有Agent共享）
const { content } = await polpo.getMemory();
await polpo.saveMemory("# Project Context\n\nThis is a Next.js e-commerce app...");

// Agent专属记忆（仅单个Agent可访问）
const agentMem = await polpo.getAgentMemory("coder");
await polpo.saveAgentMemory("coder", "Prefers TypeScript, uses Vitest for tests.");

Webhooks

Webhook

typescript

// Register a webhook
await polpo.registerWebhook({
  url: "https://myapp.com/webhook",
  events: ["task:*", "mission:completed"],
});

typescript

// 注册Webhook
await polpo.registerWebhook({
  url: "https://myapp.com/webhook",
  events: ["task:*", "mission:completed"],
});

SSE Real-Time Events

SSE实时事件

typescript

import { EventSourceManager } from "@polpo-ai/sdk";

const sse = new EventSourceManager({
  baseUrl: "https://api.polpo.sh",
  apiKey: process.env.POLPO_API_KEY,
});

sse.connect({ filter: "task:*" });
sse.on("task:transition", (data) => {
  console.log(`Task ${data.id}: ${data.from} → ${data.to}`);
});

typescript

import { EventSourceManager } from "@polpo-ai/sdk";

const sse = new EventSourceManager({
  baseUrl: "https://api.polpo.sh",
  apiKey: process.env.POLPO_API_KEY,
});

sse.connect({ filter: "task:*" });
sse.on("task:transition", (data) => {
  console.log(`任务 ${data.id}: ${data.from} → ${data.to}`);
});

Key Types

核心类型

See references/types.md for the full type reference including

Task

AgentConfig

Mission

Session

ChatCompletionRequest

ChatCompletionResponse

, and all request/response DTOs.

完整的类型定义参考请查看references/types.md，包含

Task

、

AgentConfig

、

Mission

、

Session

、

ChatCompletionRequest

、

ChatCompletionResponse

以及所有请求/响应DTO。

API Endpoints Reference

API端点参考

See references/api.md for the complete API endpoint list with methods, paths, and descriptions.

完整的API端点列表（包含请求方法、路径和说明）请查看references/api.md。