在过去两年里接触了太多零碎的agent相关的知识,好像哪里都懂一些,但是又没有完整的看过一整套harness的代码,现在准备好好读一下pi的源码,把整个学习过程整理记录一下。
从AgentLoop开始:
在25年初我第一次看到agentloop的时候,看到的就是类似这样一段伪代码:用户输入的内容丢给大模型,返回output和要调用的工具,调用完工具后,把output和工具产出都追加到 prompt中,进行下一轮调用。 直到判断loop结束。
python
prompt = user_input
while not finish:
output, tool_call = llm(prompt)
tool_result = execute(tool_call)
prompt += output + tool_result
先看agent的type定义文件 pi\packages\agent\src\types.ts
找到了Agent的生命周期,和我们伪代码中的理解一致:
agent整体-> 每一轮turn-> message 和 tool_execute。 基本的loop结构没有变。
typescript
/**
* Events emitted by the Agent for UI updates.
*
* `agent_end` is the last event emitted for a run, but awaited `Agent.subscribe()`
* listeners for that event are still part of run settlement. The agent becomes
* idle only after those listeners finish.
*/
export type AgentEvent =
// Agent lifecycle
| { type: "agent_start" }
| { type: "agent_end"; messages: AgentMessage[] }
// Turn lifecycle - a turn is one assistant response + any tool calls/results
| { type: "turn_start" }
| { type: "turn_end"; message: AgentMessage; toolResults: ToolResultMessage[] }
// Message lifecycle - emitted for system, user, assistant, and toolResult messages
| { type: "message_start"; message: AgentMessage }
// Only emitted for assistant messages during streaming
| { type: "message_update"; message: AgentMessage; assistantMessageEvent: AssistantMessageEvent }
| { type: "message_end"; message: AgentMessage }
// Tool execution lifecycle
| { type: "tool_execution_start"; toolCallId: string; toolName: string; args: any }
| { type: "tool_execution_update"; toolCallId: string; toolName: string; args: any; partialResult: any }
| {
type: "tool_execution_end";
toolCallId: string;
toolName: string;
result: any;
isError: boolean;
/** Milliseconds `execute()` took, measured with a monotonic clock; absent when the tool did not run. */
durationMs?: number;
};
另一个我很感兴趣的定义,Agent状态:
可以看出定义一个Agent 的主要设置包括:
- 系统提示词
- 模型
- 思考强度
- tool(get set)
- message(get set)
- 一些agent当前的运行状态(readonly)
typescript
/**
* Public agent state.
*
* `tools` and `messages` use accessor properties so implementations can copy
* assigned arrays before storing them.
*/
export interface AgentState {
/**
* Current system prompt, replayed from the transcript's system messages.
*
* Read-only: to change the prompt, append a system message with `content` or `sections`.
* In `initialState`, this seeds the leading system message.
*/
readonly systemPrompt: string;
/** Active model used for future turns. */
model: Model<any>;
/** Requested reasoning level for future turns. */
thinkingLevel: ThinkingLevel;
/**
* Executable tools. Assigning a new array copies the top-level array.
*
* Differences from the tools declared in the transcript are announced to the model
* with a system message before the next request.
*/
set tools(tools: AgentTool<any>[]);
get tools(): AgentTool<any>[];
/**
* Conversation transcript. Assigning a new array copies the top-level array.
*
* System messages in the transcript carry the prompt and tool declarations.
*/
set messages(messages: AgentMessage[]);
get messages(): AgentMessage[];
/**
* True while the agent is processing a prompt or continuation.
*
* This remains true until awaited `agent_end` listeners settle.
*/
readonly isStreaming: boolean;
/** Partial assistant message for the current streamed response, if any. */
readonly streamingMessage?: AgentMessage;
/** Tool call ids currently executing. */
readonly pendingToolCalls: ReadonlySet<string>;
/** Error message from the most recent failed or aborted assistant turn, if any. */
readonly errorMessage?: string;
}
翻到agent-loop的实现 pi\packages\agent\src\agent-loop.ts
typescript
/**
* Start an agent loop with a new prompt message.
* The prompt is added to the context and events are emitted for it.
*/
export function agentLoop(
prompts: AgentMessage[],
context: AgentContext,
config: AgentLoopConfig,
signal: AbortSignal | undefined,
streamFn: StreamFn,
): EventStream<AgentEvent, AgentMessage[]> {
const stream = createAgentStream();
void runAgentLoop(
prompts,
context,
config,
async (event) => {
stream.push(event);
},
signal,
streamFn,
).then((messages) => {
stream.end(messages);
});
return stream;
}
有个context,之前没关注到,看看context的定义:
果然是messages+tools
typescript
/** Context snapshot passed into the low-level agent loop. */
export interface AgentContext {
/** Transcript visible to the model. */
messages: AgentMessage[];
/** Tools available for execution in this run. */
tools?: AgentTool<any>[];
}
顺便点开messages的定义:
CustomAgentMessages是留给用户扩展用的,点进去默认是空的。 Message预置的定义也和我们之前看到的一样,系统信息,用户query,模型回答,tool调用结果。
typescript
/**
* AgentMessage: Union of LLM messages + custom messages.
* This abstraction allows apps to add custom message types while maintaining
* type safety and compatibility with the base LLM messages.
*/
export type AgentMessage = Message | CustomAgentMessages[keyof CustomAgentMessages];
export type Message = SystemMessage | UserMessage | AssistantMessage | ToolResultMessage;
再看看tools:
typescript
/**
* Tool definition used by the agent runtime. `parameters` is any JSON Schema object; see {@link AgentToolParams} for
* the type `execute` receives.
*/
export interface AgentTool<TParameters extends object = object, TDetails = any> extends Tool<TParameters> {
/** Human-readable label for UI display. */
label: string;
/**
* Optional compatibility shim for raw tool-call arguments before schema validation.
* Must return an object that matches `TParameters`.
*/
prepareArguments?: (args: unknown) => AgentToolParams<TParameters>;
/**
* JSON Schema of `structuredContent` in successful results. Tools that declare it should always
* set `structuredContent`.
*/
outputSchema?: object;
/**
* Execute the tool call. Throw on failure, or return a result with `isError: true`; do not only
* describe the failure in `content`.
*/
execute: (
toolCallId: string,
params: AgentToolParams<TParameters>,
signal?: AbortSignal,
onUpdate?: AgentToolUpdateCallback<TDetails>,
) => Promise<AgentToolResult<TDetails>>;
/** Recovery policy for an effect whose durable intent exists but whose outcome is unknown. */
replay?: "never" | "safe";
/**
* Per-tool execution mode override.
* - "sequential": this tool must execute one at a time with other tool calls.
* - "parallel": this tool can execute concurrently with other tool calls.
*
* If omitted, the default execution mode applies.
*/
executionMode?: ToolExecutionMode;
}
前面都没啥特别的,让我比较感兴趣的是这个executionMode,原来工具串行还是并行是由tool自己声明的,之前一直以为是模型的能力:
typescript
/**
* Configuration for how tool calls from a single assistant message are executed.
*
* - "sequential": each tool call is prepared, executed, and finalized before the next one starts.
* - "parallel": tool calls are prepared sequentially, then allowed tools execute concurrently.
* `tool_execution_end` is emitted in tool completion order after each tool is finalized,
* while tool-result message artifacts are emitted later in assistant source order.
*/
export type ToolExecutionMode = "sequential" | "parallel";
点进runAgentLoop
typescript
export async function runAgentLoop(
prompts: AgentMessage[],
context: AgentContext,
config: AgentLoopConfig,
emit: AgentEventSink,
signal: AbortSignal | undefined,
streamFn: StreamFn,
): Promise<AgentMessage[]> {
const initialMessages = declareToolChanges(context, prompts);
const newMessages: AgentMessage[] = [...initialMessages];
const currentContext: AgentContext = {
...context,
messages: [...context.messages, ...initialMessages],
};
await emit({ type: "agent_start" });
await emit({ type: "turn_start" });
for (const message of initialMessages) {
await emit({ type: "message_start", message });
await emit({ type: "message_end", message });
}
await runLoop(currentContext, newMessages, config, signal, emit, streamFn ?? getDefaultStreamFn());
return newMessages;
}
第一步是declareToolChanges声明工具变化:
这个函数看起来很复杂,实际上做的事情是对齐 context.tools 和 prompts 里面声明的tool。
typescript
/**
* Declare tool loadout changes to the model.
*
* `context.tools` is what the runtime can execute; the transcript's system messages declare
* what the model may call. Before each request the difference becomes `toolsAdded` and
* `toolsRemoved` on a system message. When a pending system message exists, its tool fields
* are treated as intent and replaced with the delta between the committed transcript and
* the executable set, so replay always yields exactly `context.tools`. Otherwise a new
* system message is inserted before the first non-system pending message.
*/
function declareToolChanges(context: AgentContext, pendingMessages: AgentMessage[]): AgentMessage[] {
let systemIndex = -1;
for (let i = pendingMessages.length - 1; i >= 0; i--) {
if (pendingMessages[i].role === "system") {
systemIndex = i;
break;
}
}
const pending = pendingMessages[systemIndex] as SystemMessage | undefined;
const baseline = pending
? pendingMessages.map((message, index) =>
index === systemIndex ? withToolChanges(pending, NO_CHANGES) : message,
)
: pendingMessages;
const changes = getToolStateChanges(
getCurrentTools([...context.messages, ...baseline]),
(context.tools ?? []).map(toToolDeclaration),
);
const unchanged = changes.toolsAdded.length === 0 && changes.toolsRemoved.length === 0;
if (pending) {
// Keep the caller's message object when it already declares no tool changes.
if (unchanged && !pending.toolsAdded?.length && !pending.toolsRemoved?.length) return pendingMessages;
return baseline.map((message, index) => (index === systemIndex ? withToolChanges(pending, changes) : message));
}
if (unchanged) return pendingMessages;
const update = withToolChanges({ role: "system", content: "", timestamp: Date.now() }, changes);
const insertIndex = pendingMessages.findIndex((message) => message.role !== "system");
const index = insertIndex === -1 ? pendingMessages.length : insertIndex;
return [...pendingMessages.slice(0, index), update, ...pendingMessages.slice(index)];
}
先说明一下函数内的几个基本概念:
context.tools 是当轮对话环境真实可用的工具集。
context 是过去的历史对话。
pendingMessages 是本轮新增的对话。
在messages里有一类系统消息:role ==="system" 。在这个消息里会声明 toolsAdded 和toolsRemoved。
typescript
/**
* System instructions and tool declarations at one point in the transcript.
*
* The leading system message is the system prompt. Later system messages change it:
* `content` adds instructions from that point on, `sections` replace or remove named
* prompt sections, and `toolsAdded`/`toolsRemoved` change the tool set. Replaying
* every system message in order yields the current prompt and tools. Providers that
* accept system messages mid-conversation send each one in place; other providers
* rebuild the leading system message from the replayed state.
*/
export interface SystemMessage {
role: "system";
/** Instruction text. On the leading message this is the base prompt; later, additional instructions. */
content: string | TextContent[];
/**
* Named, ordered prompt sections rendered verbatim after `content`. The leading message
* declares them; later messages replace sections by name, and `null` removes one. Keep
* each section self-delimiting (a tag, a heading) so the model can relate an update to
* the original. Avoid integer-like names; JSON objects reorder those.
*/
sections?: Record<string, string | null>;
/** Complete definitions of tools that become available at this point. */
toolsAdded?: Tool[];
/** Tools that stop being available at this point. */
toolsRemoved?: ToolReference[];
timestamp: number; // Unix timestamp in milliseconds
}
那么这个函数的工作流程是这样的:
首先找到最后一条 role === "system" 的 message,并把这一条message的CHANGE部分抹掉。并把抹掉最后一条CHANGE的messagelist 命名为 baseline。
typescript
const baseline = pending
? pendingMessages.map((message, index) =>
index === systemIndex ? withToolChanges(pending, NO_CHANGES) : message,
)
: pendingMessages;
使用 context +baseline 重放(getCurrentTools),得到当前message中推演得到的工具列表。 然后和当下真实的可用工具集context.tools进行对比 。 得到最后需要变更的 changes。
typescript
const changes = getToolStateChanges(
getCurrentTools([...context.messages, ...baseline]),
(context.tools ?? []).map(toToolDeclaration),
);
然后将changes 回写进最后一条 system message 中。 然后做了一个兜底,当pendingmessage中不存在role === system的消息,但是仍然对不齐账,和context.tools 不一致时。 我们会直接新增一条 system消息insert进去。
当然相信很多人也能看到 const insertIndex = pendingMessages.findIndex((message)=> message.role !=="system");这一行完全是多余的嘛,前面pending == undefined 说明pendingmessage里面根本没有 system的消息,所以才会走到下面的兜底逻辑,下面这段等价于 pendingMessages.unshift(update) 嘛 (笑
typescript
if (pending) {
// Keep the caller's message object when it already declares no tool changes.
if (unchanged && !pending.toolsAdded?.length && !pending.toolsRemoved?.length) return pendingMessages;
return baseline.map((message, index) => (index === systemIndex ? withToolChanges(pending, changes) : message));
}
if (unchanged) return pendingMessages;
const update = withToolChanges({ role: "system", content: "", timestamp: Date.now() }, changes);
const insertIndex = pendingMessages.findIndex((message) => message.role !== "system");
const index = insertIndex === -1 ? pendingMessages.length : insertIndex;
return [...pendingMessages.slice(0, index), update, ...pendingMessages.slice(index)];
这样经过了 declareToolChanges 之后,我们可以保证这一轮对话 实际可用的tools 和 context对话中重放后得到的tools 完全对齐一致。过去一直说: 为了保持前缀cache命中,当tools变更的时候,不动前面的history,只在最后追加一条工具的变更。想不到实现竟然如此复杂。
回到我们的agentloop中,后续步骤就很简单了,把initialMessages 复制一份newMessages,给本轮runLoop追加消息,currentContext也同步更新一下刚才message中修的toolchanges的内容,然后emit一些event事件(message_start 和 message_end 就直接连着抛啊。。) 最后runLoop:
typescript
const initialMessages = declareToolChanges(context, prompts);
const newMessages: AgentMessage[] = [...initialMessages];
const currentContext: AgentContext = {
...context,
messages: [...context.messages, ...initialMessages],
};
await emit({ type: "agent_start" });
await emit({ type: "turn_start" });
for (const message of initialMessages) {
await emit({ type: "message_start", message });
await emit({ type: "message_end", message });
}
await runLoop(currentContext, newMessages, config, signal, emit, streamFn ?? getDefaultStreamFn());
return newMessages;
终于读到我们开头提到的伪代码部分了,中间 内层循环的代码太多了我先折叠起来不看。先看外层循环:
有两个message的输入点:getSteeringMessages和 getFollowUpMessages
SteeringMessages俗称插话,是当agent正在运行的时候,我们在界面上又输入了query,这时候会在turn的执行边界插入这句query。
FollowUpMessages这个功能是我第一次见的,claude code上好像没有:使用followup()输入的内容,会在agent 上个任务执行完毕后加载,作为下一轮对话的query。(真的会有用户用这种功能嘛,不看agent回复的内容就直接定了下一轮query的输入。。)
最后再看explicitContinuation标记,如果true就再跑一轮,false就终止。 这个标记每轮都会被置为false,看起来continue真不容易呢,必须每轮都选择继续才会继续。
typescript
/**
* Main loop logic shared by agentLoop and agentLoopContinue.
*/
async function runLoop(
initialContext: AgentContext,
newMessages: AgentMessage[],
initialConfig: AgentLoopConfig,
signal: AbortSignal | undefined,
emit: AgentEventSink,
streamFunction: StreamFn,
): Promise<void> {
let currentContext = initialContext;
let config = initialConfig;
let lastCompletedTurn: PrepareNextTurnContext | undefined;
let explicitContinuation = false;
// Check for steering messages at start (user may have typed while waiting)
let pendingMessages: AgentMessage[] = (await config.getSteeringMessages?.()) || [];
// Outer loop: continues when queued follow-up messages arrive after agent would stop
while (true) {
let hasMoreToolCalls = true;
// Inner loop: process tool calls and steering messages
while (hasMoreToolCalls || pendingMessages.length > 0) {
let preparedMessages: AgentMessage[] = [];
//这一段太长了先隐藏不看
}
// Agent would stop here. Check for follow-up messages.
const followUpMessages = (await config.getFollowUpMessages?.()) || [];
if (followUpMessages.length > 0) {
// Set as pending so inner loop processes them
explicitContinuation = false;
pendingMessages = followUpMessages;
continue;
}
// No natural request was selected, so fulfill the continuation decision with one context-only turn.
if (explicitContinuation) {
explicitContinuation = false;
continue;
}
// No more messages, exit
break;
}
await emit({ type: "agent_end", messages: newMessages });
}
看内层循环:
lastCompletedTurn在第一轮是undefined ,从第二轮开始,在开始下一轮之前,会给上一轮的结果做一次快照,然后如果pendingmessage已经都执行了,就再查询一次SteeringMessages看看有没有新输入的query。 可以注意到getSteeringMessages的调用点在run开始前,turn开始前,turn结束后,这也印证了我们之前了解到的:SteeringMessages
在turn的执行边界插入这句query。 然后点进去细看又发现了一条细节:这个getSteeringMessages命名看起来是get多条插话,实际实现的默认配置是one-at-a-time的,也就是说每次get只会返回最老的一条插话内容。并且每一轮turn只会清空一次pendingMessages 。也就是说输入多条插话的时候,最快也得一轮turn插入一条。(也可配置成all)
typescript
this.steeringQueue = new PendingMessageQueue(runtimeOptions.steeringMode ?? "one-at-a-time");
getSteeringMessages: async () => {
if (skipInitialSteeringPoll) {
skipInitialSteeringPoll = false;
return [];
}
return this.steeringQueue.drain();
},
然后emit turn_start。此时我有一点疑惑,第一轮的时候不会进这个分支,怎么不报 turn_start的事件,然后超前翻原来是在函数外部initialMessages完成后就上报了。
然后又跑了一轮 declareToolChanges 对齐工具。可以看出 declareToolChanges和getSteeringMessages这些方法的调用还是非常频繁的,几乎每一个可能调用llm的过程前后都会调用这些方法来对齐状态。 长异步任务的处理果然还是很艰难的啊。
下一步到 prepareRequest,是调用llm前的最后一次检查了,这一步还可以设置model和reasoning
再往下 streamAssistantResponse 终于调用模型了,后面的逻辑和开头的伪代码直接对应上了:message直接往后追加,找到
toolCall执行,但是有一个例外:当message.stopReason ==="length"时(输出被token上限截断,工具参数可能被拦腰截断成非法 JSON,所以整批不执行、全部快速失败。)时就不调用工具快速失败了。 然后把toolResults也追加进message。
再往后就是单轮turn的最后一件事了:决策是否停止这一轮agent loop。但无论如何跑完decision这一轮turn就结束了。
decision没有缺省实现,缺省就会返回undefined------没有这一层判断。我们看看假如有会如何:
end:直接结束agent loop,上报agent_end事件。
continue:设置explicitContinuation = true,在没有pendingmessage和moretoolcalls的情况下续一轮turn
undefined:弃权,仍然按照 pendingmessage和moretoolcalls 来判定要不要内循环下一轮,在外循环按照explicitContinuation判定要不要再开一轮内循环。
typescript
while (hasMoreToolCalls || pendingMessages.length > 0) {
let preparedMessages: AgentMessage[] = [];
if (lastCompletedTurn) {
const nextTurnSnapshot = await config.prepareNextTurn?.(lastCompletedTurn);
if (nextTurnSnapshot) {
currentContext = nextTurnSnapshot.context ?? currentContext;
preparedMessages = nextTurnSnapshot.messages ?? [];
config = {
...config,
model: nextTurnSnapshot.model ?? config.model,
reasoning:
nextTurnSnapshot.thinkingLevel === undefined
? config.reasoning
: nextTurnSnapshot.thinkingLevel === "off"
? undefined
: nextTurnSnapshot.thinkingLevel,
};
}
// Preparation can be long-running (for example, compaction). Pick up steering
// queued while it ran. Only poll again if the earlier poll returned nothing;
// otherwise one-at-a-time mode would deliver two messages in this turn.
if (pendingMessages.length === 0) {
pendingMessages = (await config.getSteeringMessages?.()) || [];
}
await emit({ type: "turn_start" });
}
// Process prepared and queued messages before the next assistant response.
for (const message of declareToolChanges(currentContext, [...preparedMessages, ...pendingMessages])) {
await emit({ type: "message_start", message });
await emit({ type: "message_end", message });
currentContext.messages.push(message);
newMessages.push(message);
}
pendingMessages = [];
const requestUpdate = await config.prepareRequest?.(
{
context: currentContext,
model: config.model,
thinkingLevel: config.reasoning ?? "off",
},
signal,
);
if (requestUpdate) {
currentContext = requestUpdate.context ?? currentContext;
config = {
...config,
model: requestUpdate.model ?? config.model,
reasoning:
requestUpdate.thinkingLevel === undefined
? config.reasoning
: requestUpdate.thinkingLevel === "off"
? undefined
: requestUpdate.thinkingLevel,
};
}
// Stream assistant response
const message = await streamAssistantResponse(currentContext, config, signal, emit, streamFunction);
newMessages.push(message);
if (message.stopReason === "error" || message.stopReason === "aborted") {
lastCompletedTurn = {
message,
toolResults: [],
context: currentContext,
newMessages,
};
await config.finishTurn?.(lastCompletedTurn, signal);
await emit({ type: "turn_end", message, toolResults: [] });
await emit({ type: "agent_end", messages: newMessages });
return;
}
// Check for tool calls
const toolCalls = message.content.filter((c) => c.type === "toolCall");
const toolResults: ToolResultMessage[] = [];
hasMoreToolCalls = false;
if (toolCalls.length > 0) {
// A "length" stop means the output was cut off by the token limit, so
// every tool call in the message may carry truncated arguments. Fail
// them all instead of executing potentially borked calls.
const executedToolBatch =
message.stopReason === "length"
? await failToolCallsFromTruncatedMessage(toolCalls, emit)
: await executeToolCalls(currentContext, message, config, signal, emit);
toolResults.push(...executedToolBatch.messages);
hasMoreToolCalls = !executedToolBatch.terminate;
for (const result of toolResults) {
currentContext.messages.push(result);
newMessages.push(result);
}
}
lastCompletedTurn = {
message,
toolResults,
context: currentContext,
newMessages,
};
const decision = await config.finishTurn?.(lastCompletedTurn, signal);
await emit({ type: "turn_end", message, toolResults });
if (decision?.action === "end") {
await emit({ type: "agent_end", messages: newMessages });
return;
}
explicitContinuation = decision?.action === "continue";
pendingMessages = (await config.getSteeringMessages?.()) || [];
if (hasMoreToolCalls || pendingMessages.length > 0) {
explicitContinuation = false;
}
}
执行工具也点进去看了一眼:当config是串行,或者调用的工具有串行时,均改为全部工具串行执行。只有config允许异步且调用的工具全部是并行时,才会走并行。(好严格的判定,还以为能并行的工具跑并行,必须串行的工具串行呢)
typescript
/**
* Execute tool calls from an assistant message.
*/
async function executeToolCalls(
currentContext: AgentContext,
assistantMessage: AssistantMessage,
config: AgentLoopConfig,
signal: AbortSignal | undefined,
emit: AgentEventSink,
): Promise<ExecutedToolCallBatch> {
const toolCalls = assistantMessage.content.filter((c) => c.type === "toolCall");
const hasSequentialToolCall = toolCalls.some(
(tc) => currentContext.tools?.find((t) => t.name === tc.name)?.executionMode === "sequential",
);
if (config.toolExecution === "sequential" || hasSequentialToolCall) {
return executeToolCallsSequential(currentContext, assistantMessage, toolCalls, config, signal, emit);
}
return executeToolCallsParallel(currentContext, assistantMessage, toolCalls, config, signal, emit);
}