深度解析 tarko/agent 的 Agent 类UI-TARS 多模态 Agent 运行时的核心 API 使用指南【免费下载链接】UI-TARS-desktopThe Open-Source Multimodal AI Agent Stack: Connecting Cutting-Edge AI Models and Agent Infra项目地址: https://gitcode.com/GitHub_Trending/ui/UI-TARS-desktopAgent类是 UI-TARS 多模态 Agent 技术栈中tarko/agent位于仓库multimodal/tarko/agent的核心运行时组件它把 LLM 调用、工具注册执行、多模态上下文管理与事件流监控统一封装在一个事件驱动架构中。本指南以官方运行时 API 文档agent-api.md为主体骨架结合仓库内真实源码展开帮助你在构建自己的 GUI / 多模态智能体时掌握构造、运行、监控、取消与释放 Agent 的全部关键 API 与最佳实践。一、Agent 运行时是什么框架定位与架构速览Agent类不是一次性的函数封装而是一个可复用的多轮推理运行时。从源码注释可以清晰看到它的设计目标agent.ts多轮推理 Agent 循环multi-turn reasoning agent loop高度可定制易于构建更高层级的 Agent工具注册与执行多模态上下文感知与管理与多个 LLM Provider 通信事件流管理用于跟踪 Agent 循环状态。在类层次上AgentT继承自抽象基类BaseAgentTbase-agent.ts并实现了接口IAgentT。BaseAgent负责全部生命周期钩子如onLLMRequest、onBeforeToolCall、onPrepareRequest、onBeforeLoopTermination等与循环终止控制Agent则在其上实现工具管理器ToolManager、执行控制器AgentExecutionController、事件流处理器AgentEventStreamProcessor与 RunnerAgentRunner的装配。因此调用agent.run()后真正跑起来的是一套由 runner/loop-executor/tool-processor/llm-processor 组成的推理管线。二、实例化 Agent构造函数与 AgentOptions 全量配置new Agent(options?)创建 Agent 实例是使用它的第一步。构造函数接受一个可选的AgentOptions配置对象import { Agent } from tarko/agent; const agent new Agent({ instructions: You are a helpful assistant, tools: [myTool], model: { provider: openai, id: gpt-4 }, maxIterations: 10 });AgentOptions 字段详解AgentOptions在 agent-options.ts 中定义它由 9 个分组接口组合而成。下表汇总了每个配置项的语义、默认值及源码依据分组配置项说明默认值AgentBaseOptionsid唯一实例标识用于跟踪与日志tarko/agent见 agent.tsnameAgent 名称便于追踪Anonymousagent.tsinstructions系统提示词提供后完全替换默认提示词内置默认提示词见下AgentModelOptionsmodelLLM 模型设置含provider/id/displayName等运行时按需解析maxTokens单次请求最大 token 数未限制temperature采样温度越低越确定0.7agent.tstop_p核采样参数范围 0.0–1.0不设置则用模型默认thinking推理内容控制LLMReasoningOptions{ type: disabled }若传入非对象会抛Invalid thinking option错误AgentToolOptionstools注册给 Agent 的工具定义数组undefinedtool工具过滤配置include/exclude不过滤toolCallEngine工具调用引擎native/prompt_engineering/structured_outputs或自定义引擎构造器nativeAgentLoopOptionsmaxIterations推理循环最大迭代次数1000agent.tsAgentMemoryOptionscontext多模态上下文管理如maxImagesCountmaxImagesCount默认5agent.tseventStreamOptions事件流处理器配置—enableStreamingToolCallEvents是否流式输出工具调用构建过程事件falseinitialEvents从持久化存储恢复会话历史用的事件数组undefinedAgentMiscOptionslogLevel日志级别LogLevel开发INFO/ 生产WARNmetric是否启用指标采集TTFT、TTLT 等metric.enablefalseAgentWorkspaceOptionsworkspace涉及文件读写时的文件系统与命令执行作用域目录当前工作目录AgentSandboxOptionssandboxUrl工具沙箱 URL—默认指令instructions 缺省时来自 getDefaultPromptYou are an intelligent assistant that can use provided tools to answer user questions. Please use tools when needed to get information, dont make up answers. Provide concise and accurate responses.注意文档示例里的maxIterations: 10只是业务演示值框架默认上限是1000次迭代——现代 LLM 的长程 Agentic 任务能力允许更复杂的多步推理这正是源码注释中提高默认上限的原因。三、执行任务run() 的重载与流式 / 非流式模式run(input)/run(options)run是 Agent 的主入口执行完整的“LLM 推理 → 工具调用 → 再次推理”闭环直到产出最终答案或达到maxIterations。它有三个重载agent.ts// 简单文本输入非流式 const response await agent.run(What is the weather like?); // 对象选项 非流式input 可为多模态内容数组 const response await agent.run({ input: Analyze this image, model: gpt-4-vision-preview }); // 流式模式返回 AsyncIterableEvent const stream await agent.run({ input: Help me plan a trip, stream: true }); for await (const event of stream) { console.log(event); }三种签名的返回差异如下调用形式返回类型run(input: string)PromiseAssistantMessageEventrun(options: AgentRunNonStreamingOptions)PromiseAssistantMessageEventrun(options: AgentRunStreamingOptions)PromiseAsyncIterableEventAgentRunObjectOptions 字段执行选项在 agent-run-options.ts 中定义interface AgentRunObjectOptions { input: string | ChatCompletionContentPart[]; // 用户输入支持多模态内容部件 stream?: boolean; // 是否流式 sessionId?: string; // 会话标识缺省自动生成 model?: string; // 本次运行覆盖模型 provider?: string; // 本次运行覆盖 Provider toolCallEngine?: ToolCallEngineType; // 本次运行覆盖工具引擎 environmentInput?: EnvironmentInput; // 环境上下文以 environment_input 事件注入 abortSignal?: AbortSignal; // 取消信号由 Agent 内部自动注入 }从源码理解 run() 的行为细节对照 agent.ts 的实现有几个容易忽略的运行时语义并发保护如果 Agent 正在执行任务再次调用run()会抛出错误Agent is already executing a task. Complete or abort the current task before starting a new one.需要先abort()或等待本次运行结束。会话标识自动生成未传sessionId时按Date.now() 随机串生成。事件自动发报无论流式与否run()都会先发出user_message事件多模态输入会被标记随后发出agent_run_start携带sessionId、provider、model、modelDisplayName、agentName结束或出错时发出agent_run_end携带iterations、elapsedMs、status。agent_run_start中的选项会被sanitizeRunOptions清洗敏感字段abortSignal会被移除复杂多模态输入会被替换为占位串。环境上下文注入传入environmentInput时其content/description/metadata会打包成environment_input事件注入会话且不会算作 user 消息。初始化延迟执行首次run()前会先调用initialize()派生 Agent 可借此完成耗时的初始化工作。四、注册与筛选工具让 Agent 具备行动能力registerTool(tool)工具是 Agent 能力的载体registerTool底层调用ToolManager.registerTool以工具名为主键存储agent.ts。也可在构造函数里通过tools: [...]批量注册。一个标准的Tool定义包含name、description、JSON Schema 格式的schema和真正执行的functionimport { Tool } from tarko/agent; const weatherTool: Tool { name: get_weather, description: Get current weather for a location, schema: { type: object, properties: { location: { type: string, description: City name } }, required: [location] }, function: async (args) { const { location } args as { location: string }; return Weather in ${location}: Sunny, 25°C; } }; agent.registerTool(weatherTool);getTools()/getAvailableTools()getTools()同步返回注册的全部工具但会先经this.options.tool的过滤配置include/exclude先 include 后 exclude处理getAvailableTools()异步返回经过钩子修饰后真正可用的工具集——它会把getTools()的结果再交给onRetrieveTools生命周期钩子处理agent.ts。const availableTools await agent.getAvailableTools(); console.log(${availableTools.length} tools available for execution);需要说明的是源码注释提醒如果onRetrieveTools的实现依赖运行期状态getAvailableTools()的结果可能与run()实际使用的工具存在差异。此外base-agent.ts 提供了更推荐的onPrepareRequest钩子可在每轮请求发出前统一改写系统提示词与工具集。执行期钩子链在每一轮循环中工具执行还会经过onBeforeToolCall执行前拦截/改写参数→ 引擎执行 →onAfterToolCall改写结果→onToolCallError工具抛错时转换为可恢复返回值这些钩子全部定义在 base-agent.ts。五、直接调用 LLMcallLLM / getLLMClient / setCustomLLMClient在某些场景如单独做一次摘要、判断、分类无需走完整 Agent 循环可以直接调用当前 Agent 已选定的 LLM。callLLM(params, options?)它对“获取 LLM 客户端 当前模型”的通用模式做了封装自动把当前模型id合并进请求参数无需手动传model并在客户端或模型不可用时抛出清晰错误。同样有两个重载根据stream推断返回类型// 非流式调用 const response await agent.callLLM({ messages: [{ role: user, content: Hello }], temperature: 0.7 }); // 流式调用逐块返回 ChatCompletionChunk const stream await agent.callLLM({ messages: [{ role: user, content: Hello }], stream: true }); for await (const chunk of stream) { console.log(chunk.choices[0]?.delta?.content); }类型签名callLLM(params: OmitChatCompletionCreateParams, model { stream?: false }, options?: RequestOptions): PromiseChatCompletioncallLLM(params: OmitChatCompletionCreateParams, model { stream: true }, options?: RequestOptions): PromiseAsyncIterableChatCompletionChunkgetLLMClient()/setCustomLLMClient(client)getLLMClient()返回当前可用的 OpenAI 兼容客户端OpenAI | undefined。解析顺序agent.ts优先返回自定义客户端 → 其次复用 runner 上已创建的客户端 → 都没有但存在当前模型时即时创建并回填给 runner。setCustomLLMClient(client)用于测试或自定义实现例如指向兼容 OpenAI 协议的自建网关。调用后日志提示“Custom LLM client set, will ignore model parameters in run()”且该客户端会同步下发给 runner 的llmProcessor。import OpenAI from openai; const customClient new OpenAI({ apiKey: your-api-key, baseURL: https://custom-llm-endpoint.com }); agent.setCustomLLMClient(customClient);generateSummary(request)基于既有会话消息生成简短会话标题/摘要。底层agent.ts会追加一条系统指令“生成不超过 6 个词的标题”以temperature: 0.3、max_tokens: 25、JSON mode 调用 LLM解析 JSON 中的title字段const summary await agent.generateSummary({ messages: [ { role: user, content: What is machine learning? }, { role: assistant, content: Machine learning is... } ] }); console.log(Summary: ${summary.summary});返回PromiseSummaryResponse其中summary为生成的标题文本解析失败时回退Untitled Conversation并带上model与provider信息。注意源码注释中标注了 FIXME当前基于运行中的事件流生成摘要使用时需留意这一实现细节。六、事件流与可观测性getEventStream()Agent 的事件驱动本质体现在AgentEventStreamProcessor上。getEventStream()返回事件流管理器可订阅会话全过程的各类事件const eventStream agent.getEventStream(); eventStream.on(assistant_message, (event) { console.log(Assistant:, event.content); }); eventStream.on(tool_call, (event) { console.log(Calling tool: ${event.name}); });事件类型清单文档列出的核心事件如下它们在 agent-event-stream.ts 中有着更完整的定义事件触发时机事件负载要点user_message收到用户输入content可多模态assistant_messageAgent 生成回复content、toolCalls、finishReasontool_call工具执行开始工具名、参数tool_result工具执行完成结果system系统事件与错误—agent_run_start一次 run 开始sessionId、provider、model、agentNameagent_run_end一次 run 结束sessionId、iterations、elapsedMs、status在真实实现中事件分类更细还包括流式中间态assistant_streaming_message、assistant_streaming_thinking_message、assistant_streaming_tool_call思考类事件assistant_thinking_message规划类plan_start/plan_update/plan_finish环境上下文environment_input以及结构化终态final_answer/final_answer_streaming。所有事件统一携带id、type、timestamp基础字段便于序列化、持久化与回放。tarko/agent还提供了 Agent Snapshot 快照框架源码中的isReplaySnapshot/_setIsReplay()与此相关可据此重放历史会话。七、状态查询与生命周期管理status() / abort() / dispose()status()返回当前执行状态AgentStatus底层来自执行控制器const currentStatus agent.status(); console.log(Agent status: ${currentStatus});abort()中断当前运行中的任务。返回true表示确实中止了一次执行false表示当时没有可中止的任务agent.tsconst isAborted agent.abort(); if (isAborted) { console.log(Agent execution aborted); }实现上run()会从AgentExecutionController.beginExecution()拿到一个AbortSignal并注入执行上下文因此中止信号可以沿请求链路含generateSummary等直连 LLM 的调用传播被取消的请求会表现为AbortError。dispose()释放 Agent 占用的全部资源。基类dispose()base-agent.ts具备幂等保护重复调用直接忽略Agent 实现其onDispose()agent.ts做两件事先中止并收尾任何仍在运行的执行再清空事件流await agent.dispose(); console.log(Agent disposed successfully);getCurrentLoopIteration()/getCurrentModel()调试与状态观测还需要两个便捷方法const iteration agent.getCurrentLoopIteration(); // 1-based未运行时为 0 console.log(Currently on iteration ${iteration}); const model agent.getCurrentModel(); // AgentModel | undefined if (model) { console.log(Using ${model.provider}/${model.id}); }getCurrentModel()在源码中实际返回构造时解析出的AgentModel即 resolveModel 的结果可据此在运行前确认最终生效的 Provider / 模型。八、错误处理常见异常与捕获模式Agent 运行期间可能抛出多种异常官方文档给出了如下捕获模板try { const response await agent.run(Process this request); console.log(response.content); } catch (error) { if (error.name AbortError) { console.log(Request was cancelled); } else { console.error(Agent error:, error.message); } }常见错误场景归纳错误含义与触发点AbortError通过abort()或AbortSignal取消请求ModelErrorLLM Provider 或模型配置问题例如callLLM时模型未解析ToolError工具执行失败可通过onToolCallError钩子转换为可恢复值ValidationError输入或配置非法例如thinking传入非对象在构造期即抛错另外两类极易踩坑的运行时错误来自源码而非模型层并发执行错误run()未结束就再次调用和客户端不可用错误getLLMClient()/getCurrentModel()缺失时callLLM、generateSummary会抛出带明确指引信息的异常。九、完整实战装配一个带工具的数学计算 Agent下面整合全文 API给出一个可直接运行的完整示例继承并完善自官方文档的用例。通过事件流实时观测每一轮工具调用与助手回复异常与资源清理均由finally保障import { Agent, Tool } from tarko/agent; // 1. 定义工具 const calculatorTool: Tool { name: calculate, description: Perform mathematical calculations, schema: { type: object, properties: { expression: { type: string, description: Math expression to evaluate } }, required: [expression] }, function: async (args) { const { expression } args as { expression: string }; try { // 生产环境请替换为安全的数学求值器这里仅为演示 const result eval(expression); return Result: ${result}; } catch (error) { return Error: Invalid expression; } } }; // 2. 创建 Agent const agent new Agent({ instructions: You are a helpful math assistant. Use the calculator tool for computations., tools: [calculatorTool], model: { provider: openai, id: gpt-4 }, maxIterations: 5, temperature: 0.1, logLevel: 1 // Info level }); // 3. 订阅事件实时观测执行过程 const eventStream agent.getEventStream(); eventStream.on(tool_call, (event) { console.log([Tool] Calling ${event.name}:, event.args); }); eventStream.on(assistant_message, (event) { console.log([Assistant] ${event.content}); }); eventStream.on(agent_run_end, (event) { console.log([Run] finished in ${event.elapsedMs}ms, ${event.iterations} iterations); }); // 4. 执行并确保资源释放 async function main() { try { const response await agent.run(What is 15 * 23 7?); console.log(Final answer:, response.content); } catch (error) { if (error.name AbortError) { console.error(Request was cancelled); } else { console.error(Error:, error.message); } } finally { await agent.dispose(); } } main();十、最佳实践总结结合官方文档 Best Practices 与源码行为构建生产级 Agent 时建议遵循以下原则资源管理用完即调dispose()它具备幂等保护可安全地在finally中重复调用。错误处理所有run()/callLLM()调用包进 try-catch并优先识别AbortError以区分“用户取消”与“真异常”。工具设计保持工具职责单一、描述详实description 直接决定 LLM 是否会选中它JSON Schema 要完整required字段必不可少。上下文预算使用context.maxImagesCount限制对话历史中的图片数量默认 5超出部分会以保留语义的文本占位符替换避免多模态上下文撑爆模型窗口。流式优先长任务与需要实时反馈的交互场景优先使用stream: true逐条消费事件而非等待最终一次性结果。监控与观测订阅tool_call、tool_result、agent_run_end等事件用于日志与指标分析开启metric.enable可采集 TTFT / TTLT 等时序指标。并发约束Agent 实例默认不并发执行任务长时间运行的场景请设计任务队列或先abort()再发起新任务。长会话策略借助initialEvents可在重建 Agent 实例时从存储恢复事件历史generateSummary可为多轮会话生成短标题便于归档检索。延伸阅读Agent 生命周期钩子的完整说明见同目录姊妹文档 agent-hooks.mdonBeforeToolCall、onBeforeLoopTermination、onPrepareRequest等包级介绍与更多示例见 tarko/agent README 及其 examples 目录关注接口定义可阅读 agent-options.ts 与 agent-run-options.ts、事件类型全集见 agent-event-stream.ts多模态 GUI 场景的能力超集可参考同一框架中的GUIAgentgui-agent.ts。【免费下载链接】UI-TARS-desktopThe Open-Source Multimodal AI Agent Stack: Connecting Cutting-Edge AI Models and Agent Infra项目地址: https://gitcode.com/GitHub_Trending/ui/UI-TARS-desktop创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考