如何为 DojoAgents 开发自定义工具添加 Tools、Dashboard 路由与 Docker 部署完整教程【免费下载链接】DojoAgentsDojoAgents: Full-Market AI Copilot for Personal Investment项目地址: https://gitcode.com/gh_mirrors/do/DojoAgentsDojoAgents 是一个面向个人投资的 Full-Market AI Copilot全市场 AI 副驾。本文将带你以零基础视角掌握 DojoAgents 自定义工具开发的核心技能如何添加 ToolsAgent 工具、扩展 Dashboard 路由以及用 Docker 一键部署让你的 AI 投资助手具备全新的能力。为什么需要自定义工具DojoAgents 的核心是Agent Loop大模型根据你提供的工具Tools自主决定调用哪些能力比如查行情、看板块、调仓。当你发现现有工具不够用时只需在约定位置添加一个ToolSpec模型就会自动学会使用它。第一步理解 ToolSpec 工具契约所有自定义工具都基于统一的工具契约定义在 dojoagents/tools/registry.py 中。一个工具由 5 个要素组成字段说明name工具名模型通过它发起调用description给模型看的能力说明写得越清晰模型用得越准parametersJSON Schema 形式的参数定义handler必须为 async的执行函数sandbox_policy沙箱策略名控制超时与权限一个最小可用的工具定义长这样ToolSpec( nameexample_tool, descriptionShort model-facing description., parameters{type: object, properties: {}}, handlerhandle_example_tool, )执行时dojoagents/tools/executor.py 中的ToolExecutor会统一捕获异常、计时并规范结果——你不需要自己处理错误格式。第二步添加通用自定义工具5 步标准路径官方推荐的扩展流程非常简洁详见 docs/site/zh/development/adding-tools.md在dojoagents/tools/目录中实现工具模块定义一个或多个ToolSpec确保 handler 是 async返回dict[str, Any]或字符串在Runtime.from_config_store()或插件 registry 中注册添加聚焦测试focused tests。金融只读能力优先走 DojoSDK 通道如果你要扩展的是行情 / 板块 / 新闻等金融只读能力官方有明确的优先级优先在dojoagents/tools/dojo_sdk_tool.py中增加OFFLINE_TOOL_BINDINGS或同层 SDK 封装并保证 handler 支持可过滤查询date / market / L1–L3 / ticker避免整表 dump 拖垮上下文。⚠️ 注意不要把新的 Agent 金融只读依赖加到dashboard/tools/domain_tools.py那是 Legacy 维护区。Dashboard 工具的边界类型路径何时使用Portfolio 写工具dashboard/tools/portfolio_tools.py组合创建/调仓等有副作用写路径Domain 读工具dashboard/tools/domain_tools.py仅维护既有行为新 Task 勿新增有副作用的工具建议返回resource_changes可视化结果应返回viz_blocks让前端统一刷新缓存而不是靠工具名猜副作用。第三步添加 Dashboard 路由分层开发当自定义工具需要配套的 REST API 时Dashboard 路由采用严格的五层分层详见 docs/site/zh/development/adding-dashboard-routes.md内容位置Routerdojoagents/dashboard/routers/Request/response schemadojoagents/dashboard/schemas/Business logicdojoagents/dashboard/services/Dependency accessdojoagents/dashboard/deps.pyApp includedojoagents/dashboard/server.py以现有的 dojoagents/dashboard/routers/utility.py 为范例一个典型路由就三步声明APIRouter(prefix...)、用Query(...)校验参数、通过Depends(get_financial_registry)拿依赖。几个必须遵守的规范预期失败使用fastapi.HTTPException边界层记录异常、不静默吞错JSON/JSONL 存储优先用AtomicJsonStore/AtomicJsonlStore不要对用户可控的 key 做不安全的路径拼接。第四步Docker 一键部署验证自定义工具开发完成后最快的验证方式是 Docker 部署。仓库在 docker/ 下提供两个镜像构建均在仓库根目录执行docker build -f docker/agent/Dockerfile -t dojoagents:latest . docker run --rm -p 8765:8765 dojoagents:latest然后浏览器访问http://127.0.0.1:8765即可看到 Dashboard 运行效果。docker/agent/Dockerfile 采用多阶段构建Node 20 编译前端 → 打 Python wheel →python:3.12-slim运行最终镜像不再依赖 Node.js体积小巧。部署时有 3 个实用建议数据持久化容器内配置目录为/root/.dojo建议挂载 named volume 或 bind mount 保留agents.yaml、缓存与会话数据密钥注入模型 API Key 通过配置文件或环境变量传入切勿 bake 进镜像只读挂载配置的示例docker run --rm -p 8765:8765 \ -v $(pwd)/agents.yaml:/root/.dojo/agents.yaml:ro \ -e OPENAI_API_KEY... \ dojoagents:latest完整细节见 docs/site/zh/development/docker-packaging.md文档站点镜像docker/docs-site/Dockerfile则用于独立托管 MkDocs 静态站。常见坑与最佳实践清单✅ 不要绕过ToolExecutor让执行器统一规范化结果✅ 阻塞 I/O 应放到 async client 或 bounded executor 中✅ 工具名与 description 直接决定模型调用准确率请认真打磨文案✅ 每个新工具都配一个聚焦测试参考 tests/ 中的既有模式❌ 避免在 handler 中整表 dump 金融数据一律支持可过滤查询。总结本教程带你走完了 DojoAgents 自定义工具开发的完整闭环理解 ToolSpec 工具契约 → 按 5 步标准路径添加 Tools → 按五层分层扩展 Dashboard 路由 → 用 Docker 镜像一键部署验证。掌握了这套扩展体系你就能把自己的投资研究思路变成 Agent 的原生能力。更多开发细节可参阅 docs/site/zh/development/ 与 仓库地图祝你扩展愉快 【免费下载链接】DojoAgentsDojoAgents: Full-Market AI Copilot for Personal Investment项目地址: https://gitcode.com/gh_mirrors/do/DojoAgents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考