Paquete DBMS_CLOUD_AI_AGENT

Este paquete define y gestiona agentes, tareas, herramientas y orquestación de Select AI.

Resumen de Subprogramas DBMS_CLOUD_AI_AGENT

En esta sección se tratan los subprogramas DBMS_CLOUD_AI_AGENT de Select AI Agent proporcionados con Autonomous AI Database.

CREATE_AGENT Procedimiento

Utilice el procedimiento DBMS_CLOUD_AI_AGENT.CREATE_AGENT para registrar un nuevo agente AI en el marco Select AI Agent. Defina la identidad del agente mediante agent_name, configure su comportamiento con el parámetro de atributos y, opcionalmente, proporcione una descripción.

Sintaxis

DBMS_CLOUD_AI_AGENT.CREATE_AGENT(
     agent_name          IN  VARCHAR2,
     attributes          IN  CLOB,
     status              IN  VARCHAR2  DEFAULT NULL,
     description         IN  CLOB      DEFAULT NULL
  );

Parámetros

Ejemplo

En el siguiente ejemplo, se crea un agente para procesar las devoluciones de productos del cliente. Para obtener un ejemplo completo, consulte Ejemplo: creación de un agente de devolución de producto.

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.

Atributos CREATE_AGENT

Estos atributos definen el rol de un agente y el nombre del perfil de AI.

Atributos

En el siguiente ejemplo, se muestra cómo puede personalizar los atributos de agente en el procedimiento.

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 completed

ENABLE_AGENT Procedimiento

Este procedimiento activa el agente AI que especifica el usuario. El procedimiento cambia el estado del agente AI a ENABLED.

Sintaxis

DBMS_CLOUD_AI_AGENT.ENABLE_AGENT(
   agent_name           IN  VARCHAR2
);

Parámetros

Ejemplo para activar el perfil AI

BEGIN
     DBMS_CLOUD_AI_AGENT.ENABLE_AGENT(
         agent_name    => 'Customer_Return_Agent'
     );
END;
/

DISABLE_AGENT Procedimiento

Este procedimiento desactiva el agente de AI en la base de datos actual. En este procedimiento, el estado del agente AI cambia a DISABLED.

Sintaxis

DBMS_CLOUD_AI_AGENT.DISABLE_AGENT(
   agent_name           IN  VARCHAR2
);

Parámetros

Ejemplo

BEGIN
     DBMS_CLOUD_AI_AGENT.DISABLE_AGENT(
         agent_name    => 'Customer_Return_Agent'
     );
END;
/

DROP_AGENT Procedimiento

El procedimiento elimina un agente de AI existente. Si el agente no existe, el procedimiento devuelve un error.

Sintaxis

DBMS_CLOUD_AI_AGENT.DROP_AGENT(
    agent_name          IN  VARCHAR2,
    force               IN  BOOLEAN DEFAULT FALSE
 );

Parámetros

Ejemplo

BEGIN
     DBMS_CLOUD_AI_AGENT.DROP_AGENT(agent_name => 'Customer_Return_Agent);
END;
/

Notas de uso

Utilice force para borrar un agente e ignorar los errores si el agente AI no existe.

CREATE_TASK Procedimiento

Utilice el procedimiento DBMS_CLOUD_AI_AGENT.CREATE_TASK para definir una tarea que un agente de Select AI puede incluir en su proceso de razonamiento. Cada tarea tiene un nombre único y un juego de atributos que especifican el comportamiento del agente al planificar y realizar la tarea.

Puede definir dependencias entre tareas mediante el atributo input, lo que permite que Select AI transfiera la salida de una tarea a otra. Esto admite el razonamiento encadenado y los flujos de trabajo de varios pasos.

Sintaxis

DBMS_CLOUD_AI_AGENT.CREATE_TASK(
     task_name           IN  VARCHAR2,
     attributes          IN  CLOB,
     status              IN  VARCHAR2  DEFAULT NULL,
     description         IN  CLOB      DEFAULT NULL
  );

Parámetros

Ejemplo

En el siguiente ejemplo, se crea una tarea para procesar una devolución de producto de un cliente.

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;
/

Atributos CREATE_TASK

Estos atributos definen las instrucciones y herramientas del agente disponibles para la tarea.

Atributos

SELECT AI AGENT \

ENABLE_TASK Procedimiento

Utilice el procedimiento DBMS_CLOUD_AI_AGENT.ENABLE_TASK para activar una tarea definida anteriormente. Esto cambia el estado de la tarea a ENABLED, lo que permite al agente utilizarla durante el procesamiento.

Sintaxis

DBMS_CLOUD_AI_AGENT.ENABLE_TASK(
   task_name           IN  VARCHAR2
);

Parámetros

Notas de uso

La tarea ya debe existir en el sistema. Este procedimiento actualiza el estado de la tarea para que esté disponible para el proceso de agente durante los flujos de trabajo de razonamiento.

Ejemplo para activar una tarea

BEGIN
     DBMS_CLOUD_AI_AGENT.ENABLE_TASK(
         task_name    => 'Return_And_Price_Match'
     );
END;
/

DISABLE_TASK Procedimiento

Utilice el procedimiento DBMS_CLOUD_AI_AGENT.DISABLE_TASK para desactivar una tarea en la base de datos actual. Esto cambia el estado de la tarea a DISABLED, lo que impide que el agente la utilice durante el procesamiento.

Sintaxis

DBMS_CLOUD_AI_AGENT.DISABLE_TASK(
   task_name           IN  VARCHAR2
);

Parámetros

Notas de uso

La desactivación de una tarea no la suprime; puede volver a activarla más tarde mediante DBMS_CLOUD_AI_AGENT.ENABLE_TASK. Una vez desactivada, la tarea se vuelve inactiva y el agente ya no la considera durante la selección de la tarea.

Ejemplo

En el siguiente ejemplo, se desactiva una tarea existente.

BEGIN
     DBMS_CLOUD_AI_AGENT.DISABLE_TASK(
         task_name    => 'Return_And_Price_Match'
     );
END;
/

DROP_TASK Procedimiento

Utilice el procedimiento DBMS_CLOUD_AI_AGENT.DROP_TASK para eliminar una tarea definida previamente de la base de datos. Si la tarea no existe, puede suprimir el error definiendo el parámetro force en TRUE.

Sintaxis

DBMS_CLOUD_AI_AGENT.DROP_TASK(
   task_name IN  VARCHAR2,
   force     IN  BOOLEAN DEFAULT FALSE
);

Parámetros

Ejemplo

BEGIN
     DBMS_CLOUD_AI_AGENT.DROP_TASK(task_name => 'Return_And_Price_Match');
END;
/

Notas de uso

Utilice force para borrar una tarea e ignorar los errores si la tarea no existe.

CREATE_TOOL Procedimiento

Utilice el procedimiento DBMS_CLOUD_AI_AGENT.CREATE_TOOL para registrar una herramienta personalizada que un agente puede utilizar durante el procesamiento de tareas. Cada herramienta se identifica mediante un tool_name único e incluye atributos que definen su finalidad, lógica de implantación y metadatos.

Las herramientas pueden ser funciones PL/SQL personalizadas o tipos de herramientas incorporadas como RAG, SQL, WEBSEARCH o NOTIFICATION.

Sintaxis

DBMS_CLOUD_AI_AGENT.CREATE_TOOL(
     tool_name          IN  VARCHAR2,
     attributes          IN  CLOB,
     status              IN  VARCHAR2  DEFAULT NULL,
     description         IN  CLOB      DEFAULT NULL
  );

Parámetros

Ejemplo

En el siguiente ejemplo se crea una herramienta SQL para generar SQL a partir de un perfil NL2SQL existente. Consulte Ejemplo: creación de herramientas incorporadas para obtener más información.

BEGIN
  DBMS_CLOUD_AI_AGENT.CREATE_TOOL(
    tool_name  => 'SQL',
    attributes => '{"tool_type": "SQL",
                    "tool_params": {"profile_name": "nl2sql_profile"}}'
  );
END;
/

Atributos CREATE_TOOL

Estos atributos proporcionan la configuración de la herramienta mediante un objeto JSON en el parámetro de atributos. Cada atributo configura el modo en que el agente utiliza la herramienta durante el razonamiento.

Atributos

"tool_inputs": [ 
  { 
    "name": "data_guard", 
    "description": "Only supported values are "Enabled" and "Disabled"" 
  } 
  ]

Requisitos previos para la herramienta incorporada

Realice estos pasos antes de utilizar las herramientas incorporadas:

Herramienta RAG

1. Cree un perfil de IA que haga referencia a un índice vectorial. Consulte Seleccionar AI con generación aumentada de recuperación (RAG).

Herramienta de notificación

Se admiten los siguientes elementos: SLACK y EMAIL.

Herramienta SLACK:

1. Configure una aplicación Slack para recibir mensajes de Autonomous AI Database.

2. Cree una credencial mediante DBMS_CLOUD_NOTIFICATION para enviar notificaciones de Slack desde Autonomous AI Database. Consulte Envío de notificaciones de Slack desde Autonomous AI Database.

Herramienta EMAIL:

Nota

Nota: la herramienta de correo electrónico envía una notificación por correo electrónico desde OCI.

1. Identifique el punto final SMTP. Por ejemplo, seleccione uno de los puntos finales 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

2. Otorgue acceso SMTP mediante una ACL. Consulte Configuración de la conexión SMTP.

3. Genere credenciales SMTP para la entrega de correo electrónico. El paquete UTL_SMTP utiliza credenciales para autenticarse con los servidores de Email Delivery al enviar un correo electrónico. Consulte Generación de credenciales SMTP para un usuario para obtener más información.

4. Creación de remitentes aprobados. Complete este paso para todas las direcciones de correo electrónico que utilice como dirección From con el subprograma UTL_SMTP.MAIL. Consulte Gestión de emisores aprobados para más información.

5. Otorgue acceso SMTP al usuario agregando la entrada de control de acceso (ACE). Para obtener más información, consulte Envío de correo electrónico desde una base de datos de IA autónoma mediante DBMS_CLOUD_NOTIFICATION.

Tipos de herramientas incorporadas en el paquete DBMS_CLOUD_AI_AGENT

Puede registrar herramientas incorporadas mediante los atributos tool_type y tool_params.

ENABLE_TOOL Procedimiento

Utilice el procedimiento DBMS_CLOUD_AI_AGENT.ENABLE_TOOL para activar una herramienta creada anteriormente. Esto cambia el estado de la herramienta a ENABLED, lo que permite al agente utilizar las tareas.

Sintaxis

DBMS_CLOUD_AI_AGENT.ENABLE_TOOL(
   tool_name           IN  VARCHAR2
);

Parámetros

Ejemplo

BEGIN
     DBMS_CLOUD_AI_AGENT.ENABLE_TOOL(
         tool_name    => 'SQL'
     );
END;
/

DISABLE_TOOL Procedimiento

Utilice el procedimiento DBMS_CLOUD_AI_AGENT.DISABLE_TOOL para desactivar una herramienta. Esto cambia el estado de la herramienta a DISABLED, lo que impide que el agente lo utilice en tareas.

Sintaxis

DBMS_CLOUD_AI_AGENT.DISABLE_TOOL(
   tool_name           IN  VARCHAR2
);

Parámetros

Ejemplo

En el siguiente ejemplo, se desactiva una herramienta existente.

BEGIN
     DBMS_CLOUD_AI_AGENT.DISABLE_TOOL(
         tool_name    => 'SQL'
     );
END;
/

DROP_TOOL Procedimiento

Utilice el procedimiento DBMS_CLOUD_AI_AGENT.DROP_TOOL para eliminar una herramienta creada previamente con el agente. Si la tarea no existe, puede suprimir el error definiendo el parámetro force en TRUE.

Sintaxis

DBMS_CLOUD_AI_AGENT.DROP_TOOL(
   tool_name IN  VARCHAR2,
   force     IN  BOOLEAN DEFAULT FALSE
);

Parámetros

Ejemplo

BEGIN
     DBMS_CLOUD_AI_AGENT.DROP_TOOL(tool_name => 'SQL');
END;
/

Notas de uso

Utilice force para borrar una herramienta e ignorar los errores si la herramienta no existe.

CREATE_TEAM Procedimiento

Utilice el procedimiento DBMS_CLOUD_AI_AGENT.CREATE_TEAM para definir un equipo de agentes de IA que trabajen juntos para realizar tareas. Puede especificar agentes y sus tareas asociadas, junto con la forma en que se deben procesar las tareas.

Sintaxis

DBMS_CLOUD_AI_AGENT.CREATE_TEAM(
   team_name    IN VARCHAR2,
   attributes   IN CLOB,
   status       IN VARCHAR2 DEFAULT NULL,
   description  IN CLOB     DEFAULT NULL
);

Parámetros

Ejemplo

En el siguiente ejemplo, se crea un equipo de agente para procesar la devolución de productos de un cliente.

BEGIN
  DBMS_CLOUD_AI_AGENT.CREATE_TEAM(
    team_name  => 'ReturnAgency',
    attributes => '{"agents": [{"name":"Customer_Return_Agent","task" : "Return_And_Price_Match"}],
                    "process": "sequential"}');
END;
/

Atributos CREATE_TEAM

Estos atributos proporcionan la configuración del equipo del agente de AI. Cada equipo tiene un team_name único y utiliza un juego de atributos para definir su estructura y estrategia de ejecución.

Atributos

[ {"name": "", "task": "" ]

Función SET_TEAM

Utilice DBMS_CLOUD_AI_AGENT.SET_TEAM para especificar el equipo de agente de AI para la sesión actual.

Una vez que se define un equipo, solo se activa la acción select ai agent, el sistema no admite otras acciones de selección de IA.

Sintaxis

DBMS_CLOUD_AI_AGENT.SET_TEAM(
    team_name      IN  VARCHAR2,
);

Parámetros

Ejemplo

En el siguiente ejemplo, se define el equipo de agente de AI especificado por el usuario en la sesión actual.

EXEC DBMS_CLOUD_AI_AGENT.SET_TEAM('ReturnAgency');

Función GET_TEAM

Utilice DBMS_CLOUD_AI_AGENT.GET_TEAM para devolver el equipo de agente de AI para la sesión actual.

Sintaxis

DBMS_CLOUD_AI_AGENT.GET_TEAM RETURN VARCHAR2;

Ejemplo

En el siguiente ejemplo, se devuelve el equipo del agente de AI en la sesión actual.

SELECT DBMS_CLOUD_AI_AGENT.GET_TEAM from DUAL;

Función CLEAR_TEAM

Utilice DBMS_CLOUD_AI_AGENT.CLEAR_TEAM para borrar el equipo de agente de AI definido en la sesión actual. Este procedimiento no elimina al equipo.

Sintaxis

DBMS_CLOUD_AI_AGENT.CLEAR_TEAM;

Ejemplo

En el siguiente ejemplo, se borra el equipo del agente de IA en la sesión actual.

BEGIN
  DBMS_CLOUD_AI_AGENT.CLEAR_TEAM;
END;
/

Función RUN_TEAM

Utilice DBMS_CLOUD_AI_AGENT.RUN_TEAM para iniciar un nuevo equipo de agentes de IA o reanudar uno en pausa que esté esperando la entrada humana. Si proporciona un ID de proceso existente y el proceso de equipo asociado tiene el estado WAITING_FOR_HUMAN, la función reanuda el flujo de trabajo utilizando la entrada que proporciona como respuesta humana.

Sintaxis

DBMS_CLOUD_AI_AGENT.RUN_TEAM(
     team_name               IN  VARCHAR2,
     user_prompt             IN  CLOB DEFAULT NULL,
     params                  IN  CLOB DEFAULT NULL,
  );

Parámetros

Ejemplo

En el siguiente ejemplo, se ejecuta el equipo de agente de AI especificado por el usuario en la sesión actual.

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 Procedimiento

Utilice el procedimiento DBMS_CLOUD_AI_AGENT.ENABLE_TEAM para activar un equipo de agente de AI especificado por el usuario. Esto cambia el estado del equipo a ENABLED.

Sintaxis

DBMS_CLOUD_AI_AGENT.ENABLE_TEAM(
   team_name           IN  VARCHAR2
);

Parámetros

Ejemplo

En el siguiente ejemplo, se activa un equipo de agentes de AI especificado por el usuario.

BEGIN
     DBMS_CLOUD_AI_AGENT.ENABLE_TEAM(
         team_name    => 'ReturnAgency'
     );
END;
/

DISABLE_TEAM Procedimiento

Utilice el procedimiento DBMS_CLOUD_AI_AGENT.DISABLE_TEAM para desactivar un equipo de agente de AI existente. Esto cambia el estado del equipo a DISABLED.

Sintaxis

DBMS_CLOUD_AI_AGENT.DISABLE_TEAM(
   team_name           IN  VARCHAR2
);

Parámetros

Ejemplo

En el siguiente ejemplo, se desactiva un equipo de agentes de IA existente.

BEGIN
     DBMS_CLOUD_AI_AGENT.DISABLE_TEAM(
         team_name    => 'ReturnAgency'
     );
END;
/

DROP_TEAM Procedimiento

Utilice el procedimiento DBMS_CLOUD_AI_AGENT.DROP_TEAM para eliminar un equipo de agente de AI creado anteriormente.

Sintaxis

DBMS_CLOUD_AI_AGENT.DROP_TEAM(
   team_name IN  VARCHAR2,
   force     IN  BOOLEAN DEFAULT FALSE
);

Parámetros

Ejemplo

BEGIN
     DBMS_CLOUD_AI_AGENT.DROP_TEAM(team_name => 'ReturnAgency');
END;
/

Notas de uso

Utilice force para borrar un equipo e ignorar los errores si el equipo no existe.

Función DESCRIBE_TOOL

Utilice la función DBMS_CLOUD_AI_AGENT.DESCRIBE_TOOL para devolver metadatos JSON para una herramienta. El resultado incluye el nombre de la herramienta, la descripción, los atributos y la información del esquema de entrada que un cliente compatible con MCP puede utilizar para la detección de herramientas.

Sintaxis

DBMS_CLOUD_AI_AGENT.DESCRIBE_TOOL(
  tool_name IN VARCHAR2
) RETURN CLOB;

Parámetros

Devoluciones

Devuelve un valor CLOB que contiene metadatos de herramientas con formato JSON e información de argumentos.

Ejemplo

DECLARE
  l_result CLOB;
BEGIN
  l_result := DBMS_CLOUD_AI_AGENT.DESCRIBE_TOOL(
    tool_name => 'FETCH_LOG_TOOL'
  );

  DBMS_OUTPUT.PUT_LINE(l_result);
END;
/

Función RUN_TOOL

Utilice la función DBMS_CLOUD_AI_AGENT.RUN_TOOL para llamar a una herramienta creada por nombre. El parámetro de entrada transfiere los argumentos de la herramienta como carga útil de JSON.

Sintaxis

DBMS_CLOUD_AI_AGENT.RUN_TOOL(
  tool_name IN VARCHAR2,
  input IN CLOB
) RETURN CLOB;

Parámetros

Devoluciones

Devuelve un CLOB que contiene el resultado de ejecución de la herramienta.

Ejemplo

SELECT DBMS_CLOUD_AI_AGENT.RUN_TOOL(
  tool_name => 'FETCH_LOG_TOOL',
  input => '{"P_SINCE":"2026-01-01"}'
) AS tool_result
FROM dual;

Función LIST_TEAMS

Utilice la función DBMS_CLOUD_AI_AGENT.LIST_TEAMS para enumerar los equipos de agentes disponibles para el usuario que realiza la llamada. El resultado puede ser utilizado por las capas de integración compatibles con A2A para el descubrimiento de equipos.

Sintaxis

DBMS_CLOUD_AI_AGENT.LIST_TEAMS
  RETURN CLOB;

Parámetros

Devoluciones

Devuelve un CLOB que contiene una matriz JSON. Cada entrada incluye el nombre y la descripción del equipo.

Ejemplo

SELECT DBMS_CLOUD_AI_AGENT.LIST_TEAMS()
FROM dual;

Función DESCRIBE_TEAM

Utilice la función DBMS_CLOUD_AI_AGENT.DESCRIBE_TEAM para devolver metadatos para un equipo de agente. La función asigna las herramientas Seleccionar agente de IA disponibles para el equipo a la representación de aptitudes compatibles con A2A.

Sintaxis

DBMS_CLOUD_AI_AGENT.DESCRIBE_TEAM(
  team_name IN VARCHAR2
) RETURN CLOB;

Parámetros

Devoluciones

Devuelve un CLOB que contiene un objeto JSON con el nombre del equipo, la descripción, la versión opcional y la lista de aptitudes.

Notas de uso

• Las habilidades son una representación de protocolo de herramientas para clientes compatibles con A2A. No introducen un nuevo tipo de objeto de base de datos Seleccionar agente AI.

Ejemplo

SELECT DBMS_CLOUD_AI_AGENT.DESCRIBE_TEAM('SUPPORT_TEAM')
FROM dual;

Función GET_TEAM_STATE

Utilice la función DBMS_CLOUD_AI_AGENT.GET_TEAM_STATE para devolver el último estado de ejecución de una conversación de equipo de agente.

Sintaxis

DBMS_CLOUD_AI_AGENT.GET_TEAM_STATE(
  team_name IN VARCHAR2,
  params IN CLOB DEFAULT NULL
) RETURN VARCHAR2;

Parámetros

Devoluciones

Devuelve un estado de ejecución VARCHAR2, como RUNNING, WAITING_FOR_HUMAN, SUCCEEDED o FAILED.

Ejemplo

SELECT DBMS_CLOUD_AI_AGENT.GET_TEAM_STATE(
  team_name => 'SUPPORT_TEAM',
  params => '{"conversation_id":"<CONVERSATION_ID>"}'
)
FROM dual;

Procedimiento SET_EXECUTION_STATE

Utilice el procedimiento DBMS_CLOUD_AI_AGENT.SET_EXECUTION_STATE para actualizar una ejecución de equipo de espera a un estado especificado. Esto resulta útil para los flujos de trabajo de llamada de herramienta directa de agente en los que la aplicación controla cuando se completa la sesión interactiva.

Sintaxis

DBMS_CLOUD_AI_AGENT.SET_EXECUTION_STATE(
  team_name IN VARCHAR2,
  state IN CLOB DEFAULT 'SUCCEEDED',
  params IN CLOB DEFAULT NULL
);

Parámetros

Ejemplo

BEGIN
  DBMS_CLOUD_AI_AGENT.SET_EXECUTION_STATE(
    team_name => 'CUSTOMER_AGENT_ONLY_TEAM',
    state => 'SUCCEEDED',
    params => '{"conversation_id":"<CONVERSATION_ID>"}'
  );
END;
/