如何使用TypeScript从零开始构建一个AI代理程序

许多关于AI代理的教程都是从语言模型开始讲起，为它提供一些工具，然后让它运行循环直到产生答案。这样的做法确实足以展示这些工具的使用方法，但却没有回答那些有趣的工程学问题。

当某个工具出现故障时会发生什么？谁来验证这些操作的结果？是什么机制能防止代理无限期地运行、执行不安全的命令，或者耗尽其上下文信息？又如何在不依赖模型不可预测的响应的情况下测试这些功能呢？

这些职责都属于代理框架——也就是位于语言模型与其所运行的环境之间的那层软件。

在本次教程中，我们将使用TypeScript来构建一个小型且与具体工具提供商无关的代理框架，并以编码代理作为示例进行讲解。我们会从基本的执行循环开始，逐步添加工具验证、工作区隔离、执行时间限制、上下文管理、可观测性功能以及确定性故障测试等功能。

我们将涵盖的内容

• 先决条件

• 1. 构建基本的代理执行循环

  • 不使用真实模型进行测试

• 2. 在执行前验证工具调用

  • 具有明确契约的注册系统

  • 并非所有错误都具有相同的含义

• 3. 为代理提供工具，但不赋予其完整的计算能力

  • 将文件操作限制在特定工作区内

  • 让模型自行选择命令，而非人为设计

• 4. 对执行过程设置限制

  • 分别统计执行次数和工具调用次数

  • 传播取消操作和截止时间信息

  • 在不等待真实故障发生的情况下测试这些限制

• 5. 控制上下文信息的范围

  • 限定工具的输出范围及模型记录的历史数据

  • 不要将工具调用结果与其执行结果分开处理

• 6. 使代理的执行过程可被观察

  • 在执行的边界处生成事件信号

  • 在不创建模型的情况下记录其使用情况

• 7. 不仅要测试成功路径，还要测试失败路径

  • 在信任模型响应之前先对其进行验证

  • 将被拒绝的批次从记录中剔除

  • 使用可复现的变体进行测试

• 下一步该做什么：连接真实的语言模型

先决条件

熟悉TypeScript以及对AI代理有基本了解会很有帮助。我们将使用Node.js 24、TypeScript及其内置的测试工具，而且这些技术的依赖关系非常少。

完整的实现代码可以在配套仓库中找到：agent-harness-from-scratch。每个开发阶段都对应一个Git标签，因此你可以跟随项目的发展进程进行学习，而不需要从最终版本开始入手。

1. 构建基本代理循环

若要跟随示例进行操作，请先查看初始阶段的代码：

git clone https://github.com/gkoos/agent-harness-from-scratch.git
cd agent-harness-from-scratch
git switch --detach 01-model-loop
npm ci
npm run typecheck
npm test
npm run demo

“分离式检出”功能能让你直接进入当前讨论的代码版本，而不会影响到任何分支。当你需要进入下一个开发阶段时，只需切换到对应的Git标签即可。请确保你的系统中已经安装了Node.js 24和npm。

最重要的架构设计原则是：模型负责提出行动建议，而代理程序负责执行这些行动。当模型请求某个工具来执行某项任务时，它实际上并没有真正执行任何操作；它只是生成了一个包含工具名称及参数的结构化请求。代理程序需要解析这个请求，调用相应的功能模块，并将结果返回给模型。

这种交互过程如下图所示：

我们首先会在src/core/types.ts文件中定义相关类型。

export type ToolCall = { id: string; name: string; arguments: unknown };

export type Message =
  | { role: 'user'; content: string }
  | { role: 'assistant'; content: string; toolCalls?: ToolCall[] }
  | { role: 'tool'; callId: string; content: string; isError: boolean };

export interface ToolDefinition {
  name: string;
  description: string;
  parameters: Record>; // 用于模型的JSON结构定义
}

export interface Tool extends ToolDefinition {
  execute(argumentsValue: unknown, signal: AbortSignal): Promise;
}

export interface Model {
  generate(input: {
    messages: readonly Message[];
    tools: readonly ToolDefinition[];
    signal: AbortSignal;
  }) : Promise<{ content: string; toolCalls?: ToolCall[] }>;
}

export type AgentResult = {
  status: 'completed' | 'step_limit' | 'aborted';
  answer?: string;
  messages: Message[];
  steps: number;
};

Model接口刻意没有包含任何与OpenAI、Anthropic或其他任何提供商相关的特定内容。供应商适配器可以在不改变整个框架结构的情况下，将其API与这些类型的接口进行转换。

需要注意的是，工具参数被定义为未知类型，而不是任意类型。模型生成的数据属于不可信的输入信息，在下一节执行之前，我们需要对这些数据进行检查和验证。

src/core/agent.ts中定义的代理循环遵循以下简单的流程：

1. 将对话内容以及可用的工具定义发送给模型。

2. 将模型的响应添加到对话序列中。

3. 如果模型请求使用某些工具，就执行这些工具并将它们的结果添加到对话中。

4. 重复这个过程，直到模型给出最终答案，或者整个框架达到预定的步骤限制。

以下是src/core/agent.ts中完整的代理循环实现。模型接收工具定义，而整个执行框架则负责处理这些工具的具体实现逻辑：

import type { AgentResult, Message, Model, Tool } from './types.ts';

export async function runAgent(options: {
  model: Model;
  tools: readonly Tool[];
  prompt: string;
  maxSteps?: number;
  signal?: AbortSignal;
}): Promise<AgentResult>> {
  const { model, tools, prompt, maxSteps = 10 } = options;
  if (!Number.isSafeInteger(maxSteps) || maxSteps < 1) {
    throw new RangeError('maxSteps必须是一个正的安全整数');
  }
  const signal = options.signal ?? new AbortController().signal;
  const messages: Message[] = [{ role: 'user', content: prompt }];
  const registry = new Map(tools.map/tool => [tool.name, tool]));
  if (registry.size !== tools.length) throw new Error('存在重复的工具名称');
  const definitions = tools.map(({ name, description, parameters }) =>> ({ name, description, parameters };

  for (let step = 0; step < maxSteps; step++) {
    if (signal.aborted) return { status: 'aborted', messages, steps: step };
    let response;
    try {
      response = await model.generate({ messages: [...messages], tools: definitions, signal });
    } catch (error) {
      if (signal.aborted) return { status: 'aborted', messages, steps: step };
      throw error;
    }
    if (signal.aborted) return { status: 'aborted', messages, steps: step };
    const calls = response.toolCalls ?? [];
    messages.push({ role: 'assistant', content: response.content, ...(calls.length ? { toolCalls: calls } : {}) });
    if (!calls.length) return { status: 'completed', answer: response.content, messages, steps: step + 1 };

    for (const call of calls) {
      if (signal.aborted) return { status: 'aborted', messages, steps: step + 1 };
      const tool = registry.get(call.name);
      if (!tool) {
        messages.push({ role: 'tool', callId: call.id, content: `未知工具：${call.name}`, isError: true });
        continue;
      }
      try {
        const result = await tool.execute.callarguments, signal);
        if (signal.aborted) return { status: 'aborted', messages, steps: step + 1 };
        messages.push({ role: 'tool', callId: call.id, content: JSON.stringify(result) ?? 'null', isError: false });
      } catch (error) {
        if (signal.aborted) return { status: 'aborted', messages, steps: step + 1 };
        messages.push({
          role: 'tool', callId: call.id,
          content: error instanceof Error ? error.message : String(error),
          isError: true
        });
      }
    }
  }
  return { status: 'step_limit', messages, steps: maxSteps };
}

无需真实模型的测试

// src/models/fake.ts
import type { Model } from '../core/types.ts';

export function scriptedModel(
  responses: Array<Awaited<ReturnType<Model['generate']>>>>
): Model {
  let index = 0;
  return {
    async generate() {
      const response = responses[index++];
      if (!response) throw new Error('Scripted model exhausted');
      return response;
    }
  };
}

import { test } from 'node:test';
import assert from 'node:assert/strict';
import { runAgent } from '../src/core/agent.ts';
import { scriptedModel } from '../src/models/fake.ts';

test('执行工具并返回最终答案', async () => {
  const result = await runAgent({
    prompt: 'Say hello',
    tools: [
      {
        name: 'hello', description: 'Return a greeting',
        parameters: { type: 'object' },
        async execute() { return 'Hello'; }
      },
    ],
    model: scriptedModel([
      { content: '', toolCalls: [{ id: '1', name: 'hello', arguments: {} }] },
      { content: 'Done' }
    ])
  });
  assert.equal(result.status, 'completed');
  assert_equal(result.answer, 'Done');
  assert.deepEqual(result.messages[2], {
    role: 'tool', callId: '1', content: '"Hello"', isError: false
  });
});

2. 在执行工具调用之前对其进行验证

在最初的实现中，模型会通过名称来请求相应的工具，然后直接将参数传递给工具的实现函数。这种做法适用于演示用途，但需要注意的是，工具描述实际上只是向模型发出的一种请求，并不能保证模型会返回有效的参数。

关于这一部分的内容，请参考配套代码库中的第二个里程碑：

git switch --detach 02-tool-dispatch

这个操作会添加src/core/registry.ts文件，该文件负责处理工具的注册以及运行时参数的验证工作；同时，它还会修改src/core/agent.ts文件中定义的错误处理机制。

import type { Tool, ToolDefinition } from './types.ts';

export class ToolRegistry {
  private readonly tools = new Map;
  constructor(tools: readonly Tool[]) {
    for (const tool of tools) {
      if (!/^[a-zA-Z][a-zA-Z0-9_-]*$/.test.tool.name)) throw new Error(`无效的工具名称：${tool.name}`);
      if (this.tools.has/tool.name)) throw new Error(`重复的工具名称：${tool.name}`);
      this.tools.set-tool.name, tool);
    }
  }
  definitions(): ToolDefinition[] {
    return [...this.tools.values()).map(({ name, description, parameters }) => ({ name, description, parameters }));
  }
  get(name: string): Tool | undefined { return this.tools.get(name); }
}

const tool = registry.get(call.name);
if (!tool) {
  messages.push({
    role: 'tool', callId: call.id,
    content: `未知的工具：${call.name}`, isError: true
  });
  continue;
}

const validationErrors = validate(call.arguments, tool.parameters);
if (validationErrors.length) {
  messages.push({
    role: 'tool', callId: call.id,
    content: `参数无效：${validationErrors.join('; ')}`,
    isError: true
  });
  continue;
}

export function validate(value: unknown, schema: Record, path = '$'): string[] {
  const errors: string[] = [];
  const type = schema.type;
  if (typeof type !== 'string') return [`${path}: schema必须明确指定类型`];
  const matches = type === 'object' ? value !== null && typeof value === 'object' && !Array.isArray(value)
    : type === 'array' ? Array.isArray(value)
    : type === 'integer' ? typeof value === 'number' && Number.isInteger(value)
    : type === 'number' ? typeof value === 'number' && Number.isFinite(value)
    : type === 'null' ? value === null
    : type === 'string' || type === 'boolean' ? typeof value === type : false;
  if (!matches) return [`${path}: 预期值为${type}`];
  if (Array.isArray(schema.enum) && !schema(enum.some(item => Object.is(item, value))) {
    errors.push(`${path}: 这个值是不被允许的`);
  }
  if (type === 'object') {
    const obj = value as Record;
    const properties = (schema.properties ?? {}) as Record>;
    for (const key of (schema.required ?? []) as string[]) {
      if (!Object.hasOwn(obj, key)) errors.push(`${path}.${key}: 这个属性是必填的`);
    }
    for (const [key, item] of Object.entries(obj)) {
      if (Object.hasOwn(properties, key)) errors.push(...validate(item, properties[key], `${path}.${key}`));
      else if (schema.additionalProperties === false) errors.push(`${path}.${key}: 不存在这个属性`);
    }
  }
  if (type === 'array' && schema.items && typeof schemaitems === 'object') {
    (value as unknown[]).forEach((item, index) => {
      errors.push(...validate(
        item, schema.items as Record, `${path}[${index}]`
      ));
    });
  }
  return errors;
}

if (signal.aborted) return { status: 'aborted', messages, steps: step };
return {
  status: 'model_error', messages, steps: step,
  error: error instanceof Error ? error.message : String(error)
};

git switch --detach 03-workspace-tools

const workspace = await Workspace.open('/path/to/project');
const tools = workspaceToolsworkspace);

private lexical(path: string): string {
    if (!path || isAbsolute(path)) throw new Error('期望提供一个相对的工作区路径');
    const full = resolve(this.root, path);
    const rel = relative(this.root, full);
    if (!rel || rel === '..' || rel.startsWith(`..${process.platform === 'win32' ? '\\' : '/'}`) || isAbsolute(rel)) {
      throw new Error('路径位于工作区之外，或者指向工作区的根目录');
    }
    return full;
  }

  /** 在所有组件中都会拒绝处理符号链接，而不仅仅是最终要被读取的文件。 */
  private async check(path: string, allowMissingFinal: boolean): Promise {
    const full = this.lexical(path);
    const rel = relative(this.root, full);
    const parts = rel.split(/[\\/]/);
    let current = this.root;
    for (let i = 0; i < parts.length; i++) {
      current = resolve(current, parts[i]!);
      try {
        const stat = await lstat(current);
        if (stat.isSymbolicLink()) throw new Error('不允许使用符号链接');
        if (i < parts.length - 1 && !stat.isDirectory()) throw new Error('父目录不是一个目录');
      } catch (error) {
        if (allowMissingFinal && i === parts.length - 1 && (error as NodeJS ErrnoException).code === 'ENOENT') break;
        throw error;
      }
    }
    return full;
  }

const tool = commandTool(projectRoot, {
  test: {
    executable: process.execPath,
    args: ['--test', 'tests/example.test.js']
  }
});

signal.throwIfAborted();
const name = (value as { command: string }).command;
if (!Object.hasOwn(presets, name)) throw new Error('不允许使用该命令');
const preset = presets[name]!;
const timeout = preset.timeoutMs ?? 10_000;
if (!Number.isSafeInteger(timeout) || timeout < 1) {
  throw new Error('超时时间无效');
}

// 在用于获取命令结果的Promise内部：
const child = spawn(preset.executable, [...preset.args], {
  cwd, shell: false, signal, windowsHide: true,
  stdio: ['ignore', 'pipe', 'pipe']
});
const timer = setTimeout(() => child.kill(), timeout);

git switch --detach 04-execution-limits

const result = await runAgent({
  model,
  tools,
  prompt: '检查该项目',
  maxSteps: 10,
  maxToolCalls: 30,
  timeoutMs: 15_000
});

if (calls.length > maxToolCalls - toolCalls) {
  return { status: 'tool_limit', messages, steps, toolCalls };
}

const controller = new AbortController();
let timedOut = false;
const onAbort = () => controller.abort(options.signal?.reason);
if (options.signal?.aborted) onAbort();
else options.signal?.addEventListener('abort', onAbort, { once: true });
const timer = timeoutMs === undefined ? undefined : setTimeout(() => {
  timedOut = true;
  controller.abort(new Error('代理程序的截止时间已到'));
}, timeoutMs);
const signal = controller.signal;

try {
  // 执行逻辑放在这里，会使用controller.signal。
} finally {
  if (timer !== undefined) clearTimeout(timer);
  options.signal?.removeEventListener('abort', onAbort);
}

git switch --detach 05-context

相关的文件位于src/core/context.ts、src/core/agent.ts以及tests/context.test.ts中。

新的context配置选项设置了两个独立的限制：

const result = await runAgent({
  prompt: '检查该项目',
  model,
  tools,
  context: {
    maxContextChars: 32_000,
    maxToolResultChars: 8_000
  }
});

maxToolResultChars这个限制确保了每个工具产生的结果在被纳入对话记录之前，其长度不会超过规定的上限。如果结果超过了这个限制，那么就会只保留结果的开始和结束部分，在中间添加一个省略标记；被舍弃的部分之后将无法被访问，甚至会在result.messages中也无法看到。

为了处理这种截断操作，代码中专门设计了一个辅助函数：boundToolResult，它会在结果字符串的前后分别保留规定的字符数，然后删除中间的多余部分：

export function boundToolResult(content: string, limit: number): string {
  if (content.length <= limit) return content;
  const marker = `\n...[${content.length - limit} or more characters omitted]...\n`;
  if (marker.length >= limit) return marker.slice(0, limit);
  const remaining = limit - marker.length;
  const front = Math.ceil(remaining / 2);
  const back = Math.floor(remaining / 2);
  return content.slice(0, front) + marker + (back ? content.slice(-back) : '');
}

在记录成功结果和错误信息时，请使用以下代码：content: boundToolResult(content, context.maxToolResultChars)。这种简洁的处理方式能够有效应对长度为零的情况，因此slice(-0)不会意外地保留全部结果。

maxContextChars用于限制传递给模型的序列化消息数组的长度。虽然该系统会在返回的对话记录中保留较旧的消息，但selectContext()只会发送初始的用户请求以及尽可能多的最新交互记录。未被包含在其中的历史信息，在当前交互环节中是无法被模型获取到的。

这里所指的是字符长度限制，而非令牌数量的限制。这些限制是针对JavaScript字符串在经过JSON序列化后的实际长度而言的，其中不包括工具定义内容以及特定提供者添加的额外数据。真正的提供者适配器需要能够考虑令牌的数量，并为响应结果预留足够的空间。

不要将工具调用与其结果分开处理

对对话记录进行筛选并删除最旧的消息并不那么简单。助手的回复可能会涉及多个工具，每个工具都通过一个唯一的调用ID来标识。如果只发送其中部分工具的结果，就会导致对话内容无效或产生误导。

因此，selectContext()会将助手发出的消息以及该批次中的所有结果视为一个不可分割的整体进行处理：要么全部包含在内，要么全部忽略。同时，该函数也会拒绝那些孤立存在的结果或不完整的批次，而不会生成不一致的对话上下文。

以下是来自src/core/context.ts的selectContext()函数的实现代码，其中使用了第1节中定义的Message类型。第一个循环用于验证并整理对话记录；第二个循环则会从后往前遍历所有批次，直到达到预定的字符长度限制：

import type { Message } from './types.ts';

const size = (messages: readonly Message[]) => JSON.stringify(messages).length;

export function selectContext(messages: readonly Message[], maxChars: number): Message[] {
  if (!Number.isSafeInteger(maxChars) || maxChars < 1) {
    throw new RangeError('maxContextChars必须是一个正的安全整数');
  }
  if (!messages.length) return [];
  const groups: Message[][] = [];
  for (let i = 0; i < messages.length;) {
    const message = messages[i]!;
    if (message.role === 'assistant' && message.toolCalls?.length > 0) {
      const ids = new Set(message/toolCalls.map(call => call.id));
      if (ids.size != message.toolCalls.length) throw new Error('助手环节中存在重复的工具调用ID');
      const group: Message[] = [message];
      i++;
      while (i < messages.length && messages[i].role === 'tool') {
        const result = messages[i]!;
        if (result.role === 'tool' && !ids.delete(result.callId)) throw new Error('存在孤立或重复的工具结果');
        group.push(result);
        i++;
      }
      if (ids.size == 0) throw new Error('工具结果批次不完整');
      groups.push(group);
    } else {
      if (message.role === 'tool') throw new Error('工具结果孤立存在');
      groups.push([message]);
      i++;
    }
  }
  const first = groups[0]!;
  if (first[0].role !== 'user') throw new Error('对话必须以用户消息开始');
  const recent: Message[][] = [];
  for (let i = groups.length - 1; i >= 1; i--) {
    const group = groups[i]!;
    const next = [...first, ...[group, ...recent].flat()];
    if (size(next) > maxChars) {
      if (recent.length === 0) throw new Error('当前对话上下文的字符长度限制不足以容纳最新的一条消息');
      break;
    }
    recent.unshift(group);
  }
  const selected = [...first, ...recent.flat()];
  if (size(selected) > maxChars) throw new Error('所需消息的总量超出了对话上下文的字符长度限制');
  return selected;
}

在每次调用模型之前，应使用selectContext(messages, context.maxContextChars)作为模型的messages输入参数。如果初始提示信息或最近需要的数据量超出了上下文的容量限制，选择器会抛出异常，此时测试框架会返回context_limit。这种处理属于执行层面的决策，并非工具本身出现的错误，模型也无法自行恢复。

确定性测试主要验证批量数据处理、孤立数据检测、输出截断以及模型相关功能的正确性。这些测试不仅确认上下文容量是否已减少，还会确保缩减后的上下文仍能完整地反映对话内容。接下来，我们将让这些执行过程中的决策结果变得可见。

6. 使代理的执行过程可见

一个代理在执行任务的过程中可能会做出一些意料之外的操作：例如重试失败的请求、进行不必要的模型调用，或者将大部分时间消耗在某个特定的工具上。仅凭最终的结果我们无法了解其中的具体情况。因此，我们需要记录执行过程中的各种事件，但同时不能让整个测试框架变成一个单纯的日志记录系统。

请查看配套仓库中的这一里程碑内容：

git switch --detach 06-observability

相关实现代码位于src/core/events.ts文件中，而集成逻辑则在src/core/agent.ts文件中。

在执行边界处触发事件

我们在runAgent方法中添加了一个可选的onEvent回调函数。测试框架会在模型被调用时发出model_start和model_end事件，在工具被调度时发出tool_start和tool_end事件；当模型操作失败时，会触发model_error事件；而当整个执行过程结束时，则会发出run_end事件。

每个事件都会包含运行ID、递增的序列号以及时间戳。模型和工具的完成事件还会报告其执行所花费的时间，这些时间是通过单调计时器来测量的。这些信息足以帮助我们重建操作顺序，并识别出那些执行速度较慢的操作。

const events: AgentEvent[] = [];

const result = await runAgent({
  prompt: 'Inspect the project',
  model,
  tools,
  onEvent: event => events.push(event),
});

console.log(result.runId, events);

请从src/core/events.ts文件中导入AgentEvent类型。这个回调函数是可选的：那些不需要监控执行过程的代码可以省略它。

有一个需要注意的地方：监控功能绝不能干扰执行的正常进行。事件监听器中的异常不应该导致原本成功的操作失败。事件发射器会捕获这些异常，并可以通过onObserverError函数选择性地报告它们，不过这个处理机制中的错误也会被忽略掉。需要注意的是，回调函数是同步执行的，因此那些执行速度较慢的监听器仍然会延缓整个代理程序的执行速度。

const enriched = {
  ...event, runId, sequence: ++sequence,
  timestamp: new Date().toISOString()
};
try {
  options.onEvent?.(enriched);
} catch (error) {
  try { options.onObserverError?.(error); }
  catch { /* 观察器失败不会影响运行结果。 */
}

在模型或工具的边界处，在执行之前记录`const start = performance.now()`，在执行之后再记录`durationMs: performance.now() - start`。一个共享的`finish()`辅助函数会在返回每个终端结果之前发送`run_end`信号，因此即使程序提前结束，这些数据也能被正确记录下来。

在没有重新设计模型的情况下记录其使用情况

我们还可以在模型响应中添加由提供者报告的令牌使用情况：

git switch --detach 07-testing

import type { Model, ToolCall } from './types.ts';

/**
* 在接受模型返回的结果或执行任何后续操作之前，先验证其格式是否正确。
*/
export function validateModelResponse(value: unknown): asserts value is Awaited>&>> {
  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
    throw new TypeError('模型返回的结果必须是一个对象');
  }
  const response = value as Record;
  if (typeof response.content !== 'string') throw new TypeError('模型返回的内容必须是字符串类型');
  if (response/toolCalls === undefined) return;
  if (!Array.isArray(response.toolCalls)) throw new TypeError('模型中的工具调用信息必须是一个数组');
  const ids = new Set();
  for (const call of response-toolCalls as unknown[]) {
    if (call === null || typeof call !== 'object' || Array.isArray(call)) {
      throw new TypeError('工具调用信息必须是一个对象');
    }
    const item = call as Partial;
    if (typeof item.id !== 'string' || !item.id.trim()) throw new TypeError('工具调用的ID必须是非空字符串');
    if (typeof item.name !== 'string' || !item.name.trim()) {
      throw new TypeError('工具调用的名称必须是非空字符串');
    }
    if (!Object.hasOwn(item, 'arguments')) throw new TypeError('工具调用所需的参数缺失');
    if (ids.has(item.id)) throw new TypeError(`重复的工具调用ID：${item.id}`);
    ids.add(item.id);
  }
}

if (calls.length > maxToolCalls - toolCalls) {
  return finish('tool_limit');
}
messages.push({
  role: 'assistant',
  content: response.content,
  ...(calls.length ? { toolCalls: calls } :{})
});

import { test } from 'node:test';
import assert from 'node:assert/strict';
import { runAgent } from '../src/core/agent.ts';
import { scriptedModel } from '../src/models/fake.ts';
import type { Tool } from '../src/core/types.ts';

const noop: Tool = {
  name: 'noop', description: '返回一个固定的结果',
  parameters: { type: 'object' },
  async execute() { return 'ok'; }
};
const call = (id: string) => ({ id, name: 'noop', arguments: {} });

test('seeded batches respect tool budgets', async () => {
  let seed = 0x12345678;
  const next = () => {
    seed ^= seed << 13;
    seed ^= seed >>> 17;
    seed ^= seed << 5;
    return seed >>> 0;
  };

  for (let i = 0; i < 150; i++) {
    const limit = next() % 9;
    const batch = next() % 13;
    let executed = 0;
    const result = await runAgent({
      prompt: 'test', maxToolCalls: limit,
      tools: [
        ...noop,
        async execute() { executed++; return 'ok'; }
      ],
      model: scriptedModel([
        {
          content: '',
          toolCalls: Array.from({ length: batch }, (_, j) => call(`call-${j}`))
        },
        { content: 'done' }
      ])
    });

    const admitted = batch <= limit;
    assert.equal(executed, admitted ? batch : 0, `case ${i}`);
    assert_equal(result.toolCalls, admitted ? batch : 0, `case ${i}`);
    assert.equal(
      result.status, admitted ? 'completed' : 'tool_limit', `case ${i}`
    );
    if (!admitted) {
      assert.deepEqual(result.messages, [{ role: 'user', content: 'test' }]);
    }
  }
});

test('工具异常是否仍然属于可恢复的错误', async () => {
  let executed = 0;
  for (let i = 0; i < 60; i++) {
    const result = await runAgent({
      prompt: 'test',
      tools: [
        { ...noop, async execute() => executed++; throw new Error(`failure ${i}`) },
      ],
      model: scriptedModel([
        { content: '', toolCalls: [call('1')] },
        { content: 'recovered' }
      ])
    });
    assert.equal(result.status, 'completed');
    assert_equal(result.answer, 'recovered');
    assert.ok(result.messages.some(message => {
      message.role === 'tool' && message.isError && message.content === `failure ${i}`;
    }));
  }
  assert.equal(executed, 60);
});

// src/models/openai.ts
import OpenAI from 'openai';
import type { Model } from '../core/types.ts';

export function openAIModel(client: OpenAI): Model {
  return {
    async generate({ messages, tools, signal }) {
      const response = await client.responses.create(
        {
          model: 'YOUR_MODEL',
          input: toOpenAIInput(messages),
          tools: toOpenAITools(tools),
        },
        { signal }
      );

      return {
        content: extractText(response),
        toolCalls: extractToolCalls(response),
        usage: extractUsage(response),
      };
    },
  };
}