什么是 agent?agent 是 AI modelLLM通过自定义 instructions 和一组已分配的 tools 来定义。从 9.4 版本开始agent 也可以配备 skillsskills 是可复用的 instruction set用于提供特定领域的专业能力。用户可以在 Agent Builder UI 中或通过 programmatically 使用自然语言与 agent 进行对话。agent 会解析用户请求来定义一个 goal然后在循环中运行 tools 来实现该目标。agent 的响应基于其配置的 tools、指令和行为设置。Agent 是如何工作的当你向 agent 提问时它会分析你的请求来定义一个具体的 goal。它会选择最合适的 tools并确定要使用的正确参数。agent 会评估每一步操作返回的信息并判断是否需要使用更多 tools或者直接生成回复。这个“选择 tool、执行、分析”的迭代过程会持续进行直到 agent 能够提供完整答案。注意工具选择、执行和分析的过程会消耗 token。要了解使用量是如何计算的请参阅 Elastic Agent Builder 中的 Token usagetoken 使用情况。Elastic Agent Builder 包含一个默认 agent名为Elastic AI Agent。你可以创建自定义 agents设置自定义指令并选择所需工具以满足特定用例或工作流程的需求。你也可以使用预先配置的内置 agents这些代理针对常见用例进行了专门优化。如果你想查看系统有哪些 agents 并备份会服请参考代码https://github.com/liu-xiao-guo/elastic_backup什么是 tools?Agents 使用工具tools来代表你进行搜索、检索以及执行操作。工具可以理解为函数它们是模块化、可复用的动作代理可以调用这些工具来与 Elasticsearch 数据进行交互。技能Skills则是更高层级的能力它将多个工具协调起来形成面向特定领域的工作流。要了解更多信息请参阅 Skills。代理如何使用工具工具使代理能够与 Elasticsearch 数据进行交互。当代理接收到一个自然语言查询时它会执行以下步骤分析请求的语义意图从可用工具集中选择合适的工具将请求参数映射到工具的输入参数按需按顺序执行工具处理结构化的输出数据每个工具都是一个具有明确接口的原子操作。工具接收带类型的参数并返回结构化结果这些结果可以被代理解析、转换并用于生成最终响应。注意工具执行和结果处理会消耗 token。要了解使用量如何计算请参阅 Elastic Agent Builder 中的 Token usagetoken 使用情况。内置工具Elastic Agent Builder 提供了一整套内置工具用于处理 Elasticsearch 数据的核心功能。这些工具开箱即用无法被修改或删除。内置工具作为构建更复杂交互的基础模块为代理能力提供支撑。完整列表请参考内置工具参考注意某些内置技能还包含内联工具这些工具仅在该技能激活时可用并不会出现在工具参考列表中。有关详细信息请参阅 内置技能参考。自定义工具你可以通过自定义工具定义来扩展内置工具目录。要了解如何创建和管理自定义工具请参阅 自定义工具。如果你想列出备份或者恢复所有的工具请参考 https://github.com/liu-xiao-guo/elastic_backup目前创建工具的类别更多创建自定义工具的例子https://blog.csdn.net/ubuntutouch/category_13134509.html什么是 skillsskill 是一种可复用的能力包为 agent 提供针对特定任务类型的专业能力。每个 skill 包含三部分Instructions用 Markdown 编写的领域专属指导用于引导 agent 如何处理该任务。Toolsagent 在该 skill 启用时可以调用的内置或自定义 tools。Contextskill 可以使用的额外知识例如参考文档或 runbook。这使得 skills 与 tools 不同tools 是类似执行查询或检索文档这样的离散操作。skills 的层级更高它将 tools 与完成端到端 workflow 所需的指令和 context 组合在一起。skills 也不同于 agent 的 system prompt。system prompt 始终在上下文中而 skills 是按需加载的。一个 agent 可以拥有多个 skills但不会一次性全部加载进 context window。你只需要编写一次 skill然后将其分配给任何需要的 agent从而保持 agent 配置简洁并让专业能力更容易在团队中共享。技能如何被调用?技能可以通过以下三种方式进行调用自动发现默认代理会收到可用技能列表以及每个技能的名称和描述。它会根据用户的自然语言输入自动选择并调用最相关的 skills。无需使用特殊语法。Slash 命令用户可以通过输入/加技能名称以及提示词来显式调用某个技能。当你明确知道自己需要哪个技能时这种方式会很有用。附件驱动Attachment-driven当用户在消息中附加上下文数据时例如来自 alert flyout 的告警agent 可以根据附件类型自动调用相关技能。使用场景当你有多个代理都需要一致遵循的领域知识或流程时可以使用技能Skills。例如一位 Elastic Security 用户询问某台可疑主机。entity-analytics技能会被激活并引导代理完成实体查找、风险评分分析、资产关键性分析以及行为历史分析。一位 Elastic Observability 用户询问为什么某个服务变慢或者为什么触发了告警。observability.investigation技能会被激活并跨 APM 服务和基础设施诊断问题。一位 Elasticsearch 用户询问如何为商品目录结合关键词搜索与向量搜索。search.hybrid-search技能会被激活并指导代理构建混合搜索解决方案。内置 skillsElastic Agent Builder 提供了面向常见任务领域的内置技能。可用技能取决于你的解决方案或 Serverless 项目类型有些技能适用于所有部署而有些则专属于 Elasticsearch、Observability 或 Elastic Security。内置技能为只读无法被修改或删除。完整列表请参阅 Built-in skills reference内置技能参考。自定义 skills你可以使用自己的自定义技能来扩展内置技能目录。自定义技能会保存到你的技能库中你可以在Manage components Skills中进行管理。创建技能后它会被添加到技能库中但在你通过该代理的Customize Skills将其添加之前它不会对任何 agent 可用。这种分离机制意味着你可以维护一个共享的技能库并自行决定每个代理可以访问哪些 skills。要了解如何创建和管理自定义技能请参阅 Custom skills自定义技能。使用 API 列出技能要以编程方式检索所有可用技能请使用 List skills API 接口GET /api/agent_builder/skills有关完整的技能 CRUD 操作请参阅 Custom skills自定义技能。更多有关如何读取保存及恢复 skills请参阅代码https://github.com/liu-xiao-guo/elastic_backup 在 Elastic Agent Builder 中编写高效的自定义技能自定义技能能够为你的代理在特定任务领域提供一致、可复用的专业能力。一个技能的质量几乎完全取决于其指令编写得是否优秀。本指南将介绍如何编写指令以帮助代理选择正确的技能遵循正确的执行步骤优雅地处理边缘情况edge cases决定将指令放在哪里代理的 system prompt系统提示词始终会存在于上下文中。而技能指令只有在代理判断该技能相关时才会被加载。这个区别应当指导你将哪些内容放到哪里。使用 skillUse a skill当指令具有任务特定性或者复杂到需要独立上下文时应使用技能指令只适用于某些任务而不是 agent 处理的所有任务指令过于详细或领域特定如果放入 system prompt 会使其变得杂乱你希望同一套专业能力能够被多个代理复用任务复杂度足够高需要独立文档例如存在十个或更多特定注意事项你需要某些工具仅在特定任务类型下可用使用 system prompt当指令是通用且始终适用时应将其保留在 system prompt 中该行为属于 agent 身份的核心部分或者应适用于每一次响应指令简短、通用并且始终相关对于只针对单次交互的一次性需求直接在对话中给出指令即可无需将其编码到技能或 system prompt 中。提示Tip有关如何编写自定义指令、工具描述以及聊天提示词的更广泛指导请参阅 Best practices for prompt engineering提示工程最佳实践。编写清晰的 descriptiondescription 是 agent 用来决定是否加载某个 skill 的主要信号。它始终会被包含在上下文中而 skill 的完整指令只有在该 skill 被选中后才会被读取。如果 description 模糊不清agent 可能会加载错误的 skill甚至不加载任何 skill。一个好的 description 应该说明该 skill 的作用并明确指出何时应该使用它。保持简洁description 的长度上限为 1024 个字符并且每一个词都应该对路由决策有实际帮助。✅ GoodFind security alerts related to an original alert by analyzing common IOCs, affected assets, attack patterns, and temporal proximity. 1 Use when investigating an alert to understand the broader attack context. 21清晰描述 skill 的作用并具有足够的具体性以便与相似 skill 区分开来。2明确说明触发条件使 agent 知道何时加载它。❌ 过于模糊How to find alerts 1 Security 21) 没有说明该 skill 做什么或何时使用它。2) 没有给 agent 提供任何可执行的指导说明何时或如何使用该 skill。让 descriptions 在语义上保持区分如果你有多个 skill 覆盖相近的领域必须确保它们的 descriptions 在语义上是有明显区分的。如果两个 descriptions 很相似agent 将难以在它们之间做出选择。这种情况下应当合并重叠的 skills或者进一步优化措辞使差异更加清晰。结构化 instructionsinstructions 字段包含 skill 的完整内容使用 Markdown 编写。agent 只有在判断该 skill 相关后才会读取这些内容因此你有足够空间写得详细。但结构非常重要组织良好的 skill 能帮助 agent 确认已选择正确的 skill并准确执行你的意图。从触发条件开始在 instructions 的开头必须设置一个明确的部分说明该 skill 何时适用。即使 description 已经负责路由判断在内容中再次说明触发条件也很重要这样可以帮助 agent 确认当前使用的是正确的 skill并让 skill 本身具备自说明性。## When to Use This Skill 1) Use this skill when: - A user asks to investigate a security alert 2) - A user wants to understand if an alert is isolated or part of a broader attack - A user asks are there related alerts or what else happened around this time - You need to correlate multiple security events1) 清晰命名该部分使 skill 具有自文档能力。2) 将触发条件表述为具体的用户查询或任务类型而不是抽象的类别。提示Tip避免使用 “该 skill 用于处理告警” 这类模糊的开头。应明确说明该 skill 应处理的具体场景或用户请求类型。编写详细的核心指令核心指令是你控制 agent 行为的地方必须尽可能精确。如果指令模糊或过短会导致结果不一致agent 会自行 “填补空白”而这些推断往往不符合你的预期。对于流程型任务使用分步骤step-by-step格式效果很好## Finding Related Alerts 1. **Extract key indicators from the original alert:** 1) - IP addresses involved - User accounts affected - Timestamps (a window of ±2 hours is a good starting point) - Attack signatures or IOCs - Affected assets and hostnames 2. **Query for related alerts using these criteria:** 2) - Same source or destination IP within 24 hours - Same user account across different alert types - Same malware hash or signature - Alerts on the same asset within a short timeframe 3. **Present findings with context:** 3) - Group related alerts by common indicators - Explain the relationship between alerts - Highlight the timeline of events - Note if the pattern suggests a coordinated attack1) 在查询之前先收集数据这样 agent 才能基于具体数值进行搜索。2) 使用具体、可衡量的标准而不是模糊的描述。3) 明确告诉 agent 结果应以什么格式呈现而不仅仅是要找什么内容。提示Tip如果你发现自己在为两个不同的工作流编写指令这通常意味着应该将 skill 拆分开。添加真实示例具体示例可以提升 agent 正确应用指令的能力。应展示真实的输入以及期望的输出或推理过程并提供足够细节以避免歧义。## Example: IP-based Correlation. 1) User query: Investigate alert ALT-2024-001 for related activity 2) Original alert: Failed login from IP 192.0.2.45 to server WEB-01 Steps taken: 1. Search for other alerts involving 192.0.2.45 2. Search for other alerts on WEB-01 3. Check for alerts within ±2 hours of the original timestamp Found related alerts: 3) - ALT-2024-002: Port scan from 192.0.2.45 (10 minutes earlier) - ALT-2024-003: SQL injection attempt on WEB-01 (15 minutes later)1) 为示例使用具有描述性的名称使 agent 能够准确引用正确的示例。2) 包含一个真实的用户查询以帮助将示例锚定在具体上下文中。3) 在步骤旁同时展示预期的输出格式。当任务涉及复杂逻辑或输出格式非常重要时必须添加示例。处理边缘情况edge cases明确告诉 agent 在出现问题或异常情况时应该如何处理。如果没有清晰的指导agent 会自行 “即兴发挥”这可能导致输出混乱或不符合预期。## Edge Cases - **No related alerts found:** Inform the user that the alert appears isolated, and explain what was searched. 1) - **Too many related alerts:** Group by type and show summary statistics rather than listing all results. 2) - **Partial data available:** Work with available indicators and note which data points are missing. - **Ambiguous relationships:** Present possible connections with confidence levels rather than asserting a definitive link. 3)使用 referenced contentreferenced_content API field 允许你将命名的内容块附加到 skill 中。agent 可以根据任务需求选择读取哪些内容块而不是一次性加载全部内容。当 skill instructions 的部分内容只在特定条件下适用时这种方式非常有用。适合使用 referenced content 的内容包括API specifications这些内容较长或更新频繁大量 example queries这些内容会让 main instructions 变得臃肿lookup tables、error codes 或 reference dataagent 可能需要查阅条件相关的 guidance例如在同一个 skill 中分别为 Linux、macOS 和 Windows 行为提供独立内容块在 main instructions 中通过名称引用这些 content blocks让 agent 知道它们的存在以及何时需要读取它们## Log Triage Process For example ES|QL queries, see ./queries. 1) For OS-specific behavior, see ./linux, ./macos, or ./windows. 2)1) 通过相对路径指向已命名的 content blocks让 agent 知道在哪里找到它们。2) 使用基于主题的名称这样 agent 可以为任务选择最相关的 block。保持 referenced content 的层级浅一些。嵌套超过两层会让结构更难理解。关于如何创建带有 referenced_content 的 skill 示例请参考 Skills APIs。将每个 skill 限定为一个任务每个 skill 应该只做好一件事。一个专注的 skill 更容易被 agent 正确使用也更容易维护。如果你发现自己在编写覆盖两个不同工作流的指令就应该将其拆分为两个 skill并分别设置独立的 description。只分配相关工具每个 skill 都可以指定它能够使用的 tools。只分配与该 skill 任务直接相关的 tools。提供不必要的 tools 会增加 agent 误用工具的风险。同样的原则也适用于工具设计优先选择“单一职责”的 tool而不是将多个操作组合在一起的封装型 tool。在 instructions 中需要清晰描述如何使用这些可用 tools让 agent 明确在什么情况下应该调用哪个 tool。测试你的 skill保存后将 skill 分配给 agent并使用真实查询进行测试。检查agent 是否在预期情况下选择该 skill是否正确遵循步骤是否能处理你定义的 edge cases根据测试结果持续调整 description 或 instructions。如果你想创建自己的 skill请参考文章 “Elasticsearch智能搜索 - AI builderworkflow 及 skills”。什么是 plugins?Plugins 是可安装的软件包用于打包 agent 的能力例如 skills并且兼容 Claude agent plugin 规范。你可以使用 plugin 将一组相关能力一次性安装到 agent 中。在 9.4 发布中plugins library 在默认情况下是隐藏的直到你在 Kibana 中启用agentBuilder:experimentalFeatures这个高级设置后才会显示。安装 plugin要安装 plugin在左侧边栏中选择 Manage components Plugins。选择 Install plugin然后选择安装方式从 URL 安装提供远程托管的 plugin package URL。上传 ZIP从本地上传打包为 .zip 文件的 plugin。确认安装。已安装的 plugins 会出现在 library 中并且可以在当前 space 中分配给 agents。你可以随时从 library 中移除 plugin。Plugin 的开发例子请详细阅读Elasticsearch为 AI Agent builder 创建 skill plugin