Skip to main content

Agent 核心 — @mariozechner/pi-agent-core

概述​

pi-agent-core 是建立在 @mariozechner/pi-ai 之上的状态化 Agent 运行时，支持工具执行和事件流。

安装​

npm install @mariozechner/pi-agent-core

快速开始​

import { Agent } from "@mariozechner/pi-agent-core";
import { getModel } from "@mariozechner/pi-ai";

const agent = new Agent({
  initialState: {
    systemPrompt: "你是一个有用的助手。",
    model: getModel("anthropic", "claude-sonnet-4-20250514"),
  },
});

agent.subscribe((event) => {
  if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
    process.stdout.write(event.assistantMessageEvent.delta);
  }
});

await agent.prompt("你好！");

核心概念​

AgentMessage vs LLM Message​

Agent 使用 AgentMessage，这是一个灵活的类型：

  • 标准 LLM 消息（user、assistant、toolResult）
  • 自定义应用特定消息类型

LLM 只理解 user、assistant 和 toolResult。convertToLlm() 函数在每次 LLM 调用前过滤和转换消息。

消息流程​

AgentMessage[] → transformContext() → AgentMessage[] → convertToLlm() → Message[] → LLM
  1. transformContext：修剪旧消息，注入外部上下文
  2. convertToLlm：过滤 UI 专用消息，转换自定义类型

事件流程​

prompt() 事件序列​

prompt("Hello")
├─ agent_start
├─ turn_start
├─ message_start   { message: userMessage }      // 你的输入
├─ message_end     { message: userMessage }
├─ message_start   { message: assistantMessage } // LLM 开始响应
├─ message_update  { message: partial... }       // 流式片段
├─ message_update  { message: partial... }
├─ message_end     { message: assistantMessage } // 完整响应
├─ turn_end        { message, toolResults: [] }
└─ agent_end       { messages: [...] }

带工具调用​

如果助手调用工具，循环继续：

prompt("读取 config.json")
├─ agent_start
├─ turn_start
├─ message_start/end  { userMessage }
├─ message_start      { assistantMessage with toolCall }
├─ message_update...
├─ message_end        { assistantMessage }
├─ tool_execution_start  { toolCallId, toolName, args }
├─ tool_execution_end    { toolCallId, result }
├─ message_start/end  { toolResultMessage }
├─ turn_end           { message, toolResults: [toolResult] }
│
├─ turn_start                                        // 下一轮
├─ message_start      { assistantMessage }           // LLM 响应工具结果
├─ message_update...
├─ message_end
└─ agent_end

事件类型​

事件说明
agent_startAgent 开始
agent_endAgent 结束
turn_start轮次开始
turn_end轮次结束
message_start消息开始
message_update消息更新（流式）
message_end消息结束
tool_execution_start工具执行开始
tool_execution_update工具执行更新
tool_execution_end工具执行结束

翻译自 @mariozechner/pi-agent-core