1. 从 Elastic Agent Builder 到 MCP一个能跑起来的 Agentic 参考架构Elastic Agent Builder 是 Elasticsearch 9.2 之后以 tech preview 形式放出来的一组 AI 能力核心作用是让你用自然语言直接和索引里的数据对话同时支持自定义 tool、Elastic API、A2A 以及 MCP。MCPModel Context Protocol则是一个开放标准让 LLM 通过 tools 去调用外部系统。把这两者拼在一起就能得到一个 Agentic 参考架构Elasticsearch 当 vector store 和语义检索底座Agent Builder 暴露 MCP serverLangChain/LangGraph 这类框架当 MCP client 去编排工作流。这套架构适合谁适合已经在用 Elasticsearch 做知识库、又想接本地 AI 编码工具或 Agent 框架做联调的团队。真正卡人的地方往往不是架构本身而是工具侧的 Key 和 API 通道怎么统一。我这次的做法是用 TaoToken 做统一 Key 接入层把模型调用和 MCP 工具调用收敛到一套配置里下面把 settings.json / config.toml 骨架和连通性验证步骤完整给出来。整个参考架构分两层。Ingestion 层负责把数据写进 Elasticsearch通过 ingest pipeline 调用 ELSER 生成 embeddings落到semantic_text字段。Agent Builder 层负责把索引上的检索能力包装成 tool再通过 MCP server 暴露出去MCP client 拿到 tools 列表后交给 LLM 决策调用。安全漏洞 agent 就是个典型用例先在内部知识库做 semantic search再决定要不要去外部搜索最后让 LLM 关联两边发现并生成缓解建议。2. TaoToken 前置统一 Key 与 API 通道准备在动 Elasticsearch 之前先把模型侧的通道打通。TaoToken 在这里扮演的是统一 Key 网关你不需要在 settings.json、config.toml、环境变量里分别塞不同厂商的 Key而是拿一个 Key 走同一个 API 入口模型对话、coding plan、Agent 框架调用都复用。第一步去控制台创建 API Key。打开 https://taotoken.net/console 登录后在 API Keys 页面新建一个 Key复制出来先存到本地密码管理器。这个 Key 后面会同时出现在OPENAI_API_KEY和 MCP client 的 header 里。第二步确认你要用的模型名。在模型对话页面 https://taotoken.net/models 可以直接试跑确认模型可用再写进配置。这一步别省很多人配置写完报 404 就是因为模型名写错。第三步记下两个地址。API 基址是https://taotoken.net/api注意这个地址不带任何查询参数直接作为 base_url 用。官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 需要看文档时从 https://taotoken.net/doc 进。注意API 基址和官网地址不要混用。base_url 只填https://taotoken.net/api多带路径会导致 404。如果你打算长期跑编码类 Agent建议顺手看一下 Coding Plan 页面 https://taotoken.net/coding-plan 它针对高频编码调用做了额度设计比按次调用更划算。这一步不是必须但联调阶段调用量大提前规划能省事。3. 可复制配置settings.json 与 config.toml 骨架工具侧接入的核心是把 MCP server 和模型通道都写进配置文件。下面给两份骨架一份给支持 settings.json 的编辑器类工具一份给支持 config.toml 的 Agent 框架。3.1 settings.json 骨架{ model: { provider: openai-compatible, base_url: https://taotoken.net/api, api_key: ${TAOTOKEN_API_KEY}, model: gpt-5.2-2025-12-11 }, mcpServers: { agent-builder: { transport: streamable_http, url: ${KIBANA_URL}/api/agent_builder/mcp, headers: { Authorization: ApiKey ${ELASTICSEARCH_API_KEY}, kbn-xsrf: true } } } }这里有两个占位符要替换TAOTOKEN_API_KEY是你上一步创建的 KeyELASTICSEARCH_API_KEY是 Elasticsearch 的 API Key。KIBANA_URL指向你的 Kibana 实例如果你用了自定义 spaceMCP 地址要改成{KIBANA_URL}/s/{SPACE_NAME}/api/agent_builder/mcp。3.2 config.toml 骨架[model] provider openai-compatible base_url https://taotoken.net/api api_key ${TAOTOKEN_API_KEY} model gpt-5.2-2025-12-11 reasoning_effort low [mcp.agent_builder] transport streamable_http url ${KIBANA_URL}/api/agent_builder/mcp [mcp.agent_builder.headers] Authorization ApiKey ${ELASTICSEARCH_API_KEY} kbn-xsrf truereasoning_effort设成 low 是为了让响应更快同时保留模型能力。如果你做的是复杂安全分析可以调到 medium但联调阶段先用 low 验证连通性。3.3 环境变量占位配置文件里全部用${}占位实际值走环境变量避免 Key 进版本库。export TAOTOKEN_API_KEYsk-你的TaoTokenKey export ELASTICSEARCH_ENDPOINThttps://your-es-endpoint:9200 export ELASTICSEARCH_API_KEY你的ElasticsearchApiKey export KIBANA_URLhttps://your-kibana-url export INDEX_NAMEsecurity-vulnerabilitiesPython 侧用load_dotenv()加载然后os.getenv读取。Kibana 请求头里kbn-xsrf必须带否则 Agent Builder 的 tools API 会拒绝。4. 验证请求从 MCP tools 列表到一次最小语义检索配置写完别急着跑完整工作流先做三步验证。4.1 验证模型通道curl -s https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: gpt-5.2-2025-12-11, messages: [{role: user, content: ping}] }返回里有choices字段就说明模型通道通了。如果返回 401检查 Key 是否复制完整返回 404检查 base_url 是不是多带了路径。4.2 验证 MCP tools 列表from langchain_mcp_adapters.client import MultiServerMCPClient client MultiServerMCPClient( { agent-builder: { transport: streamable_http, url: f{KIBANA_URL}/api/agent_builder/mcp, headers: {Authorization: fApiKey {ELASTICSEARCH_API_KEY}}, } } ) tools await client.get_tools() print([t.name for t in tools])正常会打印出[platform_core_search, ..., security-semantic-search]。如果列表为空说明 Agent Builder 没启用或者 tool 还没创建。4.3 创建 semantic search tool 并验证import requests security_search_tool { id: security-semantic-search, type: index_search, description: Search internal security documents including incident reports, pentests, internal CVEs, security guidelines., tags: [security, semantic, vulnerabilities], configuration: {pattern: INDEX_NAME}, } resp requests.post( f{KIBANA_URL}/api/agent_builder/tools, headers{ kbn-xsrf: true, Content-Type: application/json, Authorization: fApiKey {ELASTICSEARCH_API_KEY}, }, jsonsecurity_search_tool, ) print(resp.status_code, resp.text)返回 200 后这个 tool 会出现在 Kibana UI 里也会出现在上一步的 MCP tools 列表中。索引 mapping 里记得加semantic_text字段并把 title、content、doc_type、severity 用copy_to指过去否则语义检索拿不到内容。index_mapping { mappings: { properties: { title: {type: text, copy_to: semantic_field}, content: {type: text, copy_to: semantic_field}, doc_type: {type: keyword, copy_to: semantic_field}, severity: {type: keyword, copy_to: semantic_field}, date: {type: date}, semantic_field: {type: semantic_text}, } } }数据用 bulk API 写入refreshTrue保证立即可检索。跑一次查询We are using Node.js with Express 4.17 for our API gateway. Are there known prototype pollution vulnerabilities?如果返回里带 severity 和 affected_systems说明整条链路通了。5. 本篇常见错排查MCP 连接返回 401九成是Authorization头格式不对。Elasticsearch 用的是ApiKey xxx不是Bearer xxx。TaoToken 那边才是Bearer。两个 Key 别搞混。tools 列表为空先确认 Agent Builder 已启用再确认 tool 创建请求返回 200。如果 Kibana 用了自定义 spaceMCP 地址必须带/s/{SPACE_NAME}否则连到默认 space 找不到 tool。semantic search 返回空结果检查 mapping 里semantic_field是不是semantic_text类型检查copy_to有没有漏字段。ELSER 模型需要先在集群里部署没部署的话semantic_text字段不会生成 embeddings。模型调用 404base_url 写成https://taotoken.net/api/v1会 404正确写法是https://taotoken.net/api路径由 SDK 自己拼。模型名也要和模型对话页面里列出的完全一致。配置文件里 Key 不生效${}占位符依赖运行环境支持变量展开。如果你的工具不支持就改成直接读环境变量的写法别把 Key 硬编码进文件。LangGraph 工作流卡住decide_internet_search节点如果一直返回需要外部搜索检查 Serper API Key 是否配置。外部搜索是可选项联调阶段可以先跳过只验证内部 semantic search。6. 把通道固定下来再谈扩展这套参考架构的价值在于模块化Elasticsearch 管数据Agent Builder 管 tool 暴露MCP 管协议TaoToken 管模型通道。任何一层都能单独替换。你可以在同一个 MCP client 下挂第二个 agent也可以把 ingestion 换成 Logstash 或 Kafka模型侧换模型只需要改配置里的 model 字段Key 和 base_url 不用动。联调阶段建议先把reasoning_effort设低、只跑内部检索确认 MCP tools 列表和 semantic search 都正常再逐步加外部搜索和复杂工作流。需要长期跑编码类 Agent 的话Coding Plan 页面 https://taotoken.net/coding-plan 有额度方案接入文档在 https://taotoken.net/doc API Key 管理在 https://taotoken.net/api-keys 。把这几处收藏好下次换工具时直接复用同一套 Key 和配置骨架就行。