DBMS_CLOUD_AI_AGENT 程序包
此程序包定义和管理 Select AI 代理、任务、工具和编排。
注意:
Oracle Database 19c(从版本 19.29 开始)和 Oracle Database 26ai(从版本 23.26 开始)中提供了对 DBMS_CLOUD_AI_AGENT 软件包的支持。DBMS_CLOUD_AI_AGENT 次级方案摘要
本部分介绍 Select AI Agent 随 Autonomous AI Database 提供的 DBMS_CLOUD_AI_AGENT 子程序。
| 子程序 | 说明 |
|---|---|
|
此过程将创建代理。 |
|
|
提供用于创建代理的属性。 |
|
|
此过程可启用代理。 |
|
|
此过程将禁用代理。 |
|
|
此过程将删除现有代理。 |
|
|
此过程将创建座席和座席团队可以包括的任务。 |
|
|
提供用于创建代理任务的属性。 |
|
|
此过程启用代理任务。 |
|
|
此过程将禁用代理任务。 |
|
|
此过程将删除现有代理任务。 |
|
|
此过程创建代理可以包括的定制工具。 |
|
|
提供用于创建工具的属性。 |
|
|
此过程启用已注册的工具。 |
|
|
此过程将禁用已注册的工具。 |
|
|
此过程将删除现有工具。 |
|
|
此过程将创建代理团队,并包括代理和任务。 |
|
|
提供用于创建代理团队的属性。 |
|
|
此过程设置当前会话中的代理团队。 |
|
|
此过程返回在当前会话中设置的代理团队。 |
|
|
此过程将清除在当前会话中设置的代理团队。 |
|
|
此过程将创建新代理或运行暂停的代理。 |
|
|
此过程允许代理团队。 |
|
|
此过程将禁用代理团队。 |
|
|
此过程将删除现有代理团队。 |
CREATE_AGENT 过程
使用 DBMS_CLOUD_AI_AGENT.CREATE_AGENT 过程在 Select AI Agent 框架中注册新的 AI 代理。使用 agent_name 定义代理的身份,使用属性参数配置其行为,并根据需要提供说明。
语法
DBMS_CLOUD_AI_AGENT.CREATE_AGENT(
agent_name IN VARCHAR2,
attributes IN CLOB,
status IN VARCHAR2 DEFAULT NULL,
description IN CLOB DEFAULT NULL
);参数
| Parameter (参数) | 说明 |
|---|---|
|
|
AI 代理的名称。代理名称必须遵循 Oracle SQL 标识符的命名规则。名称的最大长度为 125 个字符。 此项是必需参数。 |
|
|
AI 代理的定制属性。有关更多详细信息,请参见 CREATE_AGENT Attributes 。 |
status |
代理的状态。 默认值为 |
|
|
AI 代理的用户指定说明。 默认值为空值。 |
范例
以下示例将创建一个代理来处理客户产品退货。有关完整示例,请参阅示例:创建产品退货代理。
BEGIN
DBMS_CLOUD_AI_AGENT.CREATE_AGENT(
agent_name => 'CustomerAgent',
attributes => '{
"profile_name": "GOOGLE",
"role": "You are an experienced customer agent who deals with customers return request."
}'
);
END;
/
PL/SQL procedure successfully completed.
CREATE_AGENT 属性
属性
| 属性名称 | 默认值 | 说明 |
|---|---|---|
|
|
- |
代理用于将请求发送到 LLM 的 AI 配置文件。 此项是必需参数。 |
|
|
- |
定义代理的功能并为代理提供上下文。这已发送到 LLM。 此项是必需参数。 |
|
|
|
使座席能够向用户提问以获得信息或说明。 |
BEGIN
DBMS_CLOUD_AI_AGENT.CREATE_AGENT(
agent_name => 'Customer_Return_Agent',
attributes => '{
"profile_name": "GOOGLE",
"role": "You are an experienced customer agent who deals with customers return request.",
"enable_human_tool": "False"
}'
);
END;
/
PL/SQL procedure successfully completedENABLE_AGENT 过程
此过程可启用用户指定的 AI 代理。该过程将 AI 代理的状态更改为 ENABLED。
语法
DBMS_CLOUD_AI_AGENT.ENABLE_AGENT(
agent_name IN VARCHAR2
);参数
| Parameter (参数) | 说明 |
|---|---|
|
|
要启用的 AI 代理的名称。 此参数是必需的。 |
启用 AI 配置文件的示例
BEGIN
DBMS_CLOUD_AI_AGENT.ENABLE_AGENT(
agent_name => 'Customer_Return_Agent'
);
END;
/
DISABLE_AGENT 过程
此过程将禁用当前数据库中的 AI 代理。此过程将 AI 代理的状态更改为 DISABLED。
语法
DBMS_CLOUD_AI_AGENT.DISABLE_AGENT(
agent_name IN VARCHAR2
);
参数
| Parameter (参数) | 说明 |
|---|---|
|
|
AI 代理的名称。 此参数是必需的。 |
范例
BEGIN
DBMS_CLOUD_AI_AGENT.DISABLE_AGENT(
agent_name => 'Customer_Return_Agent'
);
END;
/
DROP_AGENT 过程
该过程将删除现有 AI 代理。如果代理不存在,则该过程会引发错误。
语法
DBMS_CLOUD_AI_AGENT.DROP_AGENT(
agent_name IN VARCHAR2,
force IN BOOLEAN DEFAULT FALSE
);参数
| Parameter (参数) | 说明 |
|---|---|
|
|
AI 代理的名称。 此项是必需参数。 |
|
|
如果为 此参数的默认值为 |
范例
BEGIN
DBMS_CLOUD_AI_AGENT.DROP_AGENT(agent_name => 'Customer_Return_Agent);
END;
/使用说明
如果 AI 代理不存在,请使用 force 删除代理并忽略错误。
CREATE_TASK 过程
使用 DBMS_CLOUD_AI_AGENT.CREATE_TASK 过程定义 Select AI 代理可以包括在其推理过程中的任务。每个任务都有一个唯一的名称和一组属性,用于在计划和执行任务时指定代理的行为。
您可以使用 input 属性定义任务之间的依赖关系,从而允许 Select AI 将一个任务的输出传递到另一个任务。这支持链式推理和多步骤工作流。
语法
DBMS_CLOUD_AI_AGENT.CREATE_TASK(
task_name IN VARCHAR2,
attributes IN CLOB,
status IN VARCHAR2 DEFAULT NULL,
description IN CLOB DEFAULT NULL
);参数
| Parameter (参数) | 说明 |
|---|---|
|
|
任务的唯一名称。 此项是必需参数。 |
|
|
包含任务特定属性的 JSON 对象。请参见 CREATE_TASK Attributes 。 |
status |
任务的状态。 默认值为 |
|
|
用户定义的说明,用于帮助标识任务。此值存储在数据库中,但不会发送到 LLM。 默认值为空值。 |
范例
以下示例将创建一个任务来处理来自客户的产品退货。
BEGIN
DBMS_CLOUD_AI_AGENT.CREATE_TASK(
task_name => 'Return_And_Price_Match',
attributes => '{"instruction": "Process a product return request from a customer:{query}' ||
'1. Ask customer the reason for return (price match or defective)' ||
'2. If price match:' ||
' a. Request customer to provide a price match link' ||
' b. Use websearch tool to get the price for that price match link' ||
' c. Ask customer if they want a refund.' ||
' d. Send email notification only if customer accept the refund.' ||
'3. If defective:' ||
' a. Process the defective return",
"tools": ["WebSearch", "Email"]}'
);
END;
/
CREATE_TASK 属性
属性
| 属性名称 | 默认值 | 说明 |
|---|---|---|
|
|
- |
一个清晰、简洁的陈述,描述任务应该完成什么。此文本包含在发送到 LLM 的提示中。您可以包括一个
{query} 占位符来表示您的自然语言输入。例如:
此项是必需参数。 |
|
|
- |
代理可用于完成任务的工具名称的 JSON 数组。例如: 此项是必需参数。 |
|
|
- |
标识应将其输出用作此任务输入的其他任务。选择 AI 会自动向 LLM 提供这些输出。 |
|
|
- |
允许座席在任务期间需要信息或说明时向用户提问。 默认值为“真”。 注意: 任务 |
ENABLE_TASK 过程
使用 DBMS_CLOUD_AI_AGENT.ENABLE_TASK 过程可启用以前定义的任务。这将任务的状态更改为 ENABLED,允许代理在处理期间使用它。
语法
DBMS_CLOUD_AI_AGENT.ENABLE_TASK(
task_name IN VARCHAR2
);参数
| Parameter (参数) | 说明 |
|---|---|
|
|
要启用的任务的名称。 此参数是必需的。 |
使用说明
此任务必须已存在于系统中。此过程将更新任务状态,使其在推理工作流期间可用于代理流程。
启用任务的示例
BEGIN
DBMS_CLOUD_AI_AGENT.ENABLE_TASK(
task_name => 'Return_And_Price_Match'
);
END;
/
DISABLE_TASK 过程
使用 DBMS_CLOUD_AI_AGENT.DISABLE_TASK 过程禁用当前数据库中的任务。这会将任务的状态更改为 DISABLED,以防止代理在处理期间使用它。
语法
DBMS_CLOUD_AI_AGENT.DISABLE_TASK(
task_name IN VARCHAR2
);
参数
| Parameter (参数) | 说明 |
|---|---|
|
|
要禁用的任务的名称。 此参数是必需的。 |
使用说明
禁用任务不会将其删除;您可以稍后使用 DBMS_CLOUD_AI_AGENT.ENABLE_TASK 重新启用该任务。禁用后,任务将变为非活动状态,代理在选择任务期间将不再考虑该任务。
范例
以下示例禁用现有任务。
BEGIN
DBMS_CLOUD_AI_AGENT.DISABLE_TASK(
task_name => 'Return_And_Price_Match'
);
END;
/
DROP_TASK 过程
使用 DBMS_CLOUD_AI_AGENT.DROP_TASK 过程从数据库中删除以前定义的任务。如果任务不存在,则可以通过将 force 参数设置为 TRUE 来抑制该错误。
语法
DBMS_CLOUD_AI_AGENT.DROP_TASK(
task_name IN VARCHAR2,
force IN BOOLEAN DEFAULT FALSE
);参数
| Parameter (参数) | 说明 |
|---|---|
|
|
要删除的任务的名称。 此项是必需参数。 |
|
|
如果为 此参数的默认值为 |
范例
BEGIN
DBMS_CLOUD_AI_AGENT.DROP_TASK(task_name => 'Return_And_Price_Match');
END;
/使用说明
如果任务不存在,请使用 force 删除任务并忽略错误。
CREATE_TOOL 过程
使用 DBMS_CLOUD_AI_AGENT.CREATE_TOOL 过程注册代理可在任务处理期间使用的定制工具。每个工具都由唯一的 tool_name 标识,并包含用于定义其用途、实施逻辑和元数据的属性。
这些工具可以是定制 PL/SQL 过程或函数,也可以是 RAG、SQL、WEBSEARCH 或 NOTIFICATION 等内置工具类型。
语法
DBMS_CLOUD_AI_AGENT.CREATE_TOOL(
tool_name IN VARCHAR2,
attributes IN CLOB,
status IN VARCHAR2 DEFAULT NULL,
description IN CLOB DEFAULT NULL
);参数
| Parameter (参数) | 说明 |
|---|---|
|
|
用于标识工具的唯一名称。 此项是必需参数。 |
|
|
JSON 格式的工具属性。请参见 CREATE_TOOL Attributes 。 此项是必需参数。 |
status |
工具的状态。 默认值为 |
|
|
用户定义的说明,用于帮助标识此工具。此值存储在数据库中,但不会发送到 LLM。 默认值为空值。 |
范例
以下示例创建用于生成发送给收件人的电子邮件的工具。
BEGIN
DBMS_CLOUD_AI_AGENT.CREATE_TOOL(
tool_name => 'NOTIFICATION',
attributes => '{"tool_type": "EMAIL"}'
);
END;
/
CREATE_TOOL 属性
属性
| 属性名称 | 默认值 | 说明 |
|---|---|---|
|
|
- |
一个清晰而简洁的陈述,描述该工具应该完成什么以及如何完成它。此文本包含在发送到 LLM 的提示中。 此项是必需参数。 |
|
|
- |
指定使用工具时要调用的 PL/SQL 过程或函数。 这是自定义工具的必备参数。 |
|
|
- |
指定内置工具类型。如果设置,则不需要 可能的值有:
您可以创建具有定制名称和参数的内置工具。您还可以使用相同的 |
|
|
- |
指定用于注册内置工具的参数。 |
|
|
- |
描述输入参数。与表中的列注释类似。例如:
|
内置工具的先决条件
使用内置工具之前,请执行以下步骤:
RAG 工具
-
创建引用向量索引的 AI 配置文件。请参阅使用检索增强生成 (RAG) 增强自然语言提示。
通知工具
支持以下项:SLACK 和 EMAIL。
SLACK Tool :
- 设置 Slack 应用以接收来自 Autonomous Database 的消息。
-
使用
DBMS_CLOUD_NOTIFICATION创建身份证明以从 Autonomous Database 发送 Slack 通知。请参阅从自治 AI 数据库发送 Slack 通知。
EMAIL 工具:
注意:
电子邮件工具从 OCI 发送电子邮件通知。- 确定 SMTP 端点。例如,选择 SMTP 端点之一:
smtp.us-phoenix-1.oraclecloud.com smtp.us-ashburn-1.oraclecloud.com smtp.email.uk-london-1.oci.oraclecloud.com smtp.email.eu-frankfurt-1.oci.oraclecloud.com - 使用 ACL 授予 SMTP 访问权限。请参见 Configuring SMTP Connection 。
- 生成用于电子邮件传送的 SMTP 凭证。
UTL_SMTP软件包使用凭证在发送电子邮件时通过电子邮件传送服务器进行验证。有关更多信息,请参见 Generate SMTP Credentials for a User 。 - 创建批准的发件人对于您在
UTL_SMTP.MAIL子程序中用作From地址的所有电子邮件地址,请完成此步骤。有关详细信息,请参阅管理批准的发件人。 -
通过添加访问控制条目 (Access Control Entry,ACE) 授予用户 SMTP 访问权限。有关详细信息,请参阅在自治 AI 数据库上发送电子邮件。
DBMS_CLOUD_AI_AGENT 程序包中的内置工具类型
您可以使用 tool_type 和 tool_params 属性注册内置工具。
| 工具类型 | 说明 | 必需参数 |
|---|---|---|
|
|
将自然语言转换为 SQL 查询。 |
|
|
|
通过向量搜索执行检索增强生成。 |
|
|
|
向 Slack 通道发送消息或使用 SMTP 发送电子邮件。可用的选项:
|
如果 如果 |
|
|
从 Web 搜索信息。 |
|
ENABLE_TOOL 过程
使用 DBMS_CLOUD_AI_AGENT.ENABLE_TOOL 过程启用以前注册的工具。这将工具的状态更改为 ENABLED,允许代理使用其任务。
语法
DBMS_CLOUD_AI_AGENT.ENABLE_TOOL(
tool_name IN VARCHAR2
);参数
| Parameter (参数) | 说明 |
|---|---|
|
|
要启用的工具的名称。 此参数是必需的。 |
范例
BEGIN
DBMS_CLOUD_AI_AGENT.ENABLE_TOOL(
tool_name => 'SQL'
);
END;
/
DISABLE_TOOL 过程
使用 DBMS_CLOUD_AI_AGENT.DISABLE_TOOL 过程禁用已注册的工具。这将工具的状态更改为 DISABLED,以防止代理在任务中使用它。
语法
DBMS_CLOUD_AI_AGENT.DISABLE_TOOL(
tool_name IN VARCHAR2
);
参数
| Parameter (参数) | 说明 |
|---|---|
|
|
要禁用的工具的名称。 此参数是必需的。 |
范例
以下示例禁用现有工具。
BEGIN
DBMS_CLOUD_AI_AGENT.DISABLE_TOOL(
tool_name => 'SQL'
);
END;
/
DROP_TOOL 过程
使用 DBMS_CLOUD_AI_AGENT.DROP_TOOL 过程可删除以前向代理注册的工具。如果任务不存在,则可以通过将 force 参数设置为 TRUE 来抑制该错误。
语法
DBMS_CLOUD_AI_AGENT.DROP_TOOL(
tool_name IN VARCHAR2,
force IN BOOLEAN DEFAULT FALSE
);参数
| Parameter (参数) | 说明 |
|---|---|
|
|
要删除的工具的名称。 此项是必需参数。 |
|
|
如果为 此参数的默认值为 |
范例
BEGIN
DBMS_CLOUD_AI_AGENT.DROP_TOOL(tool_name => 'SQL');
END;
/使用说明
如果工具不存在,请使用 force 删除工具并忽略错误。
CREATE_TEAM 过程
使用 DBMS_CLOUD_AI_AGENT.CREATE_TEAM 过程定义协同工作以完成任务的 AI 代理团队。您可以指定代理及其关联任务,以及应如何处理任务。
语法
DBMS_CLOUD_AI_AGENT.CREATE_TEAM(
team_name IN VARCHAR2,
attributes IN CLOB,
status IN VARCHAR2 DEFAULT NULL,
description IN CLOB DEFAULT NULL
);参数
| Parameter (参数) | 说明 |
|---|---|
|
|
用于标识 AI 代理团队的唯一名称。 此项是必需参数。 |
|
|
JSON 格式的字符串,用于定义团队属性,例如代理和流程。请参见 CREATE_TEAM Attributes 。 此项是必需参数。 |
status |
团队的状态。 默认值为 |
|
|
用于标识团队用途的自定义说明。此值存储在数据库中,但不会发送到 LLM。 默认值为空值。 |
范例
以下示例将创建一个座席团队来处理客户的产品退货。
BEGIN
DBMS_CLOUD_AI_AGENT.CREATE_TEAM(
team_name => 'ReturnAgency',
attributes => '{"agents": [{"name":"Customer_Return_Agent","task" : "Return_And_Price_Match"}],
"process": "sequential"}');
END;
/
CREATE_TEAM 属性
team_name,并使用一组属性来定义其结构和执行策略。
属性
| 属性名称 | 默认值 | 说明 |
|---|---|---|
|
|
- |
指定列出代理及其相应任务的 JSON 数组。一个代理可以使用相同的名称分配给多个任务。 此项是必需参数。 示例:
|
|
|
- |
指定如何运行任务。将 |
SET_TEAM 函数
使用 DBMS_CLOUD_AI_AGENT.SET_TEAM 为当前会话指定 AI 代理团队。
设置团队后,仅启用 select ai agent 操作,系统不支持其他 Select AI 操作。
语法
DBMS_CLOUD_AI_AGENT.SET_TEAM(
team_name IN VARCHAR2,
);
参数
| Parameter (参数) | 说明 |
|---|---|
|
|
指定要在当前会话中使用的 AI 代理团队的名称。团队必须已存在于系统中。 此参数是必需的。 |
范例
以下示例在当前会话中设置用户指定的 AI 代理团队。
EXEC DBMS_CLOUD_AI_AGENT.SET_TEAM('ReturnAgency');
GET_TEAM 函数
使用 DBMS_CLOUD_AI_AGENT.GET_TEAM 返回当前会话的 AI 代理团队。
语法
DBMS_CLOUD_AI_AGENT.GET_TEAM RETURN VARCHAR2;
范例
以下示例返回当前会话中的 AI 代理团队。
SELECT DBMS_CLOUD_AI_AGENT.GET_TEAM from DUAL;
CLEAR_TEAM 函数
使用 DBMS_CLOUD_AI_AGENT.CLEAR_TEAM 清除当前会话中设置的 AI 代理团队。此过程不会删除团队。
语法
DBMS_CLOUD_AI_AGENT.CLEAR_TEAM;
范例
以下示例将清除当前会话中的 AI 代理团队。
BEGIN
DBMS_CLOUD_AI_AGENT.CLEAR_TEAM;
END;
/
RUN_TEAM 函数
使用 DBMS_CLOUD_AI_AGENT.RUN_TEAM 启动新的 AI 代理团队或恢复正在等待人工输入的已暂停团队。如果提供现有进程 ID 且关联的团队进程处于 WAITING_FOR_HUMAN 状态,则该函数将使用您提供的输入作为人工响应恢复工作流。
语法
DBMS_CLOUD_AI_AGENT.RUN_TEAM(
team_name IN VARCHAR2,
user_prompt IN CLOB DEFAULT NULL,
params IN CLOB DEFAULT NULL,
);
参数
| Parameter (参数) | 说明 |
|---|---|
|
|
指定要在当前会话中使用的 AI 代理团队的名称。团队必须已存在于系统中。 此参数是必需的。 |
|
|
指定为任务提供的用户查询或响应。 如果任务处于 如果任务处于 |
|
|
指定在 AI 代理团队处理期间使用的定制参数。支持的参数包括:
|
范例
以下示例在当前会话中运行用户指定的 AI 代理团队。
l_final_answer := DBMS_CLOUD_AI_AGENT.RUN_TEAM(
team_name => 'ReturnAgency',
user_prompt => 'I want to return computer desk chair',
params => '{"conversation_id": "' ||l_conversation_id || '"}'
);
ENABLE_TEAM 过程
使用 DBMS_CLOUD_AI_AGENT.ENABLE_TEAM 过程可启用用户指定的 AI 代理团队。这会将团队的状态更改为 ENABLED。
语法
DBMS_CLOUD_AI_AGENT.ENABLE_TEAM(
team_name IN VARCHAR2
);参数
| Parameter (参数) | 说明 |
|---|---|
|
|
要启用的 AI 代理团队的名称。 此参数是必需的。 |
范例
以下示例启用用户指定的 AI 代理团队。
BEGIN
DBMS_CLOUD_AI_AGENT.ENABLE_TEAM(
team_name => 'ReturnAgency'
);
END;
/
DISABLE_TEAM 过程
使用 DBMS_CLOUD_AI_AGENT.DISABLE_TEAM 过程禁用现有 AI 代理团队。这会将团队的状态更改为 DISABLED。
语法
DBMS_CLOUD_AI_AGENT.DISABLE_TEAM(
team_name IN VARCHAR2
);
参数
| Parameter (参数) | 说明 |
|---|---|
|
|
要禁用的 AI 代理团队的名称。 此参数是必需的。 |
范例
以下示例禁用现有 AI 代理团队。
BEGIN
DBMS_CLOUD_AI_AGENT.DISABLE_TEAM(
team_name => 'ReturnAgency'
);
END;
/
DROP_TEAM 过程
使用 DBMS_CLOUD_AI_AGENT.DROP_TEAM 过程删除以前创建的 AI 代理团队。
语法
DBMS_CLOUD_AI_AGENT.DROP_TEAM(
team_name IN VARCHAR2,
force IN BOOLEAN DEFAULT FALSE
);参数
| Parameter (参数) | 说明 |
|---|---|
|
|
要删除的团队的名称。 此项是必需参数。 |
|
|
如果为 此参数的默认值为 |
范例
BEGIN
DBMS_CLOUD_AI_AGENT.DROP_TEAM(team_name => 'ReturnAgency');
END;
/使用说明
如果团队不存在,请使用 force 删除团队并忽略错误。
For information about Oracle's commitment to accessibility, visit the Oracle Accessibility Program website at http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc.
获得 Oracle 支持
Oracle 客户访问和使用 Oracle 支持服务将遵循其适用服务的 Oracle 订单中规定的条款和条件。