@tarko/agent vs pi-mono

┌─────────────────────────────────┐
│         Agent (公开 API)         │
│  run() / abort() / status()     │
├─────────────────────────────────┤
│        BaseAgent (钩子层)        │
│  onLLMRequest / onBeforeToolCall│
│  onEachAgentLoopStart / ...     │
├─────────────────────────────────┤
│        AgentRunner (协调器)      │
│  LLMProcessor / ToolProcessor   │
│  LoopExecutor / StreamAdapter   │
├─────────────────────────────────┤
│       Tool Call Engine 层        │
│  Native / PromptEngineering     │
│  StructuredOutputs              │
├─────────────────────────────────┤
│      @tarko/model-provider       │
│      多 Provider 统一接口         │
└─────────────────────────────────┘

┌────────────────────────────────┐
│         Agent (状态机)          │
│  prompt() / steer() / abort()  │
│  subscribe(fn)                  │
├────────────────────────────────┤
│    AgentState (响应式状态)       │
│  model / tools / messages      │
│  isStreaming / streamMessage   │
├────────────────────────────────┤
│       _runLoop (内部)           │
│  runAgentLoop / agentLoop      │
├────────────────────────────────┤
│   @mariozechner/pi-ai (底层)    │
│  streamSimple + 各 Provider    │
└────────────────────────────────┘

import { Agent } from "@tarko/agent";

const agent = new Agent({
  instructions: "你是一个编程助手",
  model: { provider: "openai", id: "gpt-4o" },
  tools: [weatherTool],
  maxIterations: 10,
});

const result = await agent.run("帮我调试这段代码");
console.log(result.content);

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"),
    tools: [weatherTool],
  },
});

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

await agent.prompt("帮我调试这段代码");

class MyAgent extends Agent {
  // LLM 请求前
  async onLLMRequest(id: string, payload: LLMRequestHookPayload) {
    console.log("即将请求 LLM", payload.messages.length);
  }

  // LLM 响应后
  async onLLMResponse(id: string, payload: LLMResponseHookPayload) {
    console.log("LLM 回复完成");
  }

  // 每次循环开始
  async onEachAgentLoopStart(sessionId: string) {
    console.log("第 N 次循环开始");
  }

  // 每次循环结束（含本轮 tool call 结果）
  async onEachAgentLoopEnd(context: EachAgentLoopEndContext) {}

  // tool call 前（可修改参数）
  async onBeforeToolCall(id, toolCall, args) {
    return args; // 可以修改后返回
  }

  // tool call 后（可修改结果）
  async onAfterToolCall(id, toolCall, result) {
    return result;
  }

  // tool 报错
  async onToolCallError(id, toolCall, error) {
    return `Error: ${error}`;
  }

  // 即将结束循环时 — 可以强制继续
  async onBeforeLoopTermination(
    id,
    finalEvent,
  ): Promise<LoopTerminationCheckResult> {
    if (!finalEvent.content.includes("done")) {
      return { finished: false }; // 强制再跑一轮
    }
    return { finished: true };
  }

  // 动态修改 system prompt 和 tools（每轮 LLM 请求前）
  async onPrepareRequest(
    context: PrepareRequestContext,
  ): Promise<PrepareRequestResult> {
    return {
      systemPrompt: context.systemPrompt + "\n当前时间：" + new Date(),
      tools: context.tools.filter((t) => t.name !== "dangerous_tool"),
    };
  }
}

const agent = new Agent({
  // tool call 前（可拦截/阻止）
  beforeToolCall: async (ctx, signal) => {
    if (ctx.toolCall.name === "dangerous_tool") {
      return { block: true, reason: "不允许执行危险工具" };
    }
  },

  // tool call 后（可覆盖结果）
  afterToolCall: async (ctx, signal) => {
    return {
      content: [{ type: "text", text: JSON.stringify(ctx.result.details) }],
      isError: false,
    };
  },

  // 消息发给 LLM 前的转换（过滤自定义消息类型）
  convertToLlm: (messages) =>
    messages.filter((m) =>
      ["user", "assistant", "toolResult"].includes(m.role),
    ),

  // 上下文窗口管理（token 压缩等）
  transformContext: async (messages) => {
    if (estimateTokens(messages) > 100000) {
      return pruneOldMessages(messages);
    }
    return messages;
  },
});

// 非流式 — 返回最终 AssistantMessageEvent
const result = await agent.run("问题");
console.log(result.content);

// 流式 — 返回 AsyncIterable<AgentEventStream.Event>
for await (const event of await agent.run({ input: "问题", stream: true })) {
  switch (event.type) {
    case "assistant_message_chunk":
      process.stdout.write(event.content);
      break;
    case "tool_call_start":
      console.log("开始调用工具", event.name);
      break;
    case "agent_run_end":
      console.log("结束，共迭代", event.iterations, "次");
      break;
  }
}

// 也可以监听内部 EventStream
agent.getEventStream().on("*", (event) => {
  /* 全量监听 */
});

// 订阅事件（响应式 UI 友好）
const unsubscribe = agent.subscribe((event) => {
  switch (event.type) {
    case "message_update":
      // 每个流式 chunk
      break;
    case "tool_execution_start":
      showToolLoading(event.toolName);
      break;
    case "tool_execution_end":
      hideToolLoading(event.toolCallId);
      break;
    case "agent_end":
      renderFinalMessages(event.messages);
      break;
  }
});

// 永远是 Promise<void>，数据通过事件推送
await agent.prompt("问题");
unsubscribe();

const agent = new Agent({
  toolCallEngine: "native", // 使用模型原生 function calling（默认）
  // toolCallEngine: 'prompt_engineering', // 把工具定义注入 prompt，解析 LLM 文本输出
  // toolCallEngine: 'structured_outputs', // 用结构化输出模式
});

// Steering：在 Agent 运行中插入引导消息（下一轮 tool call 完成后生效）
agent.steer({
  role: "user",
  content: [{ type: "text", text: "等等，先把结果保存到文件" }],
  timestamp: Date.now(),
});

// FollowUp：Agent 完成当前任务后自动继续的消息
agent.followUp({
  role: "user",
  content: [{ type: "text", text: "现在生成一份执行报告" }],
  timestamp: Date.now(),
});

// 等待空闲
await agent.waitForIdle();

// 保存快照
const snapshot = await agent.saveSnapshot();

// 用快照创建回放 Agent（确定性上下文）
const replayAgent = new Agent({ snapshot });
replayAgent._setIsReplay();
const result = await replayAgent.run("同样的问题");
// 结果完全可复现

// 在应用代码中扩展
declare module "@mariozechner/pi-agent-core" {
  interface CustomAgentMessages {
    artifact: {
      role: "artifact";
      artifactType: "code" | "image";
      content: string;
      timestamp: number;
    };
    notification: {
      role: "notification";
      level: "info" | "warn" | "error";
      text: string;
      timestamp: number;
    };
  }
}

// 使用自定义消息
agent.appendMessage({
  role: "notification",
  level: "info",
  text: "工具执行耗时 3.2s",
  timestamp: Date.now(),
});