如何为 Jaeger 构建并验证一个使用其他 LLM 的自定义 AI Sidecar【免费下载链接】jaegerCNCF Jaeger, a Distributed Tracing Platform项目地址: https://gitcode.com/GitHub_Trending/ja/jaegerJaeger 的 AI 聊天功能并不绑定某一家模型网关AI Gateway只通过 WebSocket 上的 ACP 协议与外部进程通信谁应答谁就是 sidecar。也就是说如果你想在 Jaeger 的聊天体验里用 OpenAI、Anthropic、Ollama 或自己的模型只需构建并运行一个实现了相同 ACP 契约的 sidecar 进程。仓库里有一份可工作的 Python 参考实现scripts/ai-sidecar/gemini/最省事的路线是 fork 它、只替换 LLM 相关代码然后按文档里的冒烟测试逐项验证。主操作路径依据 scripts/ai-sidecar/README.md协议细节可对照 docs/rfc/0002-ai-gateway-contextual-tools.md 和 网关实现说明。准备工作文档明确的依赖如下Go 工具链验证阶段用go run ./cmd/jaeger启动 JaegerPython 3.14并安装 uv——这是 sidecar 唯一支持的依赖安装方式uv sync你目标 LLM 提供商的 API key。另外注意参考实现在 macOS 上要求 Apple silicon因为其依赖链中cryptography49 不再支持 Intel macOS见 scripts/ai-sidecar/gemini/README.md。如果你换用其他提供商的 SDK这条限制是否仍成立取决于你的依赖树建议以uv sync能否成功安装为准。路径 Afork 参考实现并替换 LLMfork 后需要替换的只有四处WebSocket 服务器、ACP handler、_meta解析、MCP 桥接和 contextual-tool 分发都可以原样保留。1. 复制并改名在你本地检出的仓库中执行cp -r scripts/ai-sidecar/gemini scripts/ai-sidecar/myprovider cd scripts/ai-sidecar/myprovider然后更新pyproject.toml把google-genai换成你提供商的 SDK、重命名包如果想让 sidecar 在 Jaeger UI 中以别的名字出现可以在tracing.py里改 service name参考实现用的是jaeger-gemini-sidecar。2. 替换 LLM 客户端在 sidecar.py 中Gemini 客户端在 agent 构建时创建一次约第 67 行# sidecar.py around line 67 self._gemini genai.Client(api_keyconfig.gemini_api_key)把它换成你提供商的客户端并同步修改 sidecar_config.py参考实现校验的是gemini_api_key环境变量GEMINI_API_KEY你需要改成你的提供商对应的变量例如OPENAI_API_KEY否则配置校验会直接报错退出。3. 替换 agentic 循环但保留路由决策_run_agentic_gemini_loop约第 279 行负责 model→tool→model 的循环合并 MCP 工具与 contextual 工具、发送用户消息、循环执行函数调用直到模型停止调用工具。用你提供商的等价实现替换函数体但必须保留路由判断模型给出的工具名在 contextual 集合里 → 走_execute_contextual_tool通过 ACP 扩展方法发回网关否则 → 走_execute_tool调用 Jaeger MCP 服务器。这里有一个文档明确警告的坑不要改写工具名。contextual 工具快照里的名字已经带ui_前缀传给 LLM 时原样传递并按模型返回的精确字符串做路由匹配——前缀由网关侧剥离。4. 转写工具 schema每家 LLM 对 function 声明的形状不同。Gemini 形状的实现在 sidecar_helpers.py_build_gemini_contextual_tool、_extract_function_declaration和 mcp_bridge.pyJaegerMCPBridge.get_gemini_tools里。把这些 helper 改写为你提供商的形状如 OpenAI 的tools[{type: function, function: {...}}]。contextual 快照里的parameters是标准 JSON Schema转换通常只是薄封装。必须与网关对齐的三个线级常量无论走哪条路径以下三个字符串在两端必须逐字一致来源scripts/ai-sidecar/README.md 与 RFC 0002 §9.3常量值出现位置CONTEXTUAL_TOOLS_META_KEYjaegertracing.io/contextual-toolssession/new请求_meta字段内的 keyExtMethodJaegerToolCall_meta/jaegertracing.io/tools/callsidecar → 网关的 ACP 扩展方法UIToolPrefixui_网关为每个 contextual 工具名加的前缀协议层面的其他约束参考实现里都有对应处理网关总是拒绝session/request_permission它不声明任何 fs/terminal 能力sidecar 不要发起权限请求扩展方法名的前导下划线有怪癖部分 ACP 库如 Python 版在发送时自动补_所以用户代码里的常量写成meta/jaegertracing.io/tools/call换语言实现时确认你的库行为线上字节必须是_meta/jaegertracing.io/tools/callcontextual 工具是 fire-and-forget网关对扩展方法立即返回{ result: { acknowledged: true }, isError: false }见 RFC 0002 §6.6。这个 ack 就是全部结果把它作为函数响应喂回 LLM 即可如果阻塞等待一个真实结果会死锁。如果你选择从其他语言从零开始写路径 Bscripts/ai-sidecar/README.md给出了 8 步清单起 WebSocket 服务器监听与agent_url一致的地址如ws://localhost:16688、实现 ACP JSON-RPC 的initialize/session/new/session/prompt三个入站方法、直连 Jaeger MCP 服务器默认http://127.0.0.1:16687/mcp可经JAEGER_MCP_URL覆盖、解析_meta快照并按 session id 存储、合并工具列表、用session/update流式上报进度、按名字路由函数调用、prompt 结束后无条件清理快照。每步都标注了 gemini 参考代码中的对应文件。可选为你的 fork 增加一键启动文档提供的make run-ai-gemini快捷方式只对 gemini 参考实现生效Makefile 中run-ai-gemini直接调用scripts/ai-sidecar/gemini/run.sh且 preflight 会检查GEMINI_API_KEY。如果你的 fork 也想要同样的单命令体验按 scripts/ai-sidecar/README.md 的说明在你的 sidecar 源码旁放一个preflight.sh校验你的 API key 环境变量和一个run.sh可参考 gemini/run.sh它依赖共享的 _lib.sh 完成uv sync、后台启动 Jaeger 并轮询http://127.0.0.1:16686/api/v3/services等待就绪然后在 Makefile 里加一个run-ai-nametarget 指向你的run.sh。验证你的 sidecar以下冒烟测试对路径 A 和路径 B 通用全部来自scripts/ai-sidecar/README.md的 Verify It Works 一节。1. 用示例配置启动 JaegerAI 端点只有在ai.agent_url非空时才会注册见网关 README。仓库自带的示例配置 cmd/jaeger/config.yaml 已经配好了agent_url官方启动器run.sh用的就是它# cmd/jaeger/config.yaml节选 extensions: jaeger_query: ai: agent_url: ws://localhost:16688 mcp: {}在仓库根目录执行go run ./cmd/jaeger --config cmd/jaeger/config.yaml如果用的是自定义配置文件确保extensions.jaeger_query.ai.agent_url指向你的 sidecar 监听地址。2. 启动你的 sidecarcd scripts/ai-sidecar/myprovider uv sync export OPENAI_API_KEY你的提供商 API key # 替换为你实际使用的提供商 uv run python main.py预期启动日志文档示例Jaeger ACP Sidecar listening on ws://localhost:16688这一行出现说明 WebSocket 服务器已在网关配置的地址上监听。3. 发送一个聊天请求curl -N -X POST http://localhost:16686/api/ai/chat \ -H Content-Type: application/json \ -d { threadId: t1, runId: r1, messages: [{role: user, content: what services are running?}], tools: [] }应看到一串 AG-UI SSE 帧RUN_STARTED、TEXT_MESSAGE_START、若干TEXT_MESSAGE_CONTENT如果 LLM 决定调用 MCP 工具还会出现TOOL_CALL_*帧最后是TEXT_MESSAGE_END、RUN_FINISHED。4. 测试 contextual-tool 路径在请求里带一个 contextual 工具并让模型使用它curl -N -X POST http://localhost:16686/api/ai/chat \ -H Content-Type: application/json \ -d { threadId: t1, runId: r2, messages: [{role: user, content: show the flamegraph for trace abc123}], tools: [{ name: show_flamegraph, description: Open the flamegraph view for a trace_id., parameters: {type:object,properties:{trace_id:{type:string}},required:[trace_id]} }] }应看到show_flamegraph的TOOL_CALL_START/TOOL_CALL_ARGS/TOOL_CALL_END帧——注意这里没有ui_前缀网关在转发给浏览器前已经剥离了前缀。这一步能同时验证你的快照解析、扩展方法调用和前缀处理是否正确。5. 运行参考工作流测试gemini 参考实现自带 test_sidecar_workflow.py它通过 WebSocket 连到正在运行的 sidecar用 mock 掉的 LLM 驱动完整的initialize→session/new→session/prompt流程并校验流式 ACP 更新与回合结束标记uv run pytest -q test_sidecar_workflow.py文档建议把这两个 pytest 文件含 test_tracing.py作为你 fork 测试框架的镜像样板。注意该测试针对的是 ACP 会话流程模型本身被 mock因此它验证的是你的 sidecar 骨架而不是提供商集成。6. 确认 UI 自动出现不需要开任何 UI 开关Jaeger 后端会周期性探测配置的agent_url默认每 5 秒可用jaeger_query.ai.health_check_interval调整并把结果作为后端能力通告给 UI。在 sidecar 已能应答initialize后用新的浏览器标签页打开 Jaeger UI——下次页面加载时聊天入口应出现停掉 sidecar聊天入口以同样方式消失。已知边界参考实现只导出 OTel trace默认发到http://localhost:4317即 Jaeger all-in-one 的 OTLP receiver可用--otlp-endpoint/OTEL_EXPORTER_OTLP_ENDPOINT覆盖不导出 metrics——文档明确说 Jaeger 目前不接受 OTLP metrics见 scripts/ai-sidecar/gemini/README.md。未实现_meta/jaegertracing.io/tools/call扩展方法的第三方 ACP agent 会被网关忽略 contextual 工具系统退化为仅内置 MCP 工具仍可用这一点在 RFC 0002 中被视为可接受的设计取舍。若 MCP 工具发现超时可调JAEGER_MCP_DISCOVERY_TIMEOUT_SEC默认 15 秒控制单次发现尝试的超时。【免费下载链接】jaegerCNCF Jaeger, a Distributed Tracing Platform项目地址: https://gitcode.com/GitHub_Trending/ja/jaeger创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考