Electric Agents 配置指南：使用 ctx.useAgent() 构建与运行 LLM Agent

Electric Agents 配置指南使用 ctx.useAgent() 构建与运行 LLM Agent【免费下载链接】electricThe agent platform built on sync.项目地址: https://gitcode.com/GitHub_Trending/el/electric在 Electric Agents构建于 sync 之上的 Agent 平台中实体Entity的 handler 通过ctx.useAgent()完成 LLM Agent 的配置与启动配置系统提示词、模型、工具与测试响应随后调用ctx.agent.run()驱动完整的 Agent 循环直到所有工具调用被解析、最终文本响应被产出。本文以 configuring-the-agent.md 为核心结合electric-ax/agents-runtime的源码实现系统讲解AgentConfig的每个字段、ctx.electricTools、AgentHandle、模型解析、超时重试以及免 LLM 调用的测试方案帮助你写出可运行、可测试、可上生产的 Agent handler。AgentConfigAgent 的完整配置对象ctx.useAgent(config: AgentConfig)接收一个配置对象其中定义了 Agent 循环的全部关键要素。接口定义位于 packages/agents-runtime/src/types.ts完整形态如下interface AgentConfig { systemPrompt: string model: string | Modelany provider?: Provider tools: AgentTool[] streamFn?: StreamFn getApiKey?: (provider: string) Promisestring | undefined | string | undefined onPayload?: SimpleStreamOptions[onPayload] onStepEnd?: (stats: { input: number uncachedInput: number output: number }) void modelTimeoutMs?: number modelMaxRetries?: number testResponses?: string[] | TestResponseFn }各字段的作用与必填性如下字段必填说明systemPrompt是传给 LLM 的系统提示词在每一轮模型调用中生效model是模型标识字符串如claude-sonnet-4-6或已解析的Model对象provider否model为字符串时使用的 pi-ai provider默认anthropictools是提供给 Agent 的工具数组。当运行时宿主提供运行时级工具时展开ctx.electricToolsstreamFn否透传给底层 Agent 的可选流式回调getApiKey否可选的 API Key 解析函数透传到模型层onPayload否模型层原始流式 payload 的可选回调onStepEnd否每个模型步骤结束后回调携带 provider 报告的 token 计数modelTimeoutMs否单次模型调用的超时时间单位为毫秒modelMaxRetries否模型调用的最大重试次数testResponses否测试用的 mock 响应设置后不再发起真实 LLM 调用源码中的额外字段值得注意运行时源码中的AgentConfigtypes.ts还暴露了三个原文档表格之外的可选字段它们会通过 pi-adapter.ts 透传到模型层reasoning?: SimpleStreamOptions[reasoning]——推理模式配置如让模型展示思考过程thinkingBudgets?: SimpleStreamOptions[thinkingBudgets]——推理 token 预算summarizeComplete?: SummarizeCompleteFn——上下文压缩compaction时使用的模型调用钩子默认复用 pi-ai 的completeSimple即对话模型测试可注入、后续也可将压缩路由到其他模型。onStepEnd 的 token 统计语义onStepEnd回调的三个数字来自 provider 报告的用量源码注释types.ts给出了精确语义input本次完整提示体积含 prompt-cache 的读写即 meta 行展示的数值uncachedInput仅本次步骤新增的输入新 token 缓存写入排除缓存命中output本次步骤的输出 token。预算核算应使用uncachedInput output这样在缓存命中的热轮次不会把整个会话反复计入。基础用法最小可运行的 Agent handler在 handler 内调用ctx.useAgent()完成 LLM 配置再调用ctx.agent.run()执行async handler(ctx) { ctx.useAgent({ systemPrompt: You are a helpful assistant., model: claude-sonnet-4-6, tools: [...ctx.electricTools], }) await ctx.agent.run() }useAgent返回一个AgentHandle同时也会设置ctx.agent两个引用完全等价。handler 每次被唤醒时都会重新执行这段配置逻辑因此你完全可以在每次 wake 时根据唤醒类型、事件载荷动态调整 systemPrompt、tools 等参数。若想精确控制进入 Agent 上下文窗口的内容token 预算、缓存层级、外部来源可以将ctx.useContext()与useAgent搭配使用详见 Context composition。ctx.electricTools运行时提供的工具ctx.electricTools是运行时提供的工具数组。它可能为空也可能包含宿主级工具例如调度管理类工具。当你希望 LLM Agent 能调用这些运行时级工具时把它展开进tools数组tools: [...ctx.electricTools, myCustomTool, anotherTool]官方建议将ctx.electricTools放在自定义工具之前展开以保证宿主提供的基础工具保持预期顺序参见 defining-tools.md。需要强调的是handler 级的协调 API如ctx.spawn、ctx.observe、ctx.send始终可用它们定义在HandlerContext上types.ts与是否把ctx.electricTools传给 LLM 无关。是否将运行时工具暴露给模型只影响模型自主调用它们的能力。ctx.agent.run()执行 Agent 循环run()会一直阻塞直到 LLM 结束——即所有工具调用被解析、最终文本响应被产出const result await ctx.agent.run()源码实现位于 context-factory.ts每次运行会先通过getTriggerMessageText从 wake 事件inbox 消息、cron 载荷或 webhook 源唤醒解析触发消息再把它作为 Agent 的输入随后通过composeToolsWithProviders组合工具、通过 pi-adapter 创建底层 Agent 实例并运行。返回的AgentRunResult结构如下type AgentRunResult { result?: unknown writes: ChangeEvent[] toolCalls: Array{ name: string; args: unknown; result: unknown } usage: { tokens: number; duration: number } }字段说明result底层 Agent 适配器返回的可选最终结果writes目前以空数组占位返回toolCalls目前以空数组占位返回usage目前返回{ tokens: 0, duration: 0 }待用量聚合接入后填充run()还支持两个可选参数源码签名比文档更完整run(input?: string, abortSignal?: AbortSignal)。传入input会在循环开始前向对话追加一条用户消息传入abortSignal则可以与运行时自身的ctx.signal合并用于提前中止运行。AgentHandle配置与执行的句柄useAgent返回AgentHandle同时可通过ctx.agent访问interface AgentHandle { run: (input?: string) PromiseAgentRunResult }约束必须先调用useAgent再调用run()。如果在未配置的情况下调用ctx.agent.run()运行时会直接抛出错误——源码中的保护逻辑context-factory.ts会抛出[agent-runtime] agent.run() called without useAgent().。这也意味着 handler 内可以按需多次调用useAgent重新配置再触发run()。Model模型标识与 provider 解析当model是字符串时运行时通过配置的provider默认anthropic解析它你也可以直接传入已解析的Model对象model: claude-sonnet-4-6 provider: anthropic解析逻辑位于 pi-adapter.ts 的 resolvePiModel字符串模型会调用 pi-ai 的getModel(provider, model)解析Moonshot provider 走专门的getMoonshotModel如果解析失败会抛出[agent-runtime] Unknown model ... for provider ...。由于AgentConfig.provider与Model对象上的provider都可能存在context-factory.ts 统一通过agentModelProvider做归约字符串模型取config.provider ?? anthropic对象模型取model.provider。超时与重试模型调用的可靠性参数modelTimeoutMs与modelMaxRetries控制单次模型调用的稳健性。它们会被 pi-adapter 注入到每次流式调用中pi-adapter.ts未设置时的源码默认值为const DEFAULT_MODEL_TIMEOUT_MS 30_000 // 30 秒 const DEFAULT_MODEL_MAX_RETRIES 2 // 最多重试 2 次也就是说不配置时每个模型步骤最多等待 30 秒、失败后最多重试 2 次。对耗时长、工具密集的 Agent可按需提高这两个值对延迟敏感的交互场景则可以收紧超时。Test responses不调用 LLM 的确定性测试为了在完全不发起 LLM 调用的情况下测试 handler可以传入testResponses。它支持两种形式且当它被设置时运行时不会调用任何真实模型context-factory.ts 会直接走 mock 分支。形式一字符串数组按实体已运行次数选取响应非常适合确定性、可重复的多次唤醒测试ctx.useAgent({ systemPrompt: ..., model: claude-sonnet-4-6, tools: [...ctx.electricTools], testResponses: [Hello! How can I help?, Sure, I can do that.], })源码中数组分支context-factory.ts会统计该实体在runs集合中的既有记录数priorRunCount然后按下标priorRunCount % responses.length选取字符串因此同一实体的第 N 次唤醒总能拿到第 N 个响应。形式二函数每次调用都会收到当前触发消息和一个OutboundBridgeHandle返回字符串则自动作为文本块产出返回undefined则不产出自动文本响应ctx.useAgent({ // ... testResponses: async (message, bridge) { if (message.includes(calculate)) { return The answer is 42. } return undefined // emits no automatic text response }, })测试用例中这种函数形式被广泛用于捕获触发消息。例如 process-wake.test.ts 中webhook 唤醒场景通过testResponses: async (message) { receivedMessage message; return undefined }断言 agent 收到的触发载荷内容。bridgeOutboundBridgeHandle定义于 types.ts还提供了onTextStart/onTextDelta/onTextEnd文本级事件与onToolCallStart/onToolCallEnd工具级事件可模拟工具调用、推理步骤与多轮交互。注意bridge.onRunStart/onRunEnd与 step 起止事件由运行时自动包裹管理函数内部只需使用文本级与工具级方法详见 testing.md。更多基于testResponses编写测试的方法见 TestingAgentConfig与AgentHandle的完整 API 参考见 agent-config.md。与其他 API 的协同上下文组合与自定义工具useAgent通常与另外两类 API 协同使用构成完整的 Agent handler上下文组合ctx.useContext声明带 token 预算与缓存层级的上下文来源控制进入上下文窗口的内容。与useAgent搭配时典型的完整写法示例来自内置 Horton 助手见 context-composition.mdctx.useContext({ sourceBudget: 18_000, sources: { docs_toc: { content: () renderCompressedToc(), max: 3_000, cache: stable }, retrieved_docs: { content: () renderRetrievedDocs(wake, ctx.events), max: 6_000, cache: volatile }, conversation: { content: () ctx.timelineMessages(), max: 9_000, cache: volatile }, }, }) ctx.useAgent({ systemPrompt: ..., model: claude-sonnet-4-6, tools }) await ctx.agent.run()自定义工具工具遵循AgentTool接口含name、label、description、TypeBox 参数 schema 与execute函数详见 agent-tool.md。handler 中构造工具后展开进toolsconst memoryTool createMemoryStoreTool(ctx) const dispatchTool createDispatchTool(ctx) ctx.useAgent({ systemPrompt: You are a helpful assistant with persistent memory., model: claude-sonnet-4-6, tools: [...ctx.electricTools, memoryTool, dispatchTool], }) await ctx.agent.run()工具可以访问ctx.db.collections读写实体持久状态、通过ctx.spawn派生子 Agent 并等待其runFinished唤醒完整示例见 defining-tools.md。小结配置一个可运行的 LLM Agent 只需要三步在 handler 中调用ctx.useAgent()传入AgentConfigsystemPrompt、model、tools 为必填按需补充provider、getApiKey、超时重试与流式回调随后调用ctx.agent.run()执行 Agent 循环并取得AgentRunResult最后通过testResponses在无 LLM 依赖下验证 handler 逻辑。结合ctx.useContext()控制上下文预算、自定义工具扩展能力边界即可在 Electric Agents 运行时之上构建健壮、可测试、可持续演进的 Agent 应用。【免费下载链接】electricThe agent platform built on sync.项目地址: https://gitcode.com/GitHub_Trending/el/electric创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考