企业官网建设流程全解析

1. 为什么要在 Kibana 里给 Agent 接一条统一 API 通道

Elastic AI agent builder 是 Kibana 里用来搭建对话式 Agent 的一套能力，它把索引检索、ES|QL 查询、工具调用和对话状态管理打包成 API，让你不用自己写编排逻辑就能让 Agent 直接查数据。它适合两类人：一类是在做搜索与可观测场景、想让运维和业务同学用自然语言问数据的团队；另一类是想把多模型能力接进 Kibana、又不想在每个 Agent 里重复填 Key 的开发者。

问题出在模型接入这一层。Agent builder 本身负责“怎么调工具、怎么维护对话”，但底层大模型走哪个通道、用哪家的 Key，默认配置往往只指向单一来源。一旦你想在同一个 Kibana 里让不同 Agent 用不同模型，或者想把模型调用统一计费、统一限流，就会变成每个 Agent 各配一份凭证，改一次要动好几处。

我这次的做法是：Kibana 侧继续用 agent builder 的原生 API 和 MCP 端点，模型侧统一走 TaoToken 的 API 通道，用一把 Key 覆盖多个模型。这样 Kibana 只管 Agent 和工具，模型路由交给统一通道。下面把配置片段、MCP 接入骨架和验证动作都写出来，你可以直接照着改。

2. TaoToken 前置：拿到统一 Key 和接入地址

TaoToken 在这里的角色是“模型调用的统一入口”。你不需要在 Kibana 里为每个模型单独配一套凭证，而是拿一把 Key，通过同一个 API 地址请求不同模型。对 agent builder 这种要频繁切换模型的场景来说，少维护几份配置就是少几个出错点。

第一步是准备凭证。打开控制台创建 API Key，地址是 https://taotoken.net/console ，创建完把 Key 复制出来，后面配置里会用到。如果你还没决定用哪个模型，可以先在模型对话页面试一下，地址是 https://taotoken.net/models ，确认模型能正常返回再往 Kibana 里接。

第二步是确认接入地址。TaoToken 的 API 根地址是 https://taotoken.net/api ，注意这个地址不带任何查询参数，配置时直接用它作为 base URL。文档页在 https://taotoken.net/doc ，里面有各语言 SDK 的调用示例，遇到参数不确定的时候对着看。

注意：Key 只放在服务端环境变量或 Kibana 的密钥存储里，不要写进前端代码或提交到仓库。Kibana 的 API Key 和 TaoToken 的 Key 是两回事，前者用于访问 Kibana 接口，后者用于访问模型通道，别混用。

如果你后面要做长期编码类 Agent，或者想让 Agent 持续跑任务，可以了解下 Coding Plan，地址是 https://taotoken.net/coding-plan ，它更适合高频、长会话的调用模式。普通的数据问答 Agent 用按量 Key 就够了。

3. 可复制配置：Kibana 环境变量与 MCP 接入骨架

先把 Kibana 侧的基础环境变量配好。下面这段可以直接放进你的 shell 配置或部署脚本里，注意把 KIBANA_URL 和 API_KEY 换成你自己的：

export KIBANA_URL="localhost:5601" export KIBANA_API_KEY="你的Kibana API Key" export TAOTOKEN_API_KEY="你的TaoToken Key" export TAOTOKEN_BASE_URL="https://taotoken.net/api"

Kibana 的 API Key 在 Stack Management 的 API Keys 页面生成，权限至少要有 agent_builder 相关接口的访问权。TaoToken 的 Key 就是上一步在控制台创建的那把。

接下来是 MCP 接入骨架。agent builder 暴露了一个 MCP 端点，路径是/api/agent_builder/mcp，用 JSON-RPC 2.0 通信。先验证端点通不通，列出当前可用的工具：

curl -k -X POST "http://${KIBANA_URL}/api/agent_builder/mcp" \ -H "Authorization: ApiKey ${KIBANA_API_KEY}" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -H "kbn-xsrf: true" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }'

返回里会列出平台自带工具和你自己创建的工具。这一步只验证 Kibana 侧 MCP 端点，还没到模型调用。真正把模型通道接进来，是在 Agent 的配置里指定模型来源。下面是一个创建 Agent 的请求，重点看 configuration 部分怎么把工具和模型串起来：

curl -k -X POST "http://${KIBANA_URL}/api/agent_builder/agents" \ -H "Authorization: ApiKey ${KIBANA_API_KEY}" \ -H "Content-Type: application/json" \ -H "kbn-xsrf: true" \ -d '{ "id": "taotoken_avg_age", "name": "calculate the average age", "description": "从 people 索引计算平均年龄", "labels": ["analytics"], "avatar_color": "#BFDBFF", "avatar_symbol": "TA", "configuration": { "instructions": "你是一个帮助计算 people 索引平均年龄的 Agent", "tools": [ { "tool_ids": [ "platform.core.search", "platform.core.list_indices", "platform.core.get_index_mapping", "platform.core.get_document_by_id" ] } ] } }'

创建完 Agent 后，模型通道的指向通过环境变量或 Kibana 的模型配置项注入。如果你的部署里模型配置是集中管理的，把 base URL 指向https://taotoken.net/api，Key 用TAOTOKEN_API_KEY，这样所有 Agent 共用一条通道。改模型时只动这一处，不用逐个 Agent 改。

4. 验证请求：确认 Agent 调用走通统一通道

配置完要验证两件事：Agent 能不能正常对话，以及模型调用是不是真的走了统一通道。

先发一个对话请求，不指定 agent_id 时走默认 Agent：

curl -k -X POST "http://${KIBANA_URL}/api/agent_builder/converse" \ -H "Authorization: ApiKey ${KIBANA_API_KEY}" \ -H "Content-Type: application/json" \ -H "kbn-xsrf: true" \ -d '{ "input": "people 索引里的平均年龄是多少？" }'

返回里会带一个 conversation_id，说明对话是有状态的。接着用这个 id 继续追问，验证上下文是否延续：

curl -k -X POST "http://${KIBANA_URL}/api/agent_builder/converse" \ -H "Authorization: ApiKey ${KIBANA_API_KEY}" \ -H "Content-Type: application/json" \ -H "kbn-xsrf: true" \ -d '{ "input": "最大年龄和最小年龄分别是多少？", "conversation_id": "上一步返回的conversation_id" }'

第二次提问不用再提索引名，Agent 会沿用上一轮的上下文。如果这一步能正常返回，说明 Agent 编排和对话状态都没问题。

再验证模型通道。最直接的办法是看 TaoToken 控制台的调用记录，地址是 https://taotoken.net/console ，每次 Agent 对话都会产生一条模型调用记录。如果记录里能看到对应的请求，说明模型确实走了统一通道，而不是绕过了配置。另一个办法是临时把 TAOTOKEN_API_KEY 改成一个错误值，再发一次对话请求，如果报错信息指向模型认证失败，就反向证明了调用链路经过 TaoToken。

还可以直接跑一个工具执行请求，确认工具层也通：

curl -k -X POST "http://${KIBANA_URL}/api/agent_builder/tools/_execute" \ -H "Authorization: ApiKey ${KIBANA_API_KEY}" \ -H "Content-Type: application/json" \ -H "kbn-xsrf: true" \ -d '{ "tool_id": "platform.core.list_indices", "tool_params": {} }'

这个请求不涉及模型，只验证 Kibana 工具执行是否正常。工具通、对话通、控制台有记录，三样齐了才算走通。

5. 本篇常见错排查

报 401 或 403：先分清是 Kibana 的 Key 还是 TaoToken 的 Key 出问题。Kibana 接口返回 401，检查KIBANA_API_KEY是否过期、权限是否包含 agent_builder；如果对话能建立但模型返回认证错误，检查TAOTOKEN_API_KEY是否正确、有没有多余空格。

MCP 端点返回 400：多半是请求头缺了kbn-xsrf: true，或者Content-Type没设成application/json。MCP 用 JSON-RPC 2.0，jsonrpc字段和id字段都不能少。

对话没有上下文：检查第二次请求有没有带上第一次返回的conversation_id。不带的话每次都是新对话，Agent 不会记住之前的索引和问题。

模型调用没出现在控制台：确认 base URL 是不是写成了带路径的形式。TaoToken 的 API 根地址是https://taotoken.net/api，不要自己拼多余的路径。另外确认 Agent 的模型配置确实读到了环境变量，有些部署方式下环境变量不会自动透传给 Kibana 进程。

工具列表为空：tools/list返回空，通常是 Kibana API Key 权限不够，或者 agent builder 功能没在当前版本启用。先确认 Kibana 版本支持 agent builder，再检查 Key 的权限范围。

改了 Key 但没生效：Kibana 有些配置是启动时读取的，改完环境变量要重启对应服务。如果是在容器里跑，确认新变量注入到了容器内，而不是只改在宿主机。

6. 后续怎么接：按场景选入口

如果你现在卡在接入或排障阶段，建议先把 API Keys 和接入文档过一遍：创建和管理 Key 在 https://taotoken.net/api-keys ，接口参数和示例在 https://taotoken.net/doc ，这两个页面能解决大部分配置问题。

如果你还在选模型、想先确认哪个模型适合你的数据问答场景，直接去模型对话页面试：https://taotoken.net/models ，用真实问题测一轮，比看参数表直观。

如果你要做的是长期运行的编码类 Agent，或者需要 Agent 持续处理任务、会话很长，那按量 Key 可能不是最合适的，可以看下 Coding Plan：https://taotoken.net/coding-plan ，它的调用模式更贴合高频长会话。

Kibana 侧的 agent builder API 和 MCP 端点保持原生用法不变，你只需要把模型通道统一到一处。这样以后换模型、加模型、调限额，都只动一个地方，Agent 和工具配置不用跟着改。