22 AI 代理
本章提供有关在工作区中创建、测试、部署和监视代理的信息。
代理是端到端的代理应用。代理通过由不同类型（触发器、代理、护栏或工具）的节点表示的步骤图形进行定义。可以通过无代码可视化流构建器以及通过第三方库（如 LangGraph）的代码来定义代理。
- 定制工具：通过定制代码工具，代理开发人员可以使用自己的 Python 代码扩展 AI 数据平台。将工具实施打包为 ZIP 文件，将其上载到工作区并进行配置。代理使用 LLM 在运行时提供的参数将代码调用为工具。
- HTTP ：通过 HTTP 请求工具，您的代理可以调用任何 HTTPS REST API。您可以配置请求，包括方法、URL、标头、查询参数、请求正文、验证以及（可选）响应优化步骤。然后，代理在运行时调用端点。HTTP 请求工具在可视化构建器和代码构建器中都可用。在代码构建器中，该工具通过 helppUtils Python 库进行配置。
- 提示：通过提示工具，AI 开发人员可以定义可向 LLM 发出的参数化提示供他们选择。提示工具的常见用例包括电子邮件起草任务、翻译任务、样式转换、git 提交消息和代码说明。
- 远程 MCP 服务器：代理开发人员可以使用远程 MCP 服务器工具将其代理连接到远程模型上下文协议 (MCP) 服务器。
- RAG ：借助 RAG 工具，座席可以在生成响应之前提取相关的外部知识。在 AI Data Platform Workbench 中，RAG 工具查询知识库 (23ai Vector Search)，并检索语义相关的文档块。然后将这些块传递给代理以生成响应。
- SQL ：使用 SQL 工具，代理可以对通过外部目录（例如 Oracle Autonomous AI Lakehouse、Oracle Autonomous AI Transaction Processing 或 Oracle AI Database）注册的结构化数据源执行 SQL 查询。该工具适用于预定义 SQL 查询并可以进行参数化的情况。目标是让代理为参数分配值。此工具不是基于自然语言提示生成 SQL 查询的 NL2SQL 工具。
注意：
SQL 工具仅对外部目录中的数据执行查询。它不支持存储在标准目录中的数据。
注意：
必须先将 AI 计算附加到代理，然后才能测试系统工具。如果未附加计算，则禁用“Test（测试）”选项卡。在 AI Data Platform Workbench 中创建代理将在您选择的工作区文件夹中生成代理构件文件 (.aflow)。无法修改此文件。
多代理系统和主管模式
多代理系统是一种 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"（模型）选项卡上的设置来配置代理节点，以帮助您定义每个代理的用途。
应在给定特定功能和目标的情况下狭义地配置代理，以便主管代理可以可靠地路由工作。
表 22-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 体验。
表 22-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.
表 22-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 的代理，以验证和调试您的代理。
- 在画布顶部，单击背景。将代理推送到您连接的计算可能需要几秒钟。
关于代理工具
Oracle AI Data Platform Workbench 支持工具模板，可对其进行配置以访问数据并满足您的用例需求。
代理支持由单个代理组成的配置，该代理可以与一个或多个工具进行交互。Oracle AI Data Platform Workbench 提供了三种工具模板，可通过可视化流或代码进行配置以供使用：
- 定制代码：定制代码工具允许 AI 开发人员使用 Python 实施其工具。开发人员将其工具打包到 ZIP 中，将其上载到其工作区，并将其配置为代理中的节点。自定义代码工具适用于内置工具无法提供所需集成的情况。
- HTTP 请求：通过 HTTP 请求工具，开发人员可以利用 AI Data Platform Workbench API 及其提供的功能，在其代理中使用支持的 REST API 调用。代理可以使用 REST API 创建工作区对象、检查详细信息、拉式列表或修改现有对象。有关可用 API 的完整列表，请参阅 REST API for Oracle AI Data Platform Workbench 。
- 提示：通过提示工具，AI 开发人员可以定义可向 LLM 发出的参数化提示供他们选择。提示工具的常见用例包括电子邮件起草任务、翻译任务、样式转换、git 提交消息和代码说明。
- RAG ：借助 RAG 工具，座席可以在生成响应之前提取相关的外部知识。在 AI Data Platform Workbench 中，RAG 工具查询知识库 (26ai Vector Search)，并检索语义相关的文档块。然后将这些块传递给代理以生成响应。
- SQL ：使用 SQL 工具，代理可以对通过外部目录（例如 Oracle Autonomous AI Lakehouse、Oracle Autonomous AI Transaction Processing 或 Oracle AI Database）注册的结构化数据源执行 SQL 查询。该工具适用于预定义 SQL 查询并可以进行参数化的情况。目标是让代理为参数分配值。此工具不是基于自然语言提示生成 SQL 查询的 NL2SQL 工具。
注意：
SQL 工具仅对外部目录中的数据执行查询。它不支持存储在标准目录中的数据。
代理流工具（通过可视化流）
通过可视化流向座席添加工具时，您可以在座席的工具模板下找到工具。通过将工具拖放到可视化流画布中，可以向座席添加工具。在画布上拖动工具节点后，该节点会自动与代理连接。
可以在“参数”选项卡中配置每个工具，并通过单击“测试”选项卡独立于代理进行测试。
注意：
必须先将 AI 计算附加到代理，然后才能测试系统工具。如果未附加计算，则禁用“Test（测试）”选项卡。代理流工具（通过 LangGraph 代码）
您可以通过 AIDPToolConf() 类的实例向 LangGraph 编码代理添加 RAG、SQL 和提示工具。
from aidputils.agents.toolkit.configs import AIDPToolConf
aidp_tool = AIDPToolConf(name, description, tool_class , conf, params)
- 名称：用于帮助用户和 LLM 了解工具用途的描述性名称。
- 说明：为用户和 LLM 提供足够信息以了解工具的作用的全面汇总。
- tool_class：支持的工具类型：
PromptTool、SQLTool或RAGTool。 - conf：工具配置。此信息在 LLM 中隐藏。
- params：暴露给 LLM 的参数。
定制工具
通过定制代码工具，座席开发人员可以使用自己的 Python 代码扩展 AI 数据平台。
将工具实施打包为 ZIP 文件，将其上载到工作区，并将其配置为代理中的定制代码工具节点。代理使用 LLM 在运行时提供的参数将代码调用为工具。
定制代码工具适用于内置工具（HTTP、SQL、RAG、MCP）未涵盖所需的集成的情况，例如，当您需要执行本地计算、解析特定于域的格式或编写多个步骤时，这些步骤应以单个工具调用的形式显示在代理中。
使用 Python 代码上载自定义代码工具的 ZIP 文件时，AI Data Platform Workbench 具有以下限制：
| 约束条件 | 限制 |
|---|---|
| 最大 ZIP 大小 | 10 MB |
| ZIP 中的最大文件大小 | 每个文件 10 MB |
| 最大未压缩总大小 | 500 MB |
| 遍历路径 | 已阻止（。。/已拒绝） |
注意：
定制代码工具在连接到代理的 AI 计算上运行。根据工作区网络配置，代码可以访问计算环境和出站网络访问。仅上传您信任的来源的代码。自定义代码工具参数
在“参数”选项卡上，为程序包中的每个工具类配置静态设置。使用“工具类”下拉列表可以在软件包中搜索到的工具之间切换。
- 工具类：选择要配置的工具类。下拉列表从
tool_implementation.py中注册的类中填充。 - 说明：对工具的作用进行清晰简洁的说明。该说明将提供给代理，并帮助 LLM 决定何时调用该工具。缺省描述是从 tool_config.json 读取的，可以在此处覆盖。
- 配置：工具在运行时所需的静态设置。这些是在
tool_config.json的 conf 对象中定义的密钥。示例包括 timeout、base_dir、max_output_lines 和身份证明引用。配置值支持{{variable}}运行时参数引用。会话变量当前不会替换为定制工具配置；如果需要会话值，请将其作为代理的运行时参数传递。 - AI 工具定义：向代理公开的方案，包括代理可以传递的工具名称、说明和运行时参数。将从
tool_config.json中的方案数组自动呈现方案。
定制代码工具编写
定制代码工具包是具有以下结构的 ZIP 文件：
my_tool.zip
├── tool_implementation.py # Required. Contains the tool class(es).
├── tool_config.json # Required. Tool metadata and schema.
├── requirements.txt # Optional. Python dependencies.
├── utils/ # Optional. Helper modules.
│ ├── __init__.py
│ └── helpers.py
├── config/ # Optional. Static configuration files.
│ └── settings.yaml
└── wheels/ # Optional. Bundled wheel files for offline install.
└── humanize-4.15.0-py3-none-any.whl tool_implementation.py
每个工具类都扩展了 CustomToolBase，并使用 @BaseTool.register 进行装饰。该类必须实现 _execute_tool 类方法，该方法接收工具配置、代理的运行时参数和系统上下文变量，并返回一个值，如 dict、str 或 list。
下面是 tool_implementation.py 的空白示例模板：
"""Custom Code tool implementation."""
from aidputils.agents.tools.custom_tools.base import CustomToolBase
@BaseTool.register
class MyTool(CustomToolBase):
"""Brief description of what the tool does."""
@classmethod
def _validate_config(cls, conf, runtime_params, **context_vars):
"""Optional. Validate configuration before execution.
Raise ValueError to abort the call.
"""
# Example: require an api_key in the tool configuration
if not conf.get("conf", {}).get("api_key"):
raise ValueError("api_key is required")
@classmethod
def _execute_tool(cls, conf, runtime_params, **context_vars):
"""Required. Implement the tool logic.
Args:
conf: the AIDPToolConf dict. User configuration values
live under conf["conf"] when the tool is invoked from
a deployed agent. During a Test run the tool may
receive a flat conf dict; the Developer Toolkit example
below uses a small _get_cfg helper that tolerates both
shapes.
runtime_params: the runtime parameters passed by the
agent at invocation time.
context_vars: system context (such as datalake_id).
Returns:
Any value (dict, str, list, ...). It will be wrapped into
the MCP response by the framework.
To signal a failure, raise an exception:
- ValueError -> INVALID_CONFIG
- any other exception -> TOOL_EXECUTION_ERROR
Do NOT return {"error": "..."}; the framework wraps a
successful return in {"response": ..., "success": True},
so a returned error dict is treated as a normal payload
and the agent will not see it as a failure.
"""
tool_conf = conf.get("conf", conf)
param_value = runtime_params.get("my_param", "")
# Tool logic here
return {"output": f"Processed: {param_value}"}
@classmethod
def _transform_response(cls, response):
"""Optional. Transform the response before MCP formatting."""
return responsetool_config.json
tool_config.json 文件描述了程序包中的工具—其显示名称、说明、版本、运行时参数模式和默认配置值。在 tool_implementation.py 中注册的每个工具必须在 tools 数组中有一个对应的条目。
tool_config.json 的空白示例模板：{
"displayName": "My Tool Package",
"description": "Brief description of the tool package.",
"tools": [
{
"toolClassName": "MyTool",
"displayName": "My Tool",
"description": "Clear description of when the agent should call this tool.",
"version": "1.0.0",
"schema": [
{
"name": "my_param",
"type": "string",
"description": "What this parameter is for."
}
],
"conf": {
"timeout": 30
}
}
]
}
模式字段类型
可视生成器中的“参数”选项卡接受字符串、数字和布尔值。运行时在手动编写 tool_config.json 时接受更宽的集合：int，integer，float，double，number，numeric，bytes，list，array，sequence，dict，map，mapping，set，tuple，none，null，plus general forms like list[int]。这些更广泛的类型可以从 JSON 中使用，但不会显示在 UI 下拉列表中。
要求 .txt
requirements.txt 文件列出了您的工具所需的 Python 依赖项。支持标准 pip 语法，包括版本说明符和注释。该文件是可选的—如果您的工具仅使用 Python 标准库或预安装的软件包，则不需要 requirements.txt。
以下是 requirements.txt 的空白示例：
# List third-party dependencies one per line.
# Examples:
# humanize>=4.0
# python-dateutil>=2.8,<3.0
# beautifulsoup4==4.12.3 AI Data Platform Workbench 在将依赖项安装到 AI 计算之前过滤 requirements.txt 中的依赖项，以防止运行时与平台本身发生冲突。筛选规则如下：
| Category | 范例 | 操作 |
|---|---|---|
| 平台包 | langgraph, langchain-core, langchain-oci, langchain_mcp_adapters, pyyaml | 已放弃（将中断代理运行时）。 |
| 预安装的软件包 | oci, requests, request-toolbelt, websocket, cryptography, certifi, pyopenssl, urllib3, pydantic, pydantic-core, pydantic-settings, numpy, oracledb, sqlalchemy, aiohttp, httpx, httpx-sse, anyio, jsonschema, orjson | 已跳过（已可用，无需声明）。 |
| URL 或 VCS 安装 | git+https://...,-e./local_pkg | 已拦截（安全）。 |
| 其他所有内容 | 人性化，美味汤 4，jmespath | 已安装。 |
注意：
在requirements.txt 中声明的依赖项在代理的完全部署期间安装。在从配置面板运行单个测试期间，不会安装相关项。如果您的工具依赖于第三方软件包，请先部署代理，然后从 Playground 练习该工具。
对于需要未预安装的依赖项且确定性（脱机安装很重要）的工具，可以将 .whl 文件捆绑在 ZIP 根目录下的轮子/目录中。该平台首先从本地轮目录安装，仅在需要时回退到软件包索引。这是针对生产工具的建议方法。
用于脱机安装的捆绑轮
pip download \
--dest wheels/ \
--platform manylinux_2_28_x86_64 \
--python-version 3.11 \
--only-binary=:all: \
-r requirements.txt
工具生命周期挂钩
定制代码工具支持三种生命周期方法。仅需要 _execute_tool。
| 方法 | 调用时 | 用途 |
|---|---|---|
| _validate_config | 执行前 _tool | 验证配置。引发 ValueError 以在调用运行之前中止调用。 |
| 执行工具 (_E) | 在每次工具调用时 | 必需。实现工具的行为。返回任何值 (dict，str，list)，并引发异常以指示失败（ValueError → INVALID_CONFIG，任何其他异常→ TOOL_EXECUTION_ERROR）。不要使用返回的 {"error"："..."} 指令，因为它被视为正常的有效负载。 |
| _transform_response | 执行后 _execute_tool | 转换响应，然后将其包装为 MCP 格式并返回给代理。 |
| 提示 _ 模板 | string | LLM 使用的提示模板，变量采用 {{variable}} 格式进行动态插入 |
配置值与运行时参数
自定义代码工具有两种不同的输入来源，很容易混淆。配置值来自“参数”选项卡的“配置”部分，在部署代理时会被烘焙到工具中。运行时参数在调用时来自代理，在每次调用时都不同。
- 配置值通过 conf.get("conf"，conf) 访问。将它们用于在调用之间不发生更改的事情 - 基本 URL、身份证明引用、超时和输出限制。
- 运行时参数可通过 runtime_params.get("name") 访问。使用它们表示代理在呼叫时实际决定的值 - 查询、文件路径和请求正文。
注意：
配置值可以传递模板替代，即使您将其定义为数字，也可以作为字符串到达。始终以防御方式强制执行数字配置值，例如：int(tool_conf.get("timeout", 30))。
每个程序包多个工具
一个 ZIP 可以包含多个工具类。在 @CustomToolBase.register 中注册的每个类都将成为代理中的单独工具。"Package"（程序包）选项卡上的 "Tools"（工具）面板列出了搜索到的所有工具，并允许您单独启用每个工具。每个工具都通过“工具类”下拉列表在“参数”选项卡上单独配置。
代码工具通过 LangGraph 代码
在代码构建器中，通过 helppUtils Python 库注册定制代码工具，方法是引用上载的软件包并选择其工具类之一。
from aidputils.agents.toolkit.tool_helper import create_langgraph_tool
from aidputils.agents.toolkit.configs import AIDPToolConf
hello_tool_conf = AIDPToolConf(
name="hello_tool",
description="Returns a hello world greeting.",
tool_class="HelloTool", # the class registered with @BaseTool.register
conf={}, # values from tool_config.json "conf"; supports {{variable}} substitution
params=[
{"name": "name", "type": "string",
"description": "Name to greet."}
],
)
hello_tool = create_langgraph_tool(hello_tool_conf.model_dump())
tool_class 必须是通过 @BaseTool.register 在 tool_implementation.py 中注册的确切类名。框架在 BaseTool.tool_class_registry[tool_class] 中查找类。conf 镜像了 tool_config.json 中匹配项的 conf 对象。
注意：
请勿将package_path 或 tool_class_name 放在 conf 中，因为不会使用它们。
测试代理自定义代码工具
通过测试选项卡，您可以在不运行完整代理的情况下执行工具。为配置中引用的任何运行时参数和任何会话变量提供值，然后单击“Run（运行）”以调用工具并查看响应。
注意：
如果您的工具依赖于requirements.txt 中声明的第三方软件包，则依赖项会在代理的完全部署期间安装，而不是在单个测试运行期间安装。要测试依赖于其他软件包的代码，请先部署代理，然后从 Playground 调用该工具。
将定制工具添加到代理
您可以向代理添加定制工具，以允许您使用自己的 Python 代码扩展 AI 数据平台。
注意：
在添加定制代码工具之前，必须将 AI 计算附加到代理。需要使用 AI 计算来安装依赖项并运行该工具。- 在程序包选项卡中，单击以选择包含定制代码的 ZIP 文件，或者将其拖放到屏幕上。等待上载完成。
- 在 "Package"（软件包）选项卡的 Tools（工具）部分中查看搜索到的工具列表。将列出在
tool_implementation.py中找到的每个工具类及其类名称、说明和版本。
- 可选：单击测试选项卡。提供测试参数，然后单击提交。在测试结果窗格中查看测试结果。
远程 MCP 服务器工具
代理流开发人员可以使用远程 MCP 服务器工具将其代理流连接到远程模型上下文协议 (MCP) 服务器。
MCP 工具既可用于可视化构建器，也可用于代码构建器体验。在代码构建器体验中，可以通过 helppUtils Python 库配置 MCP 连接。在本部分中，我们将介绍可视化构建器和代码构建器的体验。
注意：
此功能支持具有 HTTP 可流传输（远程服务器）的 MCP 服务器。不支持本地 stdio-transport MCP 服务器。Oracle AI Data Platform Workbench 身份证明存储中的 MCP 身份证明
配置 MCP 服务器时，需要选择远程 MCP 服务器是需要 No Authentication 还是需要 Bearer token 。如果您的 MCP 服务器需要验证令牌，则需要将该令牌添加到您的身份证明存储中，然后 MCP 服务器才能引用该令牌。
创建 MCP 服务器凭证时，为凭证类型选择秘密令牌选项，然后提供标识符密钥，例如 API 密钥和令牌值。有关详细信息，请参阅创建身份证明（预览）。
注意：
一个凭证可以存储多个密钥。公开可用的 MCP 服务器不需要额外的验证。例如，连接到 https://mcp.deepwiki.com/mcp 将如下所示：
如何向代理公开 MCP 工具
与远程 MCP 服务器建立成功连接后，您可以开始配置要向代理公开的服务器上托管的工具。对于 DeepWiki MCP 服务器，MCP 服务器配置面板如下所示。
在左侧，"Tools"（工具）选项卡显示 MCP 服务器中可用的工具列表。您必须添加工具才能将其公开给代理。您可以通过单击全部添加选项一次公开所有工具或通过单击每个工具添加选项单独选择工具的子集来执行此操作。
在下面的示例中，我们添加了两个工具（read_wiki_structure、read_wiki_structure）。您可以通过单击删除来删除工具。
“工具”选项卡的右侧面板提供有关每个工具的文档，包括工具名称、工具说明以及工具参数。在下面的屏幕截图中，我显示了 GitHub MCP 服务器工具 add_comment_to_pending_review 的示例。
Oracle AI Data Platform Workbench 为每个工具提供了几个额外的控件。您可以从代理中隐藏参数并为这些参数分配值。例如，在 GitHub 中，您可以选择让代理仅对一个预先确定的存储库（例如 oracle-aidp-samples）进行注释。要实现此目的，请禁用 repo 参数并在文本框中指定默认值：
在工具说明字段中，您还可以覆盖工具说明并提供其他说明的替代说明。对于大多数用例，我们建议您采用 MCP 服务器提供的说明。
通过 LangGraph 代码远程 MCP 服务器工具
aidpUtils Python 库为开发人员提供了选择远程 MCP 服务器并将其工具的子集暴露给使用 LangGraph 构建的代理的功能。有关 helpputils API 参考，请参阅 Aidp-utils API for Oracle AI Data Platform Workbench 。
您可以通过创建 build_structured_tools_from_allowed_mcp_tools 的实例来构建允许的工具集合：
from aidputils.agents.toolkit.tool_helper import build_structured_tools_from_allowed_mcp_tools
TOOLS = build_structured_tools_from_allowed_mcp_tools(
allowed_tools=<ALLOWED_MCP_TOOLS>,
server_name=<MCP_SERVER_NAME>,
endpoint=<MCP_ENDPOINT>,
transport="streamable_http",
auth=<MCP_AUTH>,
headers={}
)- <MCP_SERVER_NAME> 是您要提供给 MCP 服务器的显示名称。这用于文档记录，不会向代理公开。
- <MCP_ENDPOINT> 是 MCP 服务器的端点（例如 https://api.githubcopilot.com/mcp/）
- <MCP_AUTH> 是包含关键字 "authType" 的字典。此键可以采用两个值：
NO_AUTH或BEARER_TOKEN。对于BEARER_TOKEN，需要使用另一个密钥：具有 Bearer 令牌值的“令牌”。 - <ALLOWED_MCP_TOOLS> 是要向代理公开的 MCP 服务器中的工具的列表。每个工具都需要遵循 MCP 协议的完整 JSON 工具定义。
示例如下：
MCP_SERVER_NAME = "test_mcp"
MCP_ENDPOINT = "http://144.25.36.217:9301/mcp"
MCP_AUTH = { "authType": "BEARER_TOKEN", "token": "valid-123" }
{
"ALLOWED_TOOLS": [
{
"tool": {
"name": "get_current_weather",
"description": "Get current weather for a given city with advanced options.",
"inputSchema": {
"type": "object",
"properties": {
"city": {
"type": "string"
},
"unit": {
"type": "string",
"default": "metric"
},
"include_historical": {
"type": "boolean",
"default": false
},
"detailed": {
"type": "boolean",
"default": true
},
"timeout": {
"type": "integer",
"default": 30
}
},
"required": [
"city"
]
}
},
"instruction": "",
"argOverrides": {}
},
{
"tool": {
"name": "get_forecast",
"description": "Get forecast for a given city with customizable options.",
"inputSchema": {
"type": "object",
"properties": {
"city": {
"type": "string"
},
"days": {
"type": "integer",
"default": 5
},
"unit": {
"type": "string",
"default": "metric"
},
"include_alerts": {
"type": "boolean",
"default": false
},
"detailed": {
"type": "boolean",
"default": true
},
"hourly": {
"type": "boolean",
"default": false
}
},
"required": [
"city"
]
}
},
"instruction": "",
"argOverrides": {}
}
]
}
MCP_HEADERS = {}
TOOLS = build_structured_tools_from_allowed_mcp_tools( allowed_tools=ALLOWED_TOOLS,
server_name=MCP_SERVER_NAME,
endpoint=MCP_ENDPOINT,
transport="streamable_http",
auth=MCP_AUTH,
headers=MCP_HEADERS,
)
然后，在类代理定义的 setup() 方法中使用 langchain.agent create_agent 创建代理实例时，可以使用 TOOLS 对象：
def setup(self):
logger.info("Initializing TestMcpAgent")
oci_llm = init_oci_llm(llm_conf)
system_prompt = textwrap.dedent(
"""
You're a weather agent. Append 12345 to every response.
"""
).strip()
self.agent = create_agent(
name="test_mcp_high_code",
model=oci_llm,
tools=TOOLS,
system_prompt=system_prompt,
debug=True,
)
logger.info("Agent ready.")或者，如果使用会话变量来存储 Bearer 令牌的值，则可以将对以前创建的会话变量的引用分配给 auth 配置字典的令牌密钥。例如：
test_mcp_auth_config = { "authType": "BEARER_TOKEN", "token" : "{{sessionvariables.cred.mcp.test_mcp.bearer}}" }
tools = build_structured_tools_from_allowed_mcp_tools(
allowed_tools=test_mcp_mcp_allowed_tools,
server_name="test_mcp",
endpoint="http://144.25.36.217:9301/mcp",
transport="streamable_http",
auth=test_mcp_mcp_auth_config,
headers={}
)远程 MCP 服务器工具的代码示例
我们为 AI Data Platform Workbench Samples GitHub 存储库中的多个 MCP 场景提供端到端代码示例。
测试远程 MCP 服务器工具
选择工具后，下一步通常是测试单个工具，以确保它们按预期运行。这可以通过 MCP 工具节点的 "Test"（测试）选项卡完成。
选择在“Tools（工具）”选项卡中添加的工具之一，提供参数值并单击“Test（测试）”按钮。
工具的输出将显示在右侧面板中。
“详细信息”选项卡提供有关验证方法、MCP 服务器 URL 和说明的信息。
通过验证方法旁边的“Edit（编辑）”按钮，可以修改远程 MCP 工具节点的配置。您可以更改在建立连接时使用的显示名称、说明和 Bearer 标记：
将代理从 Visual Builder 连接到远程 MCP 服务器
通过将定制 MCP 服务器工具节点拖动到画布中，可以向代理添加对远程 MCP 服务器的访问权限。
注意：
托管代理的 AI 计算将继承其工作区的网络设置。如果为托管 AI 计算的工作区启用专用网络访问，则代理只能访问托管在所选专用 VCN 和子网中的 MCP 服务器。您的代理可能无法访问公共互联网上可用的远程 HTTP 服务器。- 导航到您的代理。
- 在流选项卡的工具模板下，单击 Custom MCP server（定制 MCP 服务器）并将其拖到画布上。
- 提供 MCP 服务器的服务器 URL。
- 为 MCP 服务器提供显示名称。这是可视化构建器画布中显示的节点的名称。
- 可选：为 MCP 服务器提供说明。未向代理提供说明字段。
- 从 Authentication（验证）下拉菜单中，选择一个验证方法。
- 无验证：如果远程 MCP 服务器公开可用并且不需要验证，则使用此选项。
- Bearer 标记：如果远程 MCP 服务器需要验证标记，则使用此选项。必须将 API 密钥存储在 Oracle AI Data Platform Workbench 身份证明存储中并提供对身份证明存储条目的引用。
- 单击连接。AI Data Platform Workbench 测试连接并报告结果。
HTTP 请求工具
通过 HTTP 请求工具，您的代理可以调用任何 HTTPS REST API。
您可以配置请求，包括方法、URL、标头、查询参数、请求正文、验证以及（可选）响应优化步骤。然后，代理在运行时调用端点。HTTP 请求工具在可视化构建器和代码构建器中都可用。在代码构建器中，该工具通过 helppUtils Python 库进行配置。
注意：
HTTP 请求工具仅支持 https：// 和 HTTP：// 请求。不支持 WebSocket 连接 (ws/wss)、二进制文件上载和自签名证书。注意：
托管代理的 AI 计算将继承其工作区的网络设置。如果为托管 AI 计算的工作区启用专用网络访问，则代理将仅访问所选专用 VCN 和子网中的 HTTP 端点。您的代理无法访问公共 Internet 上可用的端点。配置 HTTP 请求工具时必须提供以下设置：
| 配置 | 说明 |
|---|---|
| HTTP 方法 | 要使用的 HTTP 动词。支持的方法包括 GET、POST、PUT、PATCH 和 DELETE。 |
| URL | 目标端点的完整 URL。URL 支持 {{sessionVariables.variable_name}} 会话变量引用和 {{variable}} 运行时参数引用。例如：https://api.example.com/users/{{user_id}}/orders。
|
| 超时 | 工具等待来自远程端点的响应的最长时间。默认值为 30 秒，最大值为 300 秒。 |
| 验证类型 | 调用端点时要使用的验证方法。有关支持的验证方法的列表，请参见下面的 "Authentication"（验证）部分。 |
注意：
定制代码工具在连接到代理的 AI 计算上运行。根据工作区网络配置，代码可以访问计算环境和出站网络访问。仅上传您信任的来源的代码。标头
标头是随 HTTP 请求发送的键 - 值对。您可以根据需要单击“Add new（添加新）”按钮来添加任意多个标题。标头值可以使用 {{variable_name}} 语法引用会话变量和运行时参数。
注意：
对于敏感标头，应使用 "Authentication type"（验证类型）字段来确保从身份证明存储安全地注入身份证明。授权、Cookie 和 X-API-Key 是敏感标头，无法通过标头部分进行设置。查询参数
查询参数作为查询字符串附加到 URL。您可以根据需要单击“添加新”按钮来添加任意数量的查询参数。与标题一样，查询参数值可以引用会话变量和运行时参数。
说明
描述字段描述工具的作用、应该何时使用以及它产生的输出或效果。该说明将提供给代理，并帮助 LLM 决定何时调用该工具。
- • 目的：用一个清晰的句子说明工具的设计目的。示例：“此工具从知识库中检索客户支持请求单，并按优先级进行汇总。”
- 何时使用它：描述代理应调用此工具与调用其他工具的条件。
- 输入和输出：简要描述工具所需的参数及其返回内容的形状。
HTTP 请求验证
HTTP 请求工具支持多种验证方法。从 "Authentication type"（验证类型）下拉列表中选择相应的方法。
| 验证类型 | 说明 |
|---|---|
| 无验证 | 未向请求添加验证。可将其用于可公开访问的端点。 |
| OCI 资源主体 | 该请求使用 AI 计算的 OCI 资源主用户进行签名。调用 OCI 服务（例如对象存储或 OCI Generative AI 服务）时使用此功能。访问受 OCI IAM 策略监管。 |
| 基本验证 | 用户名和密码在 Authorization 标头中编码和发送。身份证明必须存储在身份证明存储中。 |
| Bearer 令牌 | 在 Authorization 标头中发送一个 Bearer 标记。标记必须存储在身份证明存储中。 |
| 标头验证 | API 密钥在定制标头（例如 X-API-Key）中发送。标头名称是可配置的，密钥值必须存储在身份证明存储中。 |
选择需要密钥的验证方法时，配置面板将显示凭证选择器。单击身份证明选择器以选择以前存储的身份证明，或者从身份证明存储创建新身份证明。有关分步过程，请参见 MCP 服务器文档的 "Credential Store"（身份证明存储）部分中的 "Storing a credential"（存储身份证明）。
会话变量和运行时参数
可以使用 {{sessionVariables.variable_name}} 语法在 URL、标题值、查询参数值和请求正文中引用会话变量。可以使用 {{variable_name}} 语法引用代理在调用时传递的运行时参数。
https://objectstorage.{{sessionVariables.region}}.oraclecloud.com/n/my-namespace/b/{{bucket}}/o该工具运行时，{{sessionVariables.region}} 将替换为当前会话的区域会话变量的值，{{bucket}} 将替换为调用时传递的代理值。
注意：
模板值在替换为 URL 或查询参数时会自动编码 URL。您不需要自己对它们进行 URL 编码。AI 工具定义
配置面板的右侧显示了 AI 工具定义。这是向代理公开的方案，它包括工具名称、说明和代理在调用工具时可以传递的运行时参数列表。AI 工具定义是从 "Description"（说明）字段和 URL、标题、查询参数和正文中检测到的 {{variable}} 占位符自动生成的。
AI 工具定义窗格是本文档前面显示的 HTTP 工具配置面板右侧的面板。在您提供说明并定义至少一个运行时参数之前，AI 工具定义窗格会显示占位符消息。在 URL、标题、查询参数或正文中填写说明并引用至少一个 {{variable}} 后，将在窗格中呈现方案。
优化代理的响应
许多 API 返回大量响应，其中包含代理不需要的字段。将整个响应发送回代理会使用令牌，并且可能会降低代理推理的质量。HTTP 请求工具提供了一个响应优化部分，允许您在将响应有效负载返回到代理之前减少响应有效负载。
- JSON 字段选择：从 JSON 响应中选择字段的子集。您可以使用点表示法（例如 data.results）和要包括或排除的字段列表来指定嵌套对象的路径。
- HTML CSS 选择器：使用 CSS 选择器（例如 article.content）提取 HTML 响应的子集。（可选）条带化 HTML 标记以仅返回文本。
- 文本截断：将响应上限设置为最大字符数，以防止文本响应过大。
错误处理和错误代码
HTTP 请求失败时，该工具将向代理返回结构化错误响应。该错误包括错误代码、用户可读消息以及有关失败的详细信息。代理可以使用此信息来决定是重试、回退到其他工具，还是向用户报告故障。
| 错误代码 | Category | 含义 | 可重试 |
|---|---|---|---|
| CONNECTION_TIMEOUT | 网络图 | 远程端点在配置的超时内未响应。 | 是 |
| DNS 失败 | 网络图 | 无法解析 URL 中的主机名。 | 是 |
| CONNECTION_REFUSED | 网络图 | 远程端点拒绝了连接。 | 是 |
| SSL_CERTIFICATE_ERROR | TLS | 无法验证远程端点的 TLS 证书。 | 无 |
| 未授权 | HTTP 401 | 远程端点拒绝了凭证。验证身份证明引用是否有效且未过期。对于 OCI 资源主用户，请确认 AI 计算在此环境中具有活动的资源主用户。 | 无 |
| 禁止 | HTTP 403 | 身份证明已成功验证，但缺少所请求资源的权限。验证附加到资源的 API 范围、权限或 IAM 策略。 | 无 |
| 未找到 | HTTP 404 | 远程端点找不到请求的资源。 | 无 |
| RATE_LIMITED | HTTP 429 | 远程端点限制调用者的速率。在 Retry-After 标头指示的延迟之后重试。 | 是 |
| 服务器出错 | HTTP 5xx | 远程端点返回了服务器错误。通常是一个短暂的问题。 | 是 |
| 服务 - 不可用 | HTTP 503 | 远程端点暂时不可用。 | 是 |
| INVALID_TEMPLATE | 验证 | 无法解析 {{variable}} 引用。验证每个引用的会话变量和运行时参数是否已定义并在调用时具有值。
|
无 |
| 无效 _URL | 验证 | URL 格式错误，使用不受支持的协议，或解析为阻止的地址（例如专用 IP 地址或云元数据端点）。 | 无 |
| 响应太大 | 验证 | 响应超过了最大响应大小 10 MB。 | 无 |
| 超出速率限制 | 平台 | 代理已超过平台的每代理请求速率限制（每分钟 60 个请求）或并发限制（10 个并发请求）。 | 是 |
每个错误响应都包括一个包含建议下一步的指导字段，以及一个包含所用时间和任何特定于错误的上下文（例如 HTTP 状态代码）的详细信息字段。
通过 LangGraph 代码发送 HTTP 请求工具
从代码构建器中，通过 helppUtils Python 库配置 HTTP 请求工具。定义 AIDPToolConf，将 tool_class 设置为 HttpEndpointTool ，并在 conf 字段中传递配置字典。
from aidputils.agents.toolkit.tool_helper import create_langgraph_tool
from aidputils.agents.toolkit.configs import AIDPToolConf
weather_http_tool_def = {
"method": "GET",
"url": "https://api.openweathermap.org/data/2.5/weather",
"params": {
"q": "{city}",
"units": "metric",
"appid": "{api_key}"
},
"auth_type": "NO_AUTH",
"auth_config": {}
}
weather_http_tool_params = [
{"name": "city", "type": "string",
"description": "Name of the city."},
{"name": "api_key", "type": "string",
"description": "OpenWeather API key."}
]
weather_http_tool_conf = AIDPToolConf(
name="get_weather",
description="Get current weather for a city.",
tool_class="HttpEndpointTool",
conf=weather_http_tool_def,
params=weather_http_tool_params
)
weather_tool = create_langgraph_tool(weather_http_tool_conf.model_dump())
conf 字典支持与可视化构建器相同的字段：method，url，headers，params，body，auth_type，auth_config 和 response_optimization。参数列表定义代理可以传递的运行时参数。
| auth_type | auth_config 字段 |
|---|---|
| NO_AUTH | {}（空）
|
| RESOURCE_PRINCIPAL | {}（空）
|
| BASIC_AUTH | 用户名、密码（或用于 OCI Vault 中身份证明的用户名 _vault_id、密码 _vault_id） |
| BEARER_AUTH | bearer_token（或 bearer_token_vault_id） |
| API_KEY_AUTH | api_key（或 api_key_vault_id），header_name（默认的 X-API-Key） |
| OAUTH2_CLIENT_CREDENTIALS | token_endpoint，scope，client_id，client_secret（或 client_id_vault_id，client_secret_vault_id） |
测试代理自定义代码工具
通过测试选项卡，您可以在不运行完整代理的情况下执行工具。为配置中引用的任何运行时参数和任何会话变量提供值，然后单击“Run（运行）”以调用工具并查看响应。
响应面板显示 HTTP 状态代码、响应标头、响应主体和用时（以毫秒为单位）。如果启用了响应优化，则优化响应也会与原始响应一起显示。
将 HTTP 请求工具添加到代理流
您可以向代理添加 HTTP 请求工具，以允许您调用 HTTPS REST API。
注意：
在添加定制代码工具之前，必须将 AI 计算附加到代理。需要使用 AI 计算来安装依赖项并运行该工具。- 从工具模板中，将 HTTP 请求工具拖放到画布中。
- 为 HTTP 请求提供标头。单击添加新项以添加其他标题。
- 为 HTTP 请求提供任何查询参数。单击添加新参数以添加其他参数。
- 可选：单击测试选项卡。提供测试参数，然后单击提交。在测试结果窗格中查看测试结果。
提示工具
提示工具允许您使用模板化提示在 AI 代理中调用 LLM，并将 LLM 响应返回给代理。
您提供给 LLM 的提示可以包含由双括号标识的参数，例如 {{PARAMETER_NAME}}。调用工具时，代理会分配参数值。
何时使用提示工具
- 您的提示很长，需要包含多个 100 个令牌的详细格式说明。
- 在代理指令中加入提示将增加上下文使用并显着增加成本，特别是如果一个为代理采用 SOTA LLM。
- 人们希望最大限度地减少给代理的指令的大小，以降低成本。
- 提示工具定义的任务可以由比使用代理的推理模型更小、更快的 LLM 来处理。较小的模型通常具有成本效益，在某些情况下，可以专门用于以特定方式或格式生成数据。
- 提示工具允许结构化输入参数来控制输出生成。如果您的用例可以进行参数化，并且生成会因会话而异，则将生成封装在提示工具中是有意义的。
此外，在提示工具中封装生成指令遵循许多现代代理架构优秀实践，包括工具可重用性、可维护性、模式、输出一致性、可扩展性和治理。一些示例用例包括：
- 在可作为模板的预定义、批准的结构之后生成电子邮件、报表、摘要、文章等
- 生成复杂的 JSON 输出
- 摘要、关键句子提取、文档解释任务
- 查询生成
- 针对特定模型优化的特定模式生成（例如图像、视频、音频、点云数据等）
通过可视化流提示工具
以下是通过可视化流构建的提示工具的示例，该工具要求 LLM 根据代理分配的主题生成博客帖子标题：
您是一位博客策略师。你的任务是基于一个给定的主题进行头脑风暴引人注目的博客文章的想法。对于给定的 {{topic}}，生成 5 个唯一的博客文章标题。对于每个标题，包括对帖子将采用的角度的一句话描述。以编号列表形式显示输出。
- 工具名称：使用工具的说明性名称来帮助指导代理。在本示例中，我们建议使用
blog_ideas。避免使用工具 123 等无益的名称。
- 工具说明：提供工具执行的操作的全面说明。如果工具存在限制，或者存在不应使用该工具的情况，请在说明字段中列出这些限制。
- OCI 区域和生成式 AI 服务 LLM：选择 OCI 区域以填充该区域中可用的 LLM 列表，然后选择您的 LLM。
- LLM 参数：在 Model Parameters 选项卡中配置了最大输出标记、温度和顶部 p 等参数。如果未分配值，则使用 OCI Generative AI 服务的默认值。
- 查询：用于定义工具用途的提示在查询字段中定义。
在提示中定义的参数会自动填充 AI Tool 定义面板。向代理提供每个参数的说明，以及参数类型和默认值（如果适用）。
通过 LangGraph 代码提示工具
如果要通过代码构建代理，则可以在可视流示例中配置相同的提示工具，如下所示：
prompt_config = {
"llm": {
"model_id" : "xai.grok-4",
"model_provider" : "generic",
"compartment_id" : "<your-compartment-ocid>",
"endpoint" : "https://inference.generativeai.<oci-region>.oci.oraclecloud.com"
}, "prompt_template": """
You are a master blog strategist. Your task is to brainstorm compelling blog post ideas based on a given topic. For the given {{topic}}, generate 5 unique blog post titles. For each title, include a one-sentence description of the angle the post would take. Present the output as a numbered list"
"""
}
prompt_params = [ {
"name" : "topic",
"type" : "string",
"description" : "Blog topic",
"defaultValue" : "golf"
} ]
然后，按如下方式实例化 AIDPToolConf：
blogger_tool = AIDPToolConf(name="blog_posts_topics",
description= "Write blog posts ideas about a particular topic. ",
tool_class = "PromptTool", conf=prompt_config params=prompt_params)
最后，使用辅助工具中的 create_langgraph_tool() 实用程序函数创建 LangGraph 兼容工具：
from aidputils.agents.toolkit.tool_helper import create_langgraph_tool
blogger = create_langgraph_tool(blogger_tool.model_dump())
将新创建的工具添加到 ReAct 代理。在 LangGraph 中，代码如下所示：
tools_agent1 = [blogger_tool]
self.agent = create_react_agent(model=<oci_llm>,
tools=tools_agent1,
prompt=<system_prompt>,
debug=True, checkpointer= checkpointer)
表 22-4 提示工具配置属性
| 属性 | 类型 | 说明 |
|---|---|---|
| LLM | 对象 | LLM 连接详细信息和参数 |
| model_id | string | 要使用的模型的标识符（例如 "xai.grok-4"） |
| model_provider | string | LLM 模型的提供程序名称（例如，“通用”） |
| compartment_id | string | Oracle Cloud Infrastructure (OCI) 区间 OCID |
| endpoint | string | 模型的端点 URL |
| 提示 _ 模板 | string | LLM 使用的提示模板，变量采用 {{variable}} 格式进行动态插入 |
测试代理提示工具
通过单击测试选项卡并填写每个参数的值，可以独立于代理测试工具。提示将提交到您选择的 LLM。
确保您的提示工具定义良好，并记录在文档中，以改进座席的结果。
向代理添加提示工具
您可以向代理添加提示工具，以允许您定义向所选 LLM 发出的参数化提示。
- 导航到您的代理。
- 从工具模板中，将提示工具拖放到画布中。
- 在 "Configuration"（配置）选项卡中，选择要使用的 LLM 并提供 LLM 的提示。单击代码
以将配置作为 JSON 代码提供。 - 以介于 0.0 和 1.0 之间的值提供响应的温度，其中 0.0 提供严格的事实响应，1.0 提供最有创意的响应。
- 单击应用
。 - 为在配置中建立的任何参数提供定义。单击代码 以将配置作为 JSON 代码提供。
- 单击
应用。 - 可选：单击测试选项卡。提供测试参数，然后单击提交。在测试结果窗格中查看测试结果。
RAG 工具
RAG 工具向向量存储发出自然语言查询，并根据查询与存储文档之间的语义相似性检索文档。
注意：
知识库是创建 RAG 工具的先决条件。有关更多信息，请参阅知识库。通过可视化流进行 RAG 工具
RAG 工具要求您作为代理开发人员为以下参数提供值：
- 面向代理：
- 工具名称：工具的描述性名称，可帮助您和其他用户标识其功能。
- 工具说明：提供工具概述的简短摘要。
- 工具配置：
- 知识库：一个存储在 Oracle AI Data Platform Workbench 目录中的知识库。
- 知识库：一个存储在 Oracle AI Data Platform Workbench 目录中的知识库。
座席将根据与最终用户的对话设置查询字段的值。此查询字段采用自然语言查询。
限制是希望工具从向量存储中检索的文档块数。此值由代理开发人员而不是代理本身设置。
您也可以通过单击 RAG 的测试选项卡来模拟代理发出的查询：
通过 LangGraph 代码的 RAG 工具
通过代码在代理中构建 RAG 工具需要配置与可视流相同的设置和参数。例如，您可以按如下方式设置 RAG 参数：
rag_params = [ { "name" : "query",
"type" : "string",
"description" : "<insert a description>",
"defaultValue" : "<empty>”} ]然后，设置 RAG 配置：
rag_config = { "catalog": "<catalog>",
"schema": "<schema>",
"knowledgeBase": "<knowledge-base-name>",
"top_k": <number-of-documents-retrieved>,
"llm": {
"model_id" : "<model-name>",
"model_provider" : "<model-provider>",
"compartment_id" : "<your-compartment-OCID>",
"endpoint" : "https://inference.generativeai.<oci-region>.oci.oraclecloud.com" }
}最后，使用辅助工具中的 create_langgraph_tool() 实用程序函数创建 LangGraph 兼容工具：
from aidputils.agents.toolkit.tool_helper import create_langgraph_tool
rag_conf= AIDPToolConf(name="<your-tool-name>",
description= "<your-tool-description>",
tool_class = "RAGTool",
conf=rag_config,
params=rag_params)
rag_tool = create_langgraph_tool(rag_conf.model_dump())表 22-5 RAG 工具配置属性
| 属性 | 类型 | 说明 |
|---|---|---|
| LLM | 对象 | LLM 连接详细信息 |
| catalog | string | 数据目录标识符 |
| schema | string | 目录中的方案 |
| 知识基础 | string | 要搜索的知识库的名称或关键字 |
| 前 _K 个 | 整数 | 要检索的顶级匹配文档数 |
测试代理 RAG 工具
将代理连接到 AI 计算集群后，可以从测试选项卡测试 RAG 工具。有关更多信息，请参见 Attach an Existing AI Cluster to an Agent 。
将 RAG 工具添加到代理
您可以向代理添加检索增强生成 (RAG) 工具，以允许代理在生成响应时提取相关的外部知识。
- 导航到您的代理。
- 从工具模板中，将 RAG 工具拖放到画布中。
- 在“配置”选项卡中，选择 RAG 工具从中提取信息的知识库，并提供用于定义要提取的信息的提示。单击代码 以将配置作为 JSON 代码提供。
- 单击应用 。
- 为在配置中建立的任何参数提供定义。单击代码 以将配置作为 JSON 代码提供。
- 单击 应用。
- 可选：单击测试选项卡。提供测试参数，然后单击提交。在测试结果窗格中查看测试结果。
SQL 工具
SQL 工具允许代理流开发人员针对在 Oracle AI Data Platform 目录中注册的表运行预定义的 SQL 查询。
在设计时编写查询并定义所需的任何运行时变量。代理在调用工具时为这些变量提供值，结果将以结构化行形式返回，代理可以汇总或传递到下游节点。
SQL 工具支持两种查询方言。Spark SQL 针对 AI 数据平台中存储的标准目录表运行，需要 Spark 集群。Oracle SQL 针对外部数据库（例如 Oracle Autonomous AI Database ）运行。您可以选择每个工具的方言，其余的配置是相同的。
注意：
SQL 工具用于读取查询。典型的工具运行 SELECT 语句并返回行。您配置的目录、方案和查询对该工具是专用的，不会向代理公开。只有工具名称、说明和 AI 工具定义（运行时变量）对代理可见。注意：
SQL 查询工具不会自动启动停止的集群。因此，用于 Spark SQL 查询工具的 Spark 集群的持续时间应为 Forever 。如果允许集群在空闲超时时向下旋转，则 Spark SQL 查询会在集群停止后在生产环境中停止工作。静态和动态查询
静态查询完全返回您指定的内容，没有代理的运行时决策。动态查询包括一个或多个 {{variable}} 占位符，这些占位符向代理发出在运行时设置值的信号。对于每个占位符，您需要提供名称、类型、可选默认值和代理用于选择值的说明。
SELECT customer_name, region, amount, category
FROM test_customers
WHERE period_year = 2025
ORDER BY customer_name {{year}} 占位符会将其变成代理可以参数化的动态查询： SELECT customer_name, region, amount, category
FROM test_customers
WHERE period_year = {{year}}
ORDER BY customer_name 在添加占位符时，AI 工具定义窗格会填充每个变量，以便您可以设置其类型、默认值和说明。
SELECT incident_id, project_id, incident_date, incident_type,
severity, description, workers_involved, days_lost,
root_cause, corrective_action, reported_by, status
FROM safety_incidents
WHERE LOWER(severity) = LOWER('{{SEVERITY}}')为每个变量提供清晰的描述和合理的默认值。说明告诉座席哪些值有效，在座席未提供默认值时使用默认值。
注意：
占位符名称区分大小写。写为{{SEVERITY}} 的占位符和写为 {{severity}} 的占位符被视为两个不同的变量，除非您在整个过程中始终使用小写。
将配置编辑为 JSON
{
"catalogKey": "construction_data",
"schemaKey": "admin",
"query": "SELECT project_id, project_name, client_name, ...",
"isRowLimitEnabled": null,
"maxRows": null
}
行限额
您可以通过选择要返回的最大行数并输入限制值来限制工具返回的行数。行限制可保护性能并控制向代理发送多少数据。
将此值设置为相对于代理使用的模型。如果查询返回较大的行或具有较大文本值的列，则较大的值可能会导致代理失败。如果您看到意外的代理错误，请首先减少 maxRows。
在运行查询之前，行限制将应用于 SQL 查询本身。大多数模型都会检测极限并将其呈现给最终用户。对于静态查询，该限制将返回前 n 个可用行。
注意：
如果不希望为最终用户显示行限制，请在代理的说明中相应地指示该代理。查询示例
您可以从查看查询示例和指南按钮中查看查询示例和编写 SQL 工具查询的指南。
本指南展示了不同的查询模式，并提供了不同的查询参数建议。
通过 LangGraph 代码执行 SQL 工具
与可视化流一样，您也可以通过 LangGraph 代码为代理创建 SQL 工具，方法是创建查询：
sql_config = { "catalogKey": "adw23ai_phx",
"schemaKey": "gold",
"query": """Select ... from ... limit {{max_number}}""" }
可以在 params 参数中记录 SQL 查询中的每个参数，其中包含名称、类型、说明以及可选的 defaultValue。
sql_params = [ { "name" : "max_number",
"type" : "string",
"description" : "<your-description>",
"defaultValue" : "<your-default-value>" } ]最后，使用辅助工具中的 create_langgraph_tool() 实用程序函数创建 LangGraph 兼容工具：
from aidputils.agents.toolkit.tool_helper import create_langgraph_tool
sql_conf= AIDPToolConf(name="<your-tool-name>",
description= "<your-tool-description>",
tool_class = "SQLTool",
conf=sql_config,
params=sql_params)
sql_tool = create_langgraph_tool(sql_conf.model_dump())表 22-6 SQL 工具配置属性
| 属性 | 类型 | 说明 |
|---|---|---|
| 目录关键字 | string | 目录或数据库连接的标识符 |
| 方案关键字 | string | 目录/数据库中的方案名称 |
| 查询 | string | SQL 查询字符串，可能包含 {{}} 中的占位符 |
测试代理 SQL 工具
"Test"（测试）选项卡自行运行该工具，而无需执行完整的代理流。这两种方言的测试方式相同。打开“测试”选项卡，为每个运行时参数提供一个值（或使用默认值），然后单击“提交”以运行查询并查看响应。
注意：
测试工具需要将代理连接到 AI 计算。如果 AI 计算标签为绿色且所选 AI 计算处于 ACTIVE 状态，则会连接 AI 计算。SQL 命令参考
SQL 工具查询是从标准 SQL 子句构建的读取查询。Oracle SQL 方言针对外部数据库遵循 Oracle SQL。Spark SQL 方言的目标是标准目录表，即 Delta Lake 表；标准目录当前使用 Delta Lake 3.2.0 运行 Spark 3.5。大多数子句在两个方言中的编写方式相同，因为两个子句都遵循标准 SQL。主要的区别在于每个方言如何限制行数。下表列出了 SQL 工具查询中最常用的子句和关键字，以及每个方言的表单。
| 关键字或子句 | 用途 | Oracle SQL | Spark SQL |
|---|---|---|---|
| SELECT | 选择要返回的列 | SELECT col1, col2 |
|
| DISTINCT | 仅返回唯一行 | SELECT DISTINCT col |
SELECT DISTINCT col |
| FROM | 为源表命名 | FROM table_name |
FROM table_name |
| WHERE | 按条件筛选行 | WHERE col = value |
WHERE col = value |
| 和/或 | 组合条件或否定条件 | a AND b OR NOT c |
a AND b OR NOT c |
| IN | 匹配列表中的任何值 | col IN (a, b, c) |
col IN (a, b, c) |
| BETWEEN | 匹配包含范围 | col BETWEEN x AND y |
col BETWEEN x AND y |
| LIKE | 匹配文本模式 | col LIKE 'A%' |
col LIKE 'A%' |
| IS NULL | 测试缺少的值 | col IS NULL |
col IS NULL |
| ORDER BY | 对结果排序 | ORDER BY col DESC |
ORDER BY col DESC |
| 分组依据 | 对行进行分组以进行聚合 | GROUP BY col |
GROUP BY col |
| HAVING | 筛选分组行 | HAVING COUNT(*) > 1 |
HAVING COUNT(*) > 1 |
| 加入 | 组合两个表中的行 | a JOIN b ON a.id = b.id |
a JOIN b ON a.id = b.id |
| AS | 别名是列或表 | col AS name |
col AS name |
| UNION ALL | 组合两个结果集 | q1 UNION ALL q2 |
q1 UNION ALL q2 |
| CASE | 有条件地返回值 | CASE WHEN c THEN x END |
CASE WHEN c THEN x END |
| 汇总 | 对行进行汇总 | COUNT SUM AVG MIN MAX |
COUNT SUM AVG MIN MAX |
| 行限制 | 限制行数 | FETCH FIRST n ROWS ONLY |
LIMIT n |
注意：
您通常不会自己编写行限制。要返回的最大行数设置将应用于您。FETCH FIRST 和 LIMIT 表单仅在需要查询内部显式限制时才有用。有关完整的 SQL 语法和每个方言背后的查询引擎，请参见以下引用：
Spark SQL 和 Delta 数据湖（标准目录）
- Apache Spark SQL 语法：DML 语句 Spark SQL 查询和 DML 语句语法。
- Delta 数据湖：表删除、更新和合并对 Delta 表执行 DELETE、UPDATE 和 MERGE 操作。
- Delta Lake：Table 实用程序命令 实用程序操作，例如 OPTIMIZE 和 VACUUM。
- Delta Lake：将液体群集用于 Delta 表 Liquid 集群用于 Delta 表布局。
将 SQL 工具添加到代理
您可以向代理添加 SQL 工具，以允许代理对注册的外部目录中的结构化数据源执行 SQL 查询。
- 单击并拖动代理上的连接器句柄以连接到工具节点。
- 选择查询方言：
- Spark SQL 针对标准 AI 数据平台目录编写查询。
- Oracle SQL 针对外部 AI 数据平台目录编写查询。
注意：
Spark SQL 需要在 AI 数据平台工作台工作区中运行 Spark 集群。
- 从 Cluster（集群）下拉列表中，选择正在运行的 Spark 集群。单击创建集群以预配新的 Spark 集群。有关创建新群集的指导，请参见 Create a Custom Cluster 。
注意：
SQL 查询工具不会自动启动停止的集群。因此，用于 Spark SQL 查询工具的 Spark 集群的持续时间应为 Forever 。如果允许集群在空闲超时时向下旋转，则 Spark SQL 查询会在集群停止后在生产环境中停止工作。
- 在浏览目录下，使用搜索字段按名称查找目录，或单击目录管理器以查找目录。
- 在查询字段中，输入查询。单击查看查询示例和指南以打开一个面板，其中包含您可以复制或调整的现成模式。
- 在 AI 工具定义窗格中，为查询中设置的变量设置类型、默认值和说明。
- 可选：单击测试选项卡。提供测试参数，然后单击提交。在测试结果窗格中查看测试结果。
代理内存
代理内存是 AI 代理系统的一部分，该系统允许代理在轮流、任务或会话中保留和重复使用信息。
与模型的上下文窗口（仅限于当前提示）不同，内存可以持久保存事实、首选项、先前决策、工具输出、中间计划或有关环境的观察。
AI 数据平台中的代理内存
AI Data Platform 提供短期内存，仅限于会话持续时间。您可以在代理的 "Memory"（内存）选项卡中配置可以保留在内存中的内容。
单代理内存配置
可以在代理节点的 "Memory"（内存）选项卡中找到单个代理系统的内存配置。
| 内存配置 | 说明 |
|---|---|
| 启用代理内存 | 此设置启用代理内存。禁用时，代理本质上是一个无状态系统。每个回合都独立处理，并且不能询问后续问题。我们建议启用内存。 |
| 限制对话历史记录 | 禁用此选择时，前一轮将填充内存，直到模型用完上下文并返回错误。如果需要短会话，则可以禁用此设置。但是，对于大多数用例，我们建议限制对话历史记录。 |
| 截断配置 | 如果您选择限制对话历史记录，则可以通过以下方式决定截断历史记录：
|
| 最大消息限制 | 如果选择保留最后 N 条消息，则可以设置值 N。 |
| 令牌预算 | 或者，您可以设置整体令牌预算。第一个令牌被删除，以将最新的令牌保留在内存中。 |
多代理系统内存配置（主管模式）
多代理系统的内存在超级用户代理的 "Memory"（内存）选项卡中配置。
多代理系统的内存已强制实施且无法禁用，并且超级用户代理节点中显示的内存截断选项仅应用于超级用户代理内存。可以根据为整个系统选择的状态隔离策略，在执行器节点 "Memory"（内存）选项卡中配置每个执行器代理内存截断策略。
多代理系统内存配置还允许您选择执行程序代理的内存共享策略。有三个选项：Stateless、Private 和 Shared。请注意，该策略将应用于所有执行程序代理。
| 执行者代理的状态隔离 | 说明 |
|---|---|
| 无状态 | 每个执行程序代理只能看到由主管分配的任务。呼叫之间未结转任何历史记录。执行程序代理无法向主管代理发出跟进请求。
如果选择了无状态，则会禁用每个执行程序代理的内存。 |
| 专用 | 每个执行程序代理只能看到自己过去的交互。
它无法看到其他执行程序代理或与主管代理的原始用户对话。 |
| 共享 | 执行者座席可以查看座席和用户的完整对话历史记录。所有代理都在一个共享上下文中工作。
如果选择了 "Shared"（共享），则可以在每个代理节点的 "Memory"（内存）选项卡中为每个执行程序代理单独配置内存截断策略。 |
会话变量
您可以使用自定义、代理定义的会话变量在用户会话期间向代理提供其他上下文数据点。
什么是会话变量？
定制的、代理定义的会话变量在用户会话期间向代理提供其他上下文数据点。这些变量可用于各种目的，包括设置工具中的参数值，向代理提供整体说明，以及提供有关调用者和/或嵌入代理的应用程序上下文信息。
这是一个简化的场景，我们正在建立一个客户支持代理。客户支持座席集成在零售网站中。用户登录零售网站时，客户端应用程序（用户 ID、用户名、地理位置、使用的设备、购物车 ID 等）会捕获有关该用户的信息，下游支持代理可以使用该信息。让我们看一个示例，说明如何在 AIDP 的代理指令字段中使用这些会话参数：
You are a customer support agent for the retail website belts-and-buckles.com, specializing in the sales of belts and buckles. Your objective is to answer questions that customers have about their current and past orders, answer questions about items they put in their shopping cart, and answer general questions about belts-and-buckles.com.
A few guidelines before your start:
You are interacting with user {{sessionVariable.userName}}. Always start with a welcome message: Hello {{sessionVariable.preferredSalutation}} {{sessionVariable.userName}}! What’s the weather like today in {{sessionVariable.currentUserGeo}}? - userName
- PreferredSalutation
- 当前 UserGeo
座席事先不知道用户与零售网站交互，不知道用户位置是什么，也不知道用户购物车中的内容。原则上，客户端应用程序可以知道这些值的全部或部分，并将请求中的这些值传递给代理。下面是向代理发送请求的示例，包括会话参数。
注意：
此示例说明此请求的外观。它不代表执行决定。"input": [
{ "role": "user",
"content": [
{ "type": "input_text”,
"text": "What material is the belt Mr Outcast made of?",
“variables”: [“userName”: “Paul”, “preferredSalutation”: “Hon”, “cartID”: NULL, “currentUserGeo”: “Cancun, MX”]
}
]
}
] 这位经纪人回答说：“你好，保罗先生，今天在 Mx 坎昆的天气怎么样？”
这些会话参数的另一个用途是在工具中设置参数值。例如，SQL 查询可以使用会话参数 ｛{sessionParam.CartID}} 检索购物车的内容：
Select productID, productName, productDescription,
productPrice from cartTable where cartID ==
{{sessionVariable.cartID}} 会话变量由代理开发人员在创建其代理时定义，这些属性的值由客户机应用程序在创建或恢复会话时设置。
您可以在创建新会话变量时配置以下设置：
| 设置 | 说明 |
|---|---|
| 必需的变量 | 启用此项可使代理每次调用都需要此会话变量。禁用会使会话变量对于每个调用都是可选的。 |
| 日志变量 | 启用以在日志和跟踪中捕获会话变量的值。禁用可防止变量出现在日志中。我们建议为具有敏感数据的变量禁用此设置。 |
| 名称 | 会话变量的名称。使用描述性名称可使您和其他用户轻松确定变量的用途。 |
| 默认值 | 如果未在调用调用中定义其他值，则会为会话变量指定默认值。如果留空，则必须将值分配为调用调用的一部分。 |
| 说明 | 会话变量的说明。提供有用的说明，以便您和其他用户能够了解会话变量的功能。 |
示例：在工具配置中使用会话变量
可以在 SQL 工具配置中使用会话变量作为 SQL 查询本身的一部分。
在此示例中，会话变量 geo 用于筛选 SQL 查询的结果：
您可以在同一查询中使用会话变量和工具参数。在下面的示例中，titleID 参数由代理设置，而会话变量 geo 由调用应用程序提供。
系统生成的会话变量
会话变量在远程 MCP 服务器连接到代理且 MCP 服务器需要验证（如 Bearer 标记）时自动生成。
会话变量保存 Bearer 令牌的值。无法更改此系统生成的会话变量的名称，该变量是必需的变量。从画布中删除 MCP 节点时，将删除系统变量。
在 Playground 中，为系统生成的会话变量提供值。在这种情况下，需要提供 Bearer 标记才能使用 MCP 服务器。您可以选择在 MCP 节点配置期间使用的相同（或不同的）标记。
在部署代理时也是如此。您需要提供授权令牌。有关更多信息，请参阅从操场将值分配给会话变量。
示例：调用已部署端点时为会话变量赋值
在此示例中，有两个会话变量：userLocation 和 UserName，客户机应用程序正在通过 body 的 metadata 字段传递会话变量值。我们将演示如何通过 Python 和 OCI CLI 赋值。
如果使用 Python 请求库，则有效负载如下：
body = {
"isStreamEnabled" : False,
"trace" : False,
"input" :[{
"role":"User",
"content":[{
"type" : "INPUT_TEXT",
"text" : “Hello how can you help me?”
}]
}],
"metadata": {
"sessionvariables.userLocation": "Canada",
"sessionvariables.UserName": "George"
}
}
response = requests.post(
url = <insert-chat-url>,
params = None,
auth = <insert-oci-signer>,
json = body,
headers={“x-session-id": <insert-a-session-key>,}
) 或者，如果您使用 OCI CLI，则有效负载如下：
oci raw-request \
--http-method POST \
--auth security_token \
--request-body '{
"isStreamEnabled": false,
"input": [
{
"role": "user",
"content": [
{
"type": "INPUT_TEXT",
"text": "Hello how can you help me?"
}
]
}
],
"metadata": {
"sessionvariables.userName": "George",
"sessionvariables.userLocation": "Canada"}"
}
}' \
--request-headers '{
"x-session-id": "george-session-may11"
}' \
--target-uri "<insert-your-agent-flow-uri>" 
请参阅代理流说明中的会话变量
您可以在代理说明和工具配置（包括 SQL 和提示工具查询）中引用会话变量。
- 单击“Playground（操场）”中的“SQL or Prompt（SQL 或提示）”工具节点。
界限
护栏是用于指导和控制 AI 代理行为的安全机制。
注意：
Oracle AI Data Platform Workbench 提供的护栏仅提供英文版本。AI Data Platform Workbench 中提供的 Guardrails 由 OCI Generative AI 服务团队实施。请参阅面向 OCI Generative AI 的护栏。AI Data Platform Workbench 服务基于您的护栏配置调用 OCI 租户中的 Apply Guardrails API 。
可视流画布中的护栏
默认情况下，除了模型提供商的原生安全控制之外，不会对系统应用任何护栏。要添加护栏，必须将护栏节点拖动到代理可视流构建器中，然后将其连接到代理。
Guardrails 节点可以过滤聊天触发器与代理节点之间的流量，在主管和执行器代理之间，或者在代理和工具节点之间。对于大多数情况，我们建议在聊天触发器和座席节点之间使用单个护栏节点。这将确保来自传入用户的任何消息以及代理生成的消息将通过保护栏进行过滤。
- 聊天触发器节点和座席（主管或执行者）
有哪些护栏可用？
下图显示了最终用户与代理之间的简单交互。在这种情况下，将应用所有导轨（内容调节 -CM，及时注射预防 -PI 和 PII 检测 -PII）。PI 仅应用于用户查询。
在最终用户发出第二条消息后，检测到 PI 尝试，并在代理开发人员对 PI 检测（块）执行的选定操作后阻止了用户消息。
内容仲裁
内容审核是大多数生成式 AI 中的常见保护措施。如果不加以控制，LLM 可以产生有害的内容，促进暴力，种族主义和色情内容。必须让座席开发人员全面了解和控制用户与座席的交互如何被监视和扫描，以查找可能有害的内容。内容调节可防止恶意、性、暴力、有毒、贬损或基于骚扰的内容被代理流考虑或生成。我们的护栏模型根据这六个类别对内容进行分类，并标记属于这些类别之一的内容。
- 块：您可以阻止代理处理用户输入并生成响应。用户从代理流收到错误响应。
- 通知：允许代理流处理用户输入并生成响应。代理将通知用户输入或响应包含符合保护标准的内容。
- 允许：允许代理流处理和/或生成可能有害的内容。
创建代理流时，会为内容审核选择块操作。Oracle 建议保留 Block 作为内容审核的护栏选择。
提示注入
人工智能代理的提示注入护栏是一种保护机制，可以检测、预防和缓解用户输入中嵌入的恶意或意外指令。提示性注入攻击通过插入隐藏文本来尝试覆盖或颠覆代理的原始指令、策略或目标，这些文本会告知模型忽略以前的规则、泄露秘密或执行未经授权的操作。
- 块：您可以阻止代理处理用户输入。用户从代理流收到错误响应。
- 通知：允许代理流处理用户输入。代理将通知用户输入包含符合 Guardrail 条件的内容。
- 允许：允许代理流处理潜在有害的内容。
在您创建代理流时，块操作处于选中状态。Oracle 建议保留 Block 作为提示注入的护栏选择。
个人可识别信息 (Personally Identifiable Information，PII)
PII 护栏会自动检测、阻止或屏蔽来自用户输入查询或代理响应的 PII。此保护栏可防止代理以违反隐私法规或组织政策的方式公开敏感用户信息。
- 电子邮件
- Telephone number
- 物理地址
- 人员姓名
- 块：您可以阻止代理处理用户输入并生成响应。用户从代理流收到错误响应。
- 通知：允许代理流处理用户输入并生成响应。代理通知用户输入或响应包含 PII。
- 掩码：允许代理流处理输入并生成屏蔽的响应。使用的任何 PII 都会进行编辑以防止暴露。
- 允许：允许按代理流处理和/或生成 PII 数据。
在新的代理流中，默认情况下，用户输入和响应都允许 PII。Oracle 建议您根据安全需求仔细选择 PII 的护栏。
为代理创建 AI 集群
可以直接从代理界面创建新 AI 集群并立即将其连接。
- 在主页上，导航到您的代理。
- 单击计算，然后单击创建新 AI 计算。
- 为 AI 计算集群提供名称和说明。
- 选择 AI 计算集群的 OCPU 数和内存大小。
- 单击创建。
从 AI 计算分离代理
可以将代理与 AI 计算分离。分离 AI 计算会删除在连接的计算上运行的代理代码，并阻止测试。
注意：
从 AI 计算中分离代理不会删除代理。您可以通过将代理连接到相同或不同的 AI 计算来恢复构建和测试代理。- 单击 Compute（计算），然后单击 Detach from AI Compute（从 AI 计算分离）。
A2A 代理部署
Agent2Agent(A2A) 协议是独立 AI 代理之间通信的开放标准，包括使用不同框架构建的代理，由不同的供应商托管，或作为不透明的远程系统运行。
其目的是为这些代理提供共享交互模型，以便他们能够发现彼此的能力，协商支持的输入/输出格式，委托或协作处理任务，并安全地交换信息，而不会暴露内部内存、工具或实施详细信息。有关更多信息，请参见 Agent2Agent (A2A) Protocol 。
A2A 旨在解决代理互操作性：客户机或其他代理可以使用一组通用的概念和操作与任何符合 A2A 标准的远程代理进行交互，而不是定制每个代理集成。该规范以消息、任务、部件、构件、流更新和推送通知为中心；它支持同步回复、长时间运行的异步工作、流处理和企业式验证/安全模式。
在 Oracle AI Data Platform 中，所有部署的代理都有一个 /A2A 调用路径，A2A 客户机应用程序可以调用该路径。
什么是代理卡？
代理卡是由 A2A 服务器发布的 JSON 元数据文档。在 AIDP 中，A2A 服务器是托管代理部署的 AI 计算。
卡描述代理的身份、服务端点、支持的协议/传输、功能、技能、支持的输入/输出模式以及身份验证要求；客户机使用它来发现代理是否合适以及如何调用代理。正确记录的代理卡是 A2A 协议的要求。
AI 数据平台工作台中的座席卡处于“草稿”状态，这意味着座席尚未部署，或者已发布，这意味着该卡已与座席一起部署。
代理卡操作
在代理的开发过程中，该卡在代理的“操作”菜单中可用。
- 草稿卡反映了代理在开发中的当前状态。
- 发布的卡对应于部署代理时获取的卡的快照。发布的卡反映了已部署代理的状态。
代理卡字段
AI Data Platform Workbench 支持当前 A2A 协议代理卡字段的子集，可在此处获取： A2A Protocol - Agent Card 。
| 域 | 必需 | 说明 |
|---|---|---|
name |
是 | 代理的人类可读名称。示例：“配方代理” |
description |
是 | 代理人可读的描述，帮助用户和其他代理人了解其目的。示例：“帮助用户制作食谱和烹饪的代理”。 |
Agent Version |
是 | 代理的版本。示例："1.0.0" |
Documentation URL |
无 | 提供有关代理的其他文档的 URL。 |
Provider - Organization |
无 | 代理的服务提供方。 |
Provider - URL |
无 | 服务提供者的 URL。 |
Capabilities |
是 | 代理支持的 A2A 功能集。
只能配置 |
Skills
|
是 | 技能代表座席的能力。它基本上是一个描述性的概念，但代表了一组更集中的行为，代理可能会成功。技能代表 AgentSkill 的数组。 |
每个 AgentSkill 由多个字段组成，用于记录 Agent 的功能。在代理卡中定义代理技能是最耗时的操作，是一个迭代过程。在部署之前，可以在草稿座席卡中编辑技能（以及座席卡的其余部分）。
注意：
inputModes、outputModes 和 securityRequirements 由 AI Data Platform Workbench 提供，无法修改。
| 域 | 必需 | 说明 |
|---|---|---|
Skill ID |
是 | 代理技能的唯一标识符。 |
Skill Name |
是 | 技能的人类可读名称。 |
Description |
是 | 技能的详细说明。 |
Tags |
是 | 描述技能功能的一组关键字。 |
Examples |
无 | 此技能可以处理的提示或方案示例。 |
代理部署端点 A2A 路径
除 /chat 之外，/a2a 路径在已部署代理的 URL 中公开。
例如，代理将向外部客户机公开以下路径：
https://gateway.aidp.{oci-region}.oci.oraclecloud.com/agentendpoint/{agentId}/chathttps://gateway.aidp.{oci-region}.oci.oraclecloud.com/agentendpoint/{agentId}/a2a
这两个路径（/chat、/a2a）可以由单独的客户机使用。
A2A 中的会话变量
会话变量的值可以在消息 metadata 字段中传递给 A2A 代理。下面的 JSON 片段显示了向 a2a 代理发出的具有三个会话变量的用户消息的有效负载：userName、geoLocation 和 os：
{
"jsonrpc": "2.0",
"method": "message/send",
"params": {
"contextId": "session_12345",
"taskId": "task_67890",
"message": {
"role": "user",
"parts": [
{
"text": "What is the current status of my order?",
}
],
"metadata": {
"sessionvariables.userName": "George",
"sessionvariables.geoLocation": “Dallas, TX”,
"sessionvariables.os": "mobile_ios"
}
}
},
"id": "rpc-99821"
}
示例：使用 OCI CLI 调用 A2A 代理（非流处理）
oci raw-request \
--http-method POST \
--auth security_token \
--request-body '{
"id": "<your-request-id>",
"jsonrpc": "2.0",
"method": "message/send",
"params": {
"configuration": {
"acceptedOutputModes": [
"text/plain",
"text"
]
},
"message": {
"contextId": "<your-context-id>",
"kind": "message",
"messageId": "<your-message-id>",
"parts": [
{
"kind": "text",
"text": "What is the capital of India?"
}
],
"role": "user"
}
}
}' \
--request-headers '{
"x-session-id": "<your-session-id>",
"dh-user-principal": "<your-user-principal>"
}' \
--target-uri " <your-a2a-agent-endpoint-url>"
示例：使用 OCI CLI 调用 A2A 代理（流处理）
oci raw-request \
--http-method POST \
--auth security_token \
--request-body '{
"id": "<your-request-id>",
"jsonrpc": "2.0",
"method": "message/stream",
"params": {
"configuration": {
"acceptedOutputModes": [
"text/plain",
"text"
]
},
"message": {
"contextId": "<your-context-id>",
"kind": "message",
"messageId": " <your-message-id>",
"parts": [
{
"kind": "text",
"text": "What is the capital of India?"
}
],
"role": "user"
}
}
}' \
--request-headers '{
"x-session-id": "<your-session-id>",
"dh-user-principal": "<user-principal>"
}' \
--target-uri "<your-a2a-agent-endpoint-url>"
示例：A2A 客户端 SDK
import asyncio
import json
import logging
import typing
from collections.abc import Iterator
import uuid
import httpx
import oci
from a2a.client import A2AClient, ClientFactory
from a2a.types import (
AgentCard,
Message,
Part,
Role,
TextPart,
SendMessageRequest,
MessageSendParams,
MessageSendConfiguration,
Task, SendMessageSuccessResponse, SendStreamingMessageRequest,
)
class OCIAuth(httpx.Auth):
"""httpx auth implementation using OCI signer via requests auth adapter."""
def __init__(self, signer: oci.signer.AbstractBaseSigner):
self._requests_auth = _OCIRequestsAuth(signer)
def auth_flow(self, request: httpx.Request) -> Iterator[httpx.Request]:
req = RequestsRequest(
method=request.method,
url=str(request.url),
headers=dict(request.headers),
data=request.content,
)
prepared: RequestsPreparedRequest = req.prepare()
prepared = self._requests_auth(prepared)
request.headers.update(dict(prepared.headers))
yield request
def getOCIAuth():
conf = oci.config.from_file(profile_name="DEFAULT")
token_file = conf['security_token_file']
token = None
with open(token_file, 'r') as f:
token = f.read()
private_key = oci.signer.load_private_key_from_file(conf['key_file'])
signer = oci.auth.signers.SecurityTokenSigner(token, private_key)
auth = OCIAuth(signer=signer)
return auth
async def _call_agent_with_a2a(agent_url: str, query: str, context_id: str,auth:OCIAuth) -> str:
"""Call an agent using the A2A protocol."""
try:
# Initialize OCI signer
#headers = {"dh-user-principal": "dh-user"}
headers = {"Accept": "*/*",
"dh-user-principal": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."}
async with httpx.AsyncClient(timeout=60.0, auth=auth,headers=headers) as hc:
agent_card = await _get_agent_card(agent_url,auth)
print(f"Agent card is {agent_card}")
client = A2AClient(httpx_client=hc, agent_card=agent_card)
# Create message
message = Message(
message_id=str(uuid.uuid4()),
context_id=context_id,
role=Role.user,
parts=[Part(root=TextPart(text=query))],
metadata={"sessionvariables.cred.mcp.weatherReportMCP.bearer": "valid-123"}
)
request = SendMessageRequest(
id=str(uuid.uuid4()), # Add the required id field
params=MessageSendParams(
message=message,
configuration=MessageSendConfiguration(acceptedOutputModes=["text/plain", "text"]),
),
)
#json_string = json.dumps(message, indent=4)
print(f"Send request : {request}")
response = await client.send_message(request)
logging.info("Received response from A2A server: %s", response.root.result)
# Extract response
result = response.root.result
# Handle different response types
if isinstance(result, Task):
# Task response
if result.artifacts:
# Extract text from artifacts
texts = []
for artifact in result.artifacts:
for part in artifact.parts:
if hasattr(part, "root") and hasattr(part.root, "text"):
texts.append(part.root.text)
return "\n".join(texts) if texts else "Task completed with no text response"
elif result.status and result.status.message:
logging.info(f"Received Task status {result.status.state} from A2A server and status message is {result.status.message}", result.status.message)
if result.status.state== "failed":
print("Failure observed in Task invocation")
for m_part in result.status.message.parts:
print(f"Error message { m_part.root.text}")
return get_message_text(result.status.message)
else:
return f"Task {result.id} status: {result.status.state if result.status else 'unknown'}"
elif isinstance(result, Message):
return get_message_text(result)
else:
logging.warning(f"Unexpected response type: {type(result)}")
return "Received response but unable to extract text"
except Exception as ex:
logging.error(f"Error calling agent at {agent_url}: {ex}", exc_info=True)
return f"Error communicating with agent: {str(ex)}"
async def _call_agent_with_a2a_with_stream(agent_url: str, query: str, context_id: str, auth: OCIAuth) -> str:
"""Call an agent using the A2A protocol with streaming (SSE) and return the final artifact text."""
try:
async with httpx.AsyncClient(timeout=60.0, auth=auth) as hc:
agent_card = await _get_agent_card(agent_url)
if not agent_card:
return "No Agent Card Found"
print(f"Agent card is {agent_card}")
client = A2AClient(httpx_client=hc, agent_card=agent_card)
message = Message(
message_id=str(uuid.uuid4()),
context_id=context_id,
role=Role.user,
parts=[Part(root=TextPart(text=query))],
)
request = SendStreamingMessageRequest(
id=str(uuid.uuid4()),
params=MessageSendParams(
message=message,
configuration=MessageSendConfiguration(acceptedOutputModes=["text/plain", "text"]),
),
)
print("Invoking Remote Agent request (beautified JSON):")
print(json.dumps(request.model_dump(), indent=2, ensure_ascii=False))
# Expected event types:
# - TaskStatusUpdateEvent (working/in-progress)
# - TaskArtifactUpdateEvent (contains Artifact.parts[].root.text) -> final output
final_artifact_text_parts: list[str] = []
async for event in client.send_message_streaming(request):
# Print each SSE event as-is (SDK object)
print(f"[A2A stream event] {event}")
try:
result = getattr(event.root, "result", None)
if not result:
continue
# TaskArtifactUpdateEvent and TaskStatusUpdateEvent are SDK types; to avoid tight coupling,
# extract by attribute presence.
artifact = getattr(result, "artifact", None)
if artifact and getattr(artifact, "parts", None):
for part in artifact.parts:
root = getattr(part, "root", None)
txt = getattr(root, "text", None)
if txt:
final_artifact_text_parts.append(txt)
except Exception:
# Keep streaming even if an event can't be parsed
continue
return "\n".join([t for t in final_artifact_text_parts if t]).strip() or "Stream completed (no artifact text)."
except Exception as ex:
logging.error(f"Error calling agent at {agent_url}: {ex}", exc_info=True)
return f"Error communicating with agent: {str(ex)}"编辑草稿代理卡
您可以为尚未部署的代理编辑代理卡。
- 单击操作，然后单击查看代理卡和草稿代理卡。
- 单击编辑。
- 您可以通过单击右上角的表单或 JSON 来切换视图。JSON 视图更完整，但为只读。您只能编辑“表单”视图中的字段。
- 单击添加技能以添加要向 A2A 客户机公开的技能。
编辑已发布的座席卡
您可以修改已发布的代理卡，而无需取消部署或重新部署代理。
注意：
对已发布卡所做的更改会立即反映在 A2A 客户机可访问的 agent-card.json 文件中。- 单击操作，然后单击查看代理卡和已发布的代理卡。
- 单击编辑。
- 单击添加技能以添加要向 A2A 客户机公开的技能。
https://gateway.aidp.{oci-region}.oci.oraclecloud.com/agentendpoint/{agentId}/a2a/agent-card.json代理部署
部署代理会将您的代理转换为托管应用程序。
您可以将代理部署到附加到其操场或不同 AI 计算的同一 AI 计算中。将代理的最新更改部署到附加的 AI 计算时，部署的代理表示部署时代理的快照。要将部署的代理更新到最新版本，需要重新部署代理。
每个代理都有一个依赖于唯一代理键的稳定部署 URL。多次重新部署代理会覆盖部署 URL 后面的代理。
- 在任意给定时间，一个代理只能部署到一个 AI 计算集群。
- 将同一代理多次部署到同一 AI 计算集群会覆盖以前部署的代理迭代。
部署座席后，您可以检索聊天 URI，以通过编程方式发出查询并从座席的详细信息选项卡检索座席的响应。
端点 URL 是稳定的，它与每个代理绑定。URL 包括分配给每个代理的唯一 agentID。换句话说，如果您取消部署代理并重新部署该代理，则 URL 保持不变。优点是您不必修改调用端点的客户端代码，缺点是您可以覆盖生产环境中的代理。
https://gateway.aidp.{oci-region}.oci.oraclecloud.com/agentendpoint/{agentId}/{protocol}oci-region对应于 AI 数据平台实例区域；agentId是与代理关联的唯一 IDprotocol是通信协议：chat遵循 OpenAI Responses API 格式，a2a遵循代理到代理通信协议。这两种协议都可用于每个代理端点。有关更多信息，请参见 A2A Agent Deployment 。
注意：
"Details"（详细信息）选项卡中列出了两个 AI 计算。附加到 AI 计算用于在操场中测试代理。Deployed to AI Compute 托管部署的代理。部署代理后，将填充端点 URL 字段。您可以从生产应用程序调用此端点 URL。
调用已部署的代理
您可以从生产应用调用代理的端点 URL。
无论用于调用代理端点的编程接口如何，都必须通过 OCI 进行验证并具有相关权限。对于代理流端点，调用方需要对代理端点至少具有 USE 权限。
端点 URI 记录在代理 UI 的详细信息选项卡中。您可以将该端点 URI 复制到代码中以调用代理。
调用端点 URI 的方法
您可以通过不同的工具、SDK 和 CLI 调用代理端点 URI。
以下方法允许您在 Oracle AI Data Platform Workbench 代理中调用端点 URI。
使用 OCI CLI 调用
oci raw-request
--http-method POST
--target-uri <your-agent-flow-endpoint-uri>
--request-body '{"query":"Tell me about the Ryder Cup in 1985"}'
--auth <security_token>使用 Python 请求库调用
import oci import requests import json import uuid from contextlib import closing from requests import Request, Response
class AuthHelper: """ AuthHelper allows creating an OCI signer with either API key or security_token (which are short term sessions) """ def init(self, oci_profile: str, use_security_token:bool = True): config = oci.config.from_file(file_location="/Volumes/jr/default/misc/config",profile_name=oci_profile) if use_security_token: with open(config["security_token_file"], 'r') as f: token = f.read() private_key = oci.signer.load_private_key_from_file(config["key_file"])
self.signer = oci.auth.signers.SecurityTokenSigner(token, private_key) else: self.signer = oci.signer.Signer( tenancy=config["tenancy"], user=config["user"], fingerprint=config["fingerprint"], private_key_file_location=config["key_file"], #pass_phrase=config.get("pass_phrase"), #private_key_content=config.get("key_content") )
@property
def Signer(self):
return self.signer
class MyRawJsonRpcClient: """ Simple class using requests lib to post JSON to chat endpoint using OCI signing """ def init(self, chat_url:str, oci_profile: str, sessionKey:str, use_security_token:bool = True): self.authhelper = AuthHelper(oci_profile=oci_profile, use_security_token=use_security_token) self.authsigner = self.authhelper.Signer self.chat_url = chat_url self.sessionKey = sessionKey
def send(self, input:str) -> Response:
body = {
"isStreamEnabled" : False,
"sessionKey" : self.sessionKey,
"trace" : False,
"input" :[{
"role":"User",
"content":[{
"type" : "INPUT_TEXT",
"text" : input
}]
}]
}
response:Request = requests.post(
url =self.chat_url,
params = None,
auth = self.authsigner,
json=body,
headers={}
)
return response
sessionKey。sessionKey 是代理的用户会话的唯一标识符。如果继续重复使用相同的 sessionKey，则会将用户消息和代理响应附加到相同的保护。 client = MyRawJsonRpcClient(chat_url="<your-agent-flow-endpoint-uri>",
oci_profile = "DEFAULT",
sessionKey= “<your-session-key>”,
use_security_token = False )user_input = f"Hello, tell me a good dad joke."
r = client.send(input = user_input)
response_json = r.json()通过 APEX
您可以使用 AI Data Platform Workbench Samples Github 库中提供的代码示例。此示例将引导您完成从 APEX 应用调用代理部署端点的过程。
通过 Streamlit
您可以使用 AI Data Platform Workbench Samples Github 库中提供的代码示例。该示例将引导您完成从 Streamlit 应用程序调用代理部署端点的过程。
最佳实践 - 异步和非异步响应
我们建议您编写假定异步响应的客户端代码。例如：
import httpx
async def fetch_data():
async with httpx.AsyncClient() as client:
response = await client.get(URL)
return response.json()
监视代理
您可以监视与座席的会话和度量相关的详细信息，以查看有关其使用方式、其使用的资源等信息。
您的代理中有多个用于跟踪使用情况详细信息的选项卡、会话选项卡、度量选项卡和活动选项卡。您可以在座席画布的顶部找到它们。
跟踪和跨度
跟踪通过捕获和显示代理请求流，为代理提供可观察性。跨度是构成跟踪的对象。每个跨度是流中的不同步骤，例如来自用户、座席调用和工作流任务的聊天提示。
您可以查看当前会话、测试运行或以前会话的跟踪。要查看当前会话跟踪，请转至“流”选项卡，然后单击“操场”。页面底部的“详细信息”窗格在左侧窗格中显示当前会话的跟踪。您可以单击跟踪中的对象以展开它们或查看更多详细信息。在右侧窗格中，可以单击 "Info"（信息）、"Details"（详细信息）或 "Events"（事件）选项卡来了解有关所选跨度对象的更多信息。
通过单击会话的名称，可以在会话选项卡中查看以前会话的跟踪。
会话
在会话选项卡中，您可以查看此代理的会话历史记录。您可以查看每个会话是成功还是失败、URI 源、会话启动时间、会话的持续时间以及会话中使用的标记。您可以单击会话 ID 以了解有关该会话的更具体详细信息，并查看该特定会话的跟踪。
您可以使用搜索栏按会话 ID 或 URI 源过滤显示的会话，使用日期筛选器仅显示特定日期范围，并使用“会话状态”下拉菜单按会话成功还是失败进行过滤。
度量
度量选项卡显示所有代理会话的使用情况数据的摘要。“日期范围”下拉列表筛选要在显示的卡中汇总的时间期。URI 选择将筛选要查看其详细信息的 URI 选择源。您可以修改显示哪些卡，以及它们是否包括图形作为使用情况的视觉表示。
活动
作业选项卡显示代理部署状态的概要。“操作”列指定部署操作的类型（部署或取消部署），“状态”列指定操作的结果（成功、错误、警告、失败）。您可以查看启动操作的人员以及与操作结果关联的状态消息。
