17 代理创建
本节介绍如何通过可视化流构建器或代码创建 AI 代理。
主题：
多代理系统和主管模式
多代理系统是一种 AI 应用程序设计，其中用户请求由多个合作代理处理，而不是一个大型的全功能代理。
每个代理都有自己的角色、指令、模型配置、内存策略和允许的工具。流定义了请求如何在这些代理之间移动以及如何生成最终答案。
当工作流自然地分成专家职责时，此设计非常有用。例如，一个座席可以检索数据，另一个座席可以调用 API，另一个座席可以汇总查找结果，而主管可以决定使用哪个专员并将结果合并为单个响应。
注意：
作为设计原则，最好从满足要求的最小代理设计开始。在分离问题时添加多个代理，从而提高可靠性、安全性、可维护性或可观察性，而不是增加成本和复杂性。多代理系统的优势
- 专门化：为每个座席提供集中作业、提示和工具集，而不是一个拥挤的指令块。
- 工艺路线和分解：让主管解释请求，将其分解为子任务，并为每个子任务选择合适的专家。
- 工具和数据隔离：仅向负责使用它们的代理公开敏感或高影响力的工具。
- 治理和故障排除：使移交、工具所有权、内存设置和故障点更易于检查。
何时选择多代理或单代理设计
具有更多工具的单个代理通常是最正确的第一个设计。测试更简单，运行更便宜，当任务具有一个明确的目标和一个权限模型时更易于推理。当工作流从显式角色、受限工具访问或可协调多个专家输出的主管中受益时，请使用多代理设计。
| 设计问题 | 在以下情况下使用单个代理： | 在 ... 时使用多代理 |
|---|---|---|
| 任务配置 | 请求具有一个主要目标和一个响应站。 | 必须跨专业分解、路由、验证或合成请求。 |
| 工具和数据 | 相同的指令集和权限模型可以安全地管理所有工具 | 不同的代理需要不同的工具、数据源或访问边界。 |
| 说明 | 即使所有业务规则和工具指南都在一个地方，提示仍然清晰。 | 作为特定于角色的较小提示，可以更轻松地维护说明。 |
| 成本和延迟 | 您希望从用户消息中获得最短的答案。 | 可靠性、治理或可维护性优势证明了额外的编排。 |
| 疑难解答 | 故障很容易在一个跟踪中进行调试。 | 您需要为每个步骤显式切换、状态隔离和更清晰的所有权。 |
支持的模式：编排人员/主管
当前的画布体验支持编排人员/主管模式。在此模式中，聊天触发器将接收用户消息，可选的 Guardrails 将评估输入，而 Supervisor Agent 将充当剩余流的编排器。
主管应专注于规划、路由、委派和最终响应综合。它决定了哪个执行程序代理应该处理一个任务，向执行程序发送一个范围化的指令，检查结果，然后委托另一个步骤或返回最终响应。执行人员代理应该更窄的专家：他们执行分配的工作，使用他们附加的工具，并将有用的结果返回给主管。
关于可视化流画布
通过将节点和工具模板从左侧选项板拖到画布上，然后按请求应移动的顺序连接节点来组合代理。
选择节点将打开屏幕底部的配置面板。
| 画布元素 | 用途 |
|---|---|
| 聊天触发器 | 用户消息的入口点。在屏幕截图中，此节点标记为“消息”，通常位于流的顶部。
聊天触发器节点可以连接到代理、主管代理或护栏节点。每个画布只允许一个聊天触发器。 |
| 界限 | 在模型工作之前或之后放置可选的策略和安全层。护栏策略包括 PII、内容调节和即时注射检测。
Guardrails 节点可以过滤聊天触发器与代理节点之间的流量，在主管和执行器代理之间，或者在代理和工具节点之间。我们建议在聊天触发器和座席节点之间使用单个护栏节点。 |
| 主管代理 | 管弦乐队它接收用户请求，决定哪个执行程序代理或工具应处理每个任务，并协调最终答案。
画布中只允许一个主管代理。 |
| 代理 | 执行程序代理。每个执行程序都应具有明确的专长，例如数据检索、API 查找、汇总或文档问题解答。
将代理/执行程序代理用于单个代理系统。 |
| 工具模板 | 可附加到单个执行程序或主管代理的可重用功能。工具模板包括 SQL、RAG、Prompt、HTTP、Remote MCP 服务器和 Custom Tool。 |
| 开发/游戏 | 画布上方的模式选择器。在编辑代理系统时使用开发；Playground 用于启动测试会话并检查代理行为。
Playground 要求将 AI 计算连接到您的代理。 |
| 缩放控制 | Canvas 缩放选择器。屏幕截图显示了 60% 和 90% 的缩放级别。 |
将聊天触发器和座席添加到 Visual Builder 画布
使用 Visual Builder 创建座席后的第一步应该是添加聊天触发器和主管座席。
- 单击 Supervisor Agent（主管代理）并将其拖动到画布。
配置主管代理
您需要配置添加到 Visual Builder 画布中的主管代理，其中包含概述主管角色的说明。
| 域 | 配置 |
|---|---|
| 代理名 | 为您的主管代理提供描述性名称。通过跟踪和日志调试系统行为时，一个好的描述性名称将非常有用。 |
| 代理说明 | 提供代理用途、角色和一般行为的描述。对于文档用途非常有用。 |
| 区域 | 选择托管主管代理使用的 OCI 生成式 AI 模型的区域。请参见 Generative AI Models by Region 。 |
| 型号 | 选择主管使用的 OCI Generative AI 服务模型。下拉列表列出了所选区域中可用的模型。 |
| 代理说明 | 描述主管角色、路由规则、委派策略、工具使用预期和最终响应格式。 |
- 导航到工作区中的代理。
- 单击画布上的主管代理节点。
- 为您的主管代理提供微不足道的名称和说明。
- 输入主管使用的 OCI Generative AI 服务模型的区域和模型。
- 提供主管代理的代理说明。
建议的主管说明
应使用主管代理的“说明”字段使主管负责编排，而不是执行每个任务本身。
使指令保持具体，以便路由决策可预测。有关一组 Supervisor 指令的示例，请参见以下内容：
You are the supervisor for a multi-agent system.
Responsibilities:
- Understand the user's request and break it into subtasks.
- Select the most appropriate executor agent or tool for each subtask.
- Do not perform specialist work yourself when an executor agent is available.
- Ask for clarification only when required information is missing.
- Combine executor outputs into a concise final answer.
- Mention important assumptions, limits, or failed tool calls in the final answer.
Routing rules:
- Use the SQL agent for structured data questions.
- Use the HTTP agent/tool for external API lookups.
- Use the RAG agent/tool for document or knowledge-base questions.
- Use the prompt tool for reusable prompt-only transformations.配置主管代理内存和状态隔离
主管代理的 "Memory"（内存）选项卡控制主管可以使用的会话和工具输出历史记录的数量以及与执行代理共享的上下文数量。
| 域 | 配置 |
|---|---|
| 启用代理内存 | 当用户需要多回合连续性时启用。禁用隔离的一次性使用任务。
无法为主管代理禁用此字段。 |
| 限制对话历史记录 | 启用以在达到指定的限制后截断 LLM 上下文窗口。禁用以显示完整历史记录。 |
| 截断配置 | 如果启用了限制对话历史记录，则使用此字段设置截断上下文窗口的条件。
选项如下：
|
| 最大消息限制和令牌预算 | 根据您对 Truncation Configuration 的选择，将显示其中一个或两个选项。
默认值为 20 条消息和 5000 个令牌。我们建议从中等值开始，并根据需要进行调整。 |
| 执行者代理的状态隔离 | 选择 Stateless 、 Private 或 Shared 。
|
- 导航到工作区中的代理。
- 单击画布上的主管代理节点。
- 单击内存选项卡。
- 选择是否启用限制对话历史记录。选择截断配置并设置限制（如果已启用）。
- 为执行程序代理的状态隔离选择选项。
模型参数标签
使用“模型参数”选项卡可以配置可供所选模型使用的特定于模型的参数。
可以为主管和执行器代理单独配置模型参数。您可以使用的参数包括温度、顶部 K、顶部 P 和频率补偿。
注意：
只有部分模型会公开可配置的参数。此外，参数因模型系列而异。
向代理添加护栏
您可以通过向画布中添加一个或多个护栏节点来为代理添加其他保护层。
| 界限 | 选项 | 何时使用 |
|---|---|---|
| 个人可识别信息 (PII) |
|
当流必须在模型处理之前或之后阻止或屏蔽敏感的个人数据时使用。 |
| 内容审核预防 | 包含“块”、“通知”和“允许”选项的输入和输出行。 | 用于定义流如何处理仇恨，性，暴力，有毒，贬损或骚扰内容。 |
| 提示注入检测 | 包含“阻止”和“允许”选项的输入行。 | 用于减少恶意指令覆盖系统或代理指令的机会。 |
- 通过将鼠标悬停在连接上并单击红色 X，删除“聊天触发器”与“主管座席”之间的连接。
将执行者代理和工具添加到代理
可以将执行程序代理添加到工具中，以便为主管代理执行专门的工作。
- 导航到工作区中的代理。
- 将代理节点从选项板拖到画布中。代理节点应放置在高级代理下方。
- 将工具从调色板拖到画布中。
- 单击并拖动主管代理上的连接器句柄以连接到代理节点。
- 单击并拖动代理上的连接器句柄以连接到工具节点。
执行程序代理配置
可以通过修改 "Configuration"（配置）、"Memory"（内存）和 "Model"（模型）选项卡上的设置来配置代理节点，以帮助您定义每个代理的用途。
应在给定特定功能和目标的情况下狭义地配置代理，以便主管代理可以可靠地路由工作。
表 17-1“代理配置”选项卡
| 域 | 配置 |
|---|---|
| 代理名 | 最佳做法是根据每个执行程序代理的专业（如 SQL_AGENT、DOCUMENT_AGENT、API_AGENT 或 SUMMARY_AGENT）命名。
每个执行程序代理的名称对超级用户代理可见，因此请使用描述性名称。 |
| 代理说明 | 提供每个执行程序代理的详细说明。每个执行程序代理的说明对主管代理可见。 |
| 区域 | 选择托管代理使用的 OCI 生成式 AI 模型的区域。请参见 Generative AI Models by Region 。 |
| 型号 | 选择代理使用的 OCI Generative AI 服务模型。下拉菜单列出了所选区域中可用的模型。
选择适合执行程序任务的模型。执行程序代理不需要使用与主管代理相同的模型。 |
| 代理说明 | 准确描述执行程序应该做什么，它可以使用哪些工具，以及它应该返回什么输出结构。 |
执行程序代理内存选项卡
如果将执行程序代理连接到超级用户代理，则将在超级用户节点中配置执行程序的内存，并将其应用于所有执行程序代理。
| 域 | 配置 |
|---|---|
| 启用代理内存 | 当用户需要多回合连续性时启用。禁用隔离的一次性使用任务。 |
| 限制对话历史记录 | 启用以在达到指定的限制后截断 LLM 上下文窗口。禁用以显示完整历史记录。 |
| 截断配置 | 如果启用了限制对话历史记录，则使用此字段设置截断上下文窗口的条件。
选项如下：
|
| 最大消息限制和令牌预算 | 根据您对 Truncation Configuration 的选择，将显示其中一个或两个选项。
默认值为 20 条消息和 5000 个令牌。我们建议从中等值开始，并根据需要进行调整。 |
| 执行者代理的状态隔离 | 选择 Stateless 、 Private 或 Shared 。
|
执行程序代理模型参数选项卡
使用“模型参数”选项卡可以配置可供所选模型使用的特定于模型的参数。
注意：
只有部分模型会公开可配置的参数。参数也因模型系列而异。参数的示例包括温度、顶部 K、顶部 P 和频率补偿。可以为主管和执行器代理单独配置模型参数。
建议的执行者说明
You are the SQL executor agent.
Responsibilities:
- Translate the supervisor's task into safe SQL tool usage.
- Use only the SQL tools attached to this agent.
- Return a concise answer plus any important query assumptions.
- Do not invent data. If the tool cannot answer, say what is missing.
- Return structured output with: answer, evidence, assumptions, and follow_up_needed.
通过 Visual Builder 列出的代理核对清单
使用此列表作为指南，可确保为使用 Visual Builder 构建的代理包括并配置了所有必要的组件。
构建核对清单
- 代理只有一个预期的入口点：聊天触发器/消息。
- 护栏以预期位置连接，并在需要时启用。我们建议在触发器消息和代理之间插入护栏。
- 主管代理具有选定的区域、选定的模型和编排说明。执行程序代理也是如此。
- 在 Supervisor 代理的 "Memory"（内存）选项卡中配置多代理系统的内存。选择符合隐私和连续性要求的执行器状态隔离。
- 每个执行程序代理都有一个明确的专业和狭窄的指令。
- 每个工具仅附加到应使用该工具的代理。
- 没有节点断开连接。
- 将 AI 计算连接到代理系统，以测试单个工具和运行 Playground 体验。
表 17-2 常见问题
| 问题 | 可能原因 | 建议的操作 |
|---|---|---|
| 主管未调用执行程序 | 主管指令太模糊或未连接执行程序。 | 添加显式路由规则并确认执行程序节点已连接到超级用户。 |
| 执行程序返回广泛或非主题的答案 | 执行程序指令过于笼统。 | 使执行程序角色变窄并定义所需的输出结构。 |
| 未使用工具 | 工具已断开连接或连接到错误的代理。 | 检查工具连接和代理工具计数标记。 |
| 护栏不开火 | Guardrail 部分已配置但未启用。 | 打开 Guadrails 节点并确认节切换已打开。 |
| 跨代理的上下文泄漏 | 状态隔离设置为“共享”或内存超出预期范围。 | 使用无状态或专用隔离实现更严格的隔离。 |
| 跟进问题丢失上下文 | 内存已禁用或截断太过激。 | 启用内存并调整最大消息限制。 |
代理通过代码
您可以在 Oracle AI Data Platform Workbench 中将自己的 LangGraph 代码库引入 AI 代理，或者通过代理编码体验直接在平台上创建一个全新的 LangGraph 代理。
您可以使用 AI Data Platform Workbench 实用程序 Python 库 aidputils 来配置基础模型并将系统工具导入代理。有关 helpputils API 参考，请参阅 Aidp-utils API for Oracle AI Data Platform Workbench 。
通过上载现有代码文件或通过内嵌编辑器直接在代理中创建代码文件，可以通过代码创建代理。
- Python (.py)
- JSON
- TXT
- CSV
- PSV
- SH
- Folder - 文件夹
您可以通过单击文件选择器下拉列表来查看和浏览可用的代码文件。
条目和相关性文件
条目文件是代码文件，其类具有定义为代码的代理所需的设置和调用方法。Oracle AI Data Platform Workbench 要求您通过代码为代理设置条目文件。
相关性文件是包含代理定义为代码所需的第三方库的文件。相关性文件通常是包含所需第三方库列表的 requirements.txt 文件。
注意：
在编辑器中通过单击“Play（播放）”按钮或通过“Test（测试）”选项卡测试代理时，将安装第三方库。我们建议首先测试代码来安装第三方库。安装磁带库期间发生的错误将显示在输出单元中。代理类
AgentBasic 是用于使用有状态 LangGraph 工作流设置和调用简单会话代理的模板类。它演示了使用两种主要方法进行最小代理开发所需的结构：
setup()：初始化代理工作流并定义图形。invoke(user_query, **kwargs)：对用户消息运行代理并返回响应。
在集成到更大的系统之前，可以使用 main() 函数直接运行和测试该功能。
定义
class AgentBasic:
def __init__(self) -> None:
self.graph = None
def setup(self) -> None:
self.graph = StateGraph(MessagesState)
self.graph.add_node(mock_llm)
self.graph.add_edge(START, "mock_llm")
self.graph.add_edge("mock_llm", END)
self.graph = self.graph.compile()
system_prompt = "Be a helpful assistant."
async def invoke(self, user_query: str, **kwargs):
user_message = HumanMessage(content=user_query)
messages = {"messages": [dict(user_message)]}
try:
return self.graph.invoke(messages)
except Exception as e:
import traceback
logger.error(f"Exception while calling invoke {e}", exc_info=True)
print("Stack trace:\n", traceback.format_exc())
测试调用
此测试调用是初始功能测试的理想选择。
注意：
包括独立测试的主要入口点。import asyncio
async def main():
test_agent = AgentBasic()
test_agent.setup()
result = await test_agent.invoke("Hi there")
print("Agent response:", result)
if __name__ == "__main__":
asyncio.run(main())
- 该脚本将创建代理，对其进行设置并发送示例用户消息。
- 代理响应（{"messages"：[{"role"："ai"，"content"："hello world"}]} 在此示例中）。
用法指南
使用设置和调用方法创建代理类。
| 设置() | 初始化代理工作流 | agent.setup() |
| 调用() | 使用用户消息运行代理 | 等待 agent.invoke（“您的问题”） |
- 异步：
invoke()是异步方法；将其与await一起使用或在异步循环中运行。 - 测试：随附的
main()防护 (if __name__ == "__main__":) 可在部署之前轻松测试代理。
通过上载的代码构建代理
您可以通过上载 LangGraph 代码库，使用现有代码构建端到端代理应用程序。
注意：
最多可以上载 500 个文件的单个文件和文件夹，每个文件的最大大小可以为 500MB。上载的总大小限制为 5GB。- 单击上传。
通过创建新代码通过代码构建代理
您可以通过代码编辑器直接在代理中创建代码，从而使用现有代码构建端到端代理应用程序。
- Python (.py)
- JSON
- TXT
- CSV
- PSV
- SH
- 文件夹
- 单击添加新文件。
通过代码为代理设置条目文件
您的 AI 代理通过代码需要具有所需的类、设置和调用代理所需方法的条目文件。
- 右键单击条目文件，然后单击设置条目文件。您还可以选择该文件并单击代码编辑器右上角的 Set entry file（设置条目文件）按钮。
通过代码为代理设置相关性文件
您需要为代理通过包含您的代码所依赖的任何第三方库的代码流设置依赖性文件。
- 右键单击依赖性文件，然后单击设置依赖性。您还可以选择该文件，然后单击代码编辑器右上角的 Set dependencies file（设置依赖关系文件）按钮。
测试代理代码
您可以从“Test（测试）”选项卡测试用于代理的代码，以验证和调试代码。
- 单击播放场选项卡。
- 单击播放以测试所选代码文件。
代理在编码体验方面的技能
通过代理技能，代理可以发现和使用特定于任务的指令、引用文件、模板、资产和可选的可执行脚本，而无需将该域知识硬编码到代理的指令中。
技能将作为文件夹存储在代理代码库中。每个技能都有一个必需的 SKILL.md 文件，该文件描述了技能的作用以及代理应如何使用它。技能还可以包括支持文件，例如方案、示例、提示、模板、资产或脚本。
有关更多信息，请参阅代理技能概览。
- 座席发现存在技能。
- 座席仅在相关时激活技能。
- 代理仅在需要时从技能文件夹加载其他文件。
- 如果技能允许，代理可以运行显式声明的技能入口点。
何时使用座席技能
- 特定于域的说明
- 编码或数据分析工作流
- SQL 生成指导
- 业务流程手册
- 文件样板
- 方案参考
- 用于安全计算、转换或查找的可重用脚本
技能在运行时的工作方式
在运行时，主机应用程序将确定哪些技能目录可用，例如项目级和用户级技能文件夹。该平台从 SKILL.md 加载每项技能的元数据，并构建一个以技能名称为关键字的目录。
然后，座席可以使用与技能相关的工具：
| 工具 | 用途 |
|---|---|
activate_skill(name) |
从 SKILL.md 加载技能说明。 |
list_skill_files(name, path) |
列出技能文件夹内的可用文件。 |
load_skill_file(name, path) |
从技能文件夹加载支持文件。 |
run_skill_entrypoint(name, entrypoint, args_json, timeout_seconds) |
如果技能允许，则运行显式声明的 Python 入口点。 |
某些环境还可能将可用技能的摘要直接嵌入到系统提示符中。在该设置中，代理可以从提示中发现可用的技能，然后在需要完整说明时使用 activate_skill。
技能文件夹结构
技能使用座席技能样式的文件夹布局：
<skills_dir>/
some-skill/
SKILL.md
references/
...
scripts/
...
assets/
...仅需要 SKILL.md。其他文件夹是可选的。
| 文件夹或文件 | 必需 | 用途 |
|---|---|---|
SKILL.md |
是 | 主要技能元数据和说明。 |
references/ |
无 | 支持文档、方案、示例或模板。 |
scripts/ |
无 | 只能在显式声明为入口点时运行的 Python 脚本。 |
assets/ |
无 | 技能使用的静态资产。 |
写作技能
每项技能必须包括位于 SKILL.md 顶部的 YAML 前垫，然后是 Markdown 指令。
基本示例
---
name: sql-helper
description: Helps the agent write safe SQL queries using project schemas.
license: internal
compatibility: "agent-platform"
metadata:
owner: data-platform
domain: analytics
allowed-tools: "analyzeQuery inspectSchema"
---
# SQL Helper
Use this skill when the user asks for SQL generation, query review, or schema-aware analysis.
Before writing SQL:
1. Inspect the relevant schema files in `references/`.
2. Prefer explicit column names.
3. Avoid destructive statements unless the user explicitly asks for them and the environment allows them.
表 17-3 支持的前材料字段
| 域 | 必需 | 说明 |
|---|---|---|
| name | 是 | 目录和工具使用的唯一技能名称。 |
| description | 是 | 用于搜索和路由的简短说明。 |
| 执照 | 无 | 技能的许可证或使用策略。 |
| 兼容性 | 无 | 支持的运行时或平台的兼容性说明。 |
| metadata（元数据） | 无 | 字符串到字符串的元数据映射。 |
| 允许的工具 | 无 | 此技能允许的工具的空格分隔列表。 |
| 入口 | 无 | 技能声明的可执行入口点的列表。 |
添加支持文件
通过支持文件，技能可将详细内容保留在主要说明之外。这使 SKILL.md 保持专注，同时仍然允许代理访问更丰富的上下文。例如：
skills/
sql-helper/
SKILL.md
references/
warehouse_schema.md
query_style_guide.md
examples.md
代理可以通过以下方式检查这些文件：
list_skill_files("sql-helper", "references")
load_skill_file("sql-helper", "references/warehouse_schema.md")
- 数据库方案
- API 实例
- 提示模板
- 样式指南
- 域词汇表
- 分步指南
- 测试用例或示例
创建可执行技能
技能可以通过 run_skill_entrypoint（可选）公开可重用可执行行为。这适用于受控操作，例如计算、转换、验证或提取结构化数据。
- 技能必须在允许的工具中包括
run_skill_entrypoint。 - 脚本必须在
SKILL.md的入口部分显式声明。
可执行技能示例
skills/
statistics-helper/
SKILL.md
scripts/
summarize_numbers.py
技术参数
---
name: statistics-helper
description: Computes basic summary statistics for numeric data.
allowed-tools: "load_skill_file list_skill_files run_skill_entrypoint"
entrypoints:
- name: summarize_numbers
script: scripts/summarize_numbers.py
func: run
description: Returns count, min, max, mean, and median for a list of numbers.
---
# Statistics Helper
Use this skill when the user asks for basic descriptive statistics.
scripts/summarize_numbers.py:
from statistics import mean, median
def run(*, values: list[float]) -> dict:
if not values:
raise ValueError("values must not be empty")
return {
"count": len(values),
"min": min(values),
"max": max(values),
"mean": mean(values),
"median": median(values),
}
Example invocation:
run_skill_entrypoint(
name="statistics-helper",
entrypoint="summarize_numbers",
args_json="{\"values\": [10, 20, 30, 40]}",
timeout_seconds=10
)
The runner returns structured output that includes exit_code, stdout, stderr, and a best-effort parsed result when the script prints or returns JSON.
可执行入口点的规则
- 位于技能的脚本/目录下
- 在技能的入口点前线声明
- 由技能的
allowed-tools设置允许
平台不提供通用任意脚本执行。未在 SKILL.md 中声明的脚本不可运行。
脚本运行程序使用超时，默认为 10 秒，运行具有隔离模式行为的 Python，并应用路径限制。但是，基于子进程的执行不是完整的操作系统沙盒。对于生产环境，应考虑更高的隔离（例如容器、受限文件系统或网络控制）。
使用 allowed-tools 的工具权限
allowed-tools 充当技能级别的权限门。对于仅限文档的技能，您只能允许使用文件读取工具：
allowed-tools: "load_skill_file list_skill_files"对于可以执行声明脚本的技能，请包括 run_skill_entrypoint：
allowed-tools: "load_skill_file list_skill_files run_skill_entrypoint" 除非技能真正需要可执行行为，否则不要添加 run_skill_entrypoint。
如何让你的经纪人发现和使用技能
要向座席补充技能，您必须使用 helppUtils 库中的以下对象实例化技能目录、技能中间件并将技能转换为工具：
| 工具 | 用途 |
|---|---|
discover_skill_catalog |
确定默认技能搜索位置（项目 + 用户）从搜索到的目录构建 SkillCatalog |
SkillMiddleware |
将可用技能汇总和传送规则附加到系统提示。
为工作空间驱动的中间件构建提供工厂助手。 |
make_skill_tools |
此方法返回技能发现工具– activate_skill、list_skill_files、load_skill_file 和 run_skill_entrypoint。座席可以使用这些工具来激活和运行不同的技能。 |
下面是您的条目文件将包括的内容的示例：
from aidputils.agents.skills.discovery import discover_skill_catalog
from aidputils.agents.skills.middleware import SkillMiddleware
from aidputils.agents.skills.tools.factories import make_skill_tools
...
class SchoolGradeAgentWithEmbededSkills:
...
def init(self) -> None:
...
self.catalog = discover_skill_catalog(skill_folder_whitelist=None)
self.skill_middleware = SkillMiddleware(self.catalog)
self.tools = make_skill_tools(self.catalog)
您可以通过向代码添加此记录器语句来调试技能目录。这将打印技能目录中发现的每项技能：
for info in self.catalog.list():
logger.info("skill_id=%s name=%s desc=%s root=%s skill_file=%s", info.skill_id, info.name, info.description, info.root_dir, info.skill_file)
技能优先顺序
该平台可以从多个位置加载技能，例如项目级目录和用户级目录。目录将这些位置汇总到一个以名称为关键字的技能列表中。
当多个门店包含具有相同名称的技能时，优先级将确定使用哪一项。以后存储覆盖较早的，这允许主机应用程序控制用户级技能、项目级技能还是工作区级技能是否优先。
技能拟定最佳实践
保持技术专注
在激活后立即使用 SKILL.md 来获取座席所需的核心指令。在引用/中放置长方案、示例和引用材料。
写入清除说明
说明字段用于搜索。使它足够具体，以便座席知道何时激活技能。
description: Helps generate BigQuery SQL using the finance warehouse schema.description: Helps with data.使用显式入口点名称
entrypoints:
- name: validate_query
- name: summarize_numbers
- name: transform_csventrypoints:
- name: run
- name: do_it 返回结构化结果
可执行脚本应尽可能返回 JSON 序列化结果。这使代理可以更轻松地检查和使用输出。
避免不必要的执行
尽可能优先使用说明和参考文件。仅对真正需要代码的操作使用可执行入口点。
代理技能故障排除
如果您在实施代理技能时遇到问题，请查看此列表以获得解决问题的帮助。
座席看不到我的技能
- 技能文件夹位于已配置的技能目录下。
- 文件夹包含 SKILL.md。
- SKILL.md 具有有效的 YAML 前处理材料。
- 前言包括名称和说明。
代理激活错误的技能
检查技能目录中的重复技能名称。如果两项技能的名称相同，则目录优先级确定使用哪一项技能。
无法加载支持文件
- 该文件位于技能文件夹内。
- 路径不包括遍历，例如 ../。
- 文件未隐藏。
- 不排除该文件，例如 __pycache__ 或 .pyc。
不会运行入口点
- allow-tools 中包含 run_skill_entrypoint。
- 入口点在 SKILL.md 中声明。
- 脚本路径位于脚本/下方。
- 该脚本是一个 .py 文件。
- 脚本中存在 func 中的函数名称。
- 参数是有效的 JSON 对象。
入口点超时
仅当操作需要更长时间时，才增加 timeout_seconds。对于长时间运行或资源密集型操作，请考虑将操作移至专用服务或更隔离的执行环境。
示例：完全代理技能
此示例演示了实施后的完整座席技能。
文件夹构造
skills/
customer-support-reply/
SKILL.md
references/
tone_guide.md
refund_policy.md
escalation_rules.md
技术参数
---
name: customer-support-reply
description: Helps draft customer support replies using the company tone guide and policy references.
allowed-tools: "load_skill_file list_skill_files"
metadata:
owner: support-operations
domain: customer-support
---
# Customer Support Reply
Use this skill when the user asks for help drafting, reviewing, or improving a customer support response.
Workflow:
1. Identify the customer’s issue.
2. Load the relevant policy file from `references/` if needed.
3. Draft a clear, empathetic response.
4. Avoid making commitments that are not supported by policy.
5. Recommend escalation when the request matches the escalation rules.
This skill does not run code. It gives the agent structured instructions and optional policy files that can be loaded only when relevant.
代理测试
您可以测试代理以预览和调试其输出。您还可以创建和管理测试会话，为代理探索不同的测试方案。
测试代理的第一步是将代理连接到 AI 计算。附加代理的操作将代理的副本推送到 AI 计算。只要您的代理连接到 AI 计算，每次单击 "Test"（测试）按钮时，您对代理所做的任何更改都会传播到附加的计算。
单击“Test（测试）”按钮后，将转到测试操场。
- 一个聊天窗口，您可以在其中启动会话并开始与座席聊天，或者恢复现有会话
- 基于图形的代理表示形式
- 显示会话期间生成的跟踪和跨度的树的面板
- 跟踪并跨越浏览器面板，其中显示跟踪并跨越属性、输入/输出。“详细信息”选项卡包括 ID、开始和结束时间、执行时间，而“事件”选项卡突出显示执行期间的任何错误。
通过 Playground，您可以独立交互和测试每个座席（如果您希望这样做）。默认情况下，将选择主管座席，但您可以选择与每个执行者座席单独交谈并进行测试。这允许您模拟主管代理向执行程序代理发出请求的行为。为此，请在聊天窗口的下拉菜单中选择要测试的座席。
跟踪和跨度在您创建第一条消息后立即显示在中央面板中。每个任务对应于不同的用户消息。您可以单击左转义符展开跟踪并检查跨度。
在游乐场测试您的座席
您可以从 Test 操场测试视觉构建器和基于 LangGraph 的代理，以验证和调试您的代理。
- 在画布顶部，单击背景。将代理推送到您连接的计算可能需要几秒钟。
