如何实现在 Claude Managed Agents 聊天中渲染交互式图表的自定义工具【免费下载链接】claude-quickstartsA collection of projects designed to help developers quickly get started with building deployable applications using the Claude API项目地址: https://gitcode.com/GitHub_Trending/an/claude-quickstarts在 claude-quickstarts 仓库的managed-agents/copilot-kit-ag-ui示例中一个由 Anthropic 托管的 Claude Managed Agent 充当个人理财助手当它想展示数字时会调用自定义工具把交互式图表还款时间线、增长预测、预算拆分、方案对比直接渲染进 CopilotKit 聊天界面用户还能拖动滑杆在前端重算图表。这篇文章以这个可运行的 demo 为路径讲清楚这类渲染即结果的自定义工具是怎么定义、注册和验证的。准备条件demo 的运行前提在 README 中列明Node 22 或更高版本node --version检查Anthropic API 凭据且账号已开通 Managed Agents beta设置ANTHROPIC_API_KEY或已执行过ant auth login配置 profileSDK 会自动找到二者之一组织需开启 30 天数据保留。claude-fable-5在 zero data retention 的组织下不可用。工作目录为 managed-agents/copilot-kit-ag-ui它是一个 npm workspace 根目录。启动 demo 并验证图表能渲染按顺序执行npm install # 安装全部 workspaces npm run setup # 一次性创建云环境 agentID 写入 agent-ids.json npm run dev # 启动 dev serversruntime 在 :8787web app 在 :5173npm run setup会创建两个持久化资源云环境和financial-assistantagent并把 ID 存入agent-ids.json。agent 只创建一次之后每个 session 按 ID 引用重复运行 setup 是空操作除非传-- --force重新配置 agent 定义。打开 http://localhost:5173 发送文档给出的示例问题If I invest $500/month at a 7% annual return, what will I have in 20 years?预期现象回复中内联出现一张交互式增长预测图表而不是纯文字数字。图表上的滑杆在前端本地重算不会触发新一轮 agent 调用。另外服务端会为每个新 session 打印一个 Console trace URL可以并排查看原始 agent 活动。自定义工具的服务端契约图表工具定义在 server/src/vizTools.ts共四个show_payoff_timeline、show_growth_projection、show_budget_breakdown、show_comparison。以还款时间线为例摘录自该文件{ name: show_payoff_timeline, description: Render an interactive debt-payoff chart in the chat: remaining balance by month, payoff date, and total interest, with a payment slider the user can drag to explore what if I paid more. Use whenever you discuss paying down a specific debt. Pass a comparisonPayment to contrast two plans (e.g. minimum vs aggressive)., parameters: { type: object, properties: { title: { type: string, description: Short chart title, e.g. Credit card payoff }, principal: { type: number, exclusiveMinimum: 0, description: Current balance in dollars }, aprPercent: { type: number, minimum: 0, maximum: 100, description: Annual interest rate, e.g. 22 for 22% APR }, monthlyPayment: { type: number, exclusiveMinimum: 0, description: Planned monthly payment in dollars }, comparisonPayment: { type: number, exclusiveMinimum: 0, description: Optional second payment amount to compare against, }, }, required: [title, principal, aprPercent, monthlyPayment], }, handler: rendered(show_payoff_timeline), }其中rendered(name)的 handler 忽略输入、只返回一句确认文本Rendered show_payoff_timeline to the user as an interactive visual.。这是整个设计的核心约定渲染本身就是工具的结果agent 负责提供初始数字handler 的 ack 让这一轮继续流动。接入点在 server/src/index.tsvizTools作为backendTools传给上游适配器ag-ui/claude-managed-agents的ManagedAgentsAgentconst runtime new CopilotSseRuntime({ agents: { financial-assistant: new ManagedAgentsAgent({ managedAgentId: ids.agentId, agentVersion: ids.agentVersion, environmentId: ids.environmentId, backendTools: vizTools, sessionStore: store, sessionTitle: (threadId) Finance assistant thread ${threadId}, }), }, });注意 server/src/setup.ts 中创建 agent 时并没有注册这些可视化工具——适配器会在每个 session 上把它们作为工具覆盖项注册与 agent 自身的工具集agent_toolset_20260401web_fetch被禁用合并。因此修改工具契约不需要重新 provision agent。agent 的系统提示词则明确要求把图表工具作为顶层工具调用直接调用绝不包在 repl 脚本里因为 repl 包装的调用无法触达用户。前端注册useRenderTool 把工具调用变成 React 组件服务端声明agent 能调什么前端声明调用来了渲染成什么。web/src/viz/renderers.tsx 用 CopilotKit 的useRenderTool按工具名匹配TOOL_CALL_*事件并挂载组件摘录useRenderTool( { name: show_growth_projection, parameters: growthSchema, render: vizRender(growthSchema, Building growth projection…, GrowthProjection), }, [], );growthSchema等是 zod 结构对应show_growth_projection的initialAmount、monthlyContribution、annualReturnPercent、years等参数全部用z.coerce.number()解析。文件头注释解释了原因CopilotKit 运行时在不同版本下会以不同形状投递工具参数——类型化对象、所有数字被字符串化的对象、或嵌套数组以 JSON 字符串到达。所以renderers.tsx先用asRecord归一化结构再经带z.coerce的 schema 解析后才挂载组件inProgress状态或未通过解析时显示加载占位行。同一文件末尾还有一个通配注册name: *让bash、web_search、文件操作等内置工具的每次调用渲染为紧凑的可展开活动行而不是静默消失。整个组件在 web/src/App.tsx 里挂载于CopilotKitProvider内部、与CopilotChat并列自身不渲染任何内容。修改或新增一个图表工具按 CLAUDE.md 的设计说明改动分两种情况修改现有工具的参数或渲染行为只改server/src/vizTools.ts的契约和web/src/viz/下的 React 组件重启 dev server 即可。因为工具是逐 session 注册的工具覆盖项改契约永远不需要重新 provision。新增一个 agent 能感知的工具名系统提示词在 provision 时固化在 agent 定义里setup.ts的ASSISTANT_SYSTEM列出了四个工具及其用途要 agent 认识新名字就得改提示词并npm run setup -- --force从零重建 agent。新增前端渲染器时沿用同样的解析后挂载模式定义 zod schema 承接服务端契约中的数字边界status inProgress时返回占位组件解析失败时返回说明性占位成功才挂载图表组件。验证方式与常见问题验证主路径就是上面那步发示例投资问题看到内联图表且滑杆可拖。CLAUDE.md 列出的常见失败及判断方法服务启动时报No agent configured没跑过npm run setup且三个ANTHROPIC_*ID 环境变量也未设置。setup 期间client.beta.environments.create或client.beta.agents.create返回 403/404组织没有 Managed Agents beta 权限或模型在该组织的数据保留策略下不可用。出现提到 Observable 的instanceof报错树里存在多份rxjs拷贝。AG-UI 客户端和 CopilotKit 运行时交换 RxJS observable两份拷贝会破坏instanceof检查从 workspace 根目录重装让package.json里overrides固定的rxjs版本生效。端口冲突设置PORT给服务端dev 模式下还要同步更新web/vite.config.ts里指向 :8787 的代理目标。web 页面正常但聊天报错Vite 开发代理把/api/copilotkit转发到 :8787去查服务端日志。限制这个 demo 的会话状态由适配器的有界内存 store 维持服务器重启即开新 session旧 session 不会删除聊天端点本身无鉴权每条消息都消耗 API 额度公开分享前需设置ALLOWED_ORIGINS、保持 URL 私密或在前面加鉴层见 README 的 Security posture 一节。如果需要持久化 session文档指出的下一步是替换为持久化的sessionStore。【免费下载链接】claude-quickstartsA collection of projects designed to help developers quickly get started with building deployable applications using the Claude API项目地址: https://gitcode.com/GitHub_Trending/an/claude-quickstarts创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考