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

Notas de uso

• profile_name identifica el perfil de IA utilizado para las llamadas del LLM.
• supervisor es opcional y se define por defecto en false.
• Defina supervisor en true solo para los agentes que controlan el enrutamiento del equipo.
• No puede actualizar la opción de supervisor después de la creación del agente.
• Mantenga las instrucciones de tareas específicas del trabajador fuera del supervisor cuando sea posible; colóquelas en las tareas del trabajador.

Ejemplo: creación de un agente de supervisor

En este ejemplo, se crea un agente supervisor que puede controlar un equipo y delegar subtareas a agentes de trabajadores configurados.

BEGIN
  DBMS_CLOUD_AI_AGENT.CREATE_AGENT(
    agent_name => 'ORCHESTRATOR_AGENT',
    attributes => '{
      "profile_name": "<AI_PROFILE_NAME>",
      "role": "Route requests to the appropriate worker agent.",
      "supervisor": true
    }',
    description => 'Routes subtasks to worker agents'
  );
END;
/

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": "" ]

Notas de uso

Revise las reglas de atributos de equipo antes de crear un equipo supervisado para que las asignaciones de supervisor y trabajador permanezcan separadas.

• supervisor_agent nombra el objeto de agente de supervisor que controla el equipo.
• agents muestra los pares de agente y tarea de trabajador disponibles para delegación.
• No muestre el supervisor seleccionado como trabajador en la matriz agents.
• Utilice process con la definición de equipo. El diseño del supervisor inicial requiere sequential; una subtarea de trabajador debe finalizar antes de que el supervisor delegue la siguiente subtarea.

Ejemplo: creación de un equipo dirigido por un supervisor

En este ejemplo, se crea un equipo supervisado con pares de cuentas y tareas de agente de trabajador de pago disponibles para el objeto de agente de supervisor.

BEGIN
  DBMS_CLOUD_AI_AGENT.CREATE_TEAM(
    team_name => 'CUSTOMER_SUPPORT',
    attributes => '{
      "process": "sequential",
      "supervisor_agent": "ORCHESTRATOR_AGENT",
      "agents": [
        {"name":"ACCOUNT_AGENT", "task":"ACCOUNT_MANAGEMENT_TASK"},
        {"name":"PAYMENT_AGENT", "task":"PAYMENT_MANAGEMENT_TASK"}
      ]
    }'
  );
END;
/

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

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

Función EXPORT_TEAM

Utilice la función DBMS_CLOUD_AI_AGENT.EXPORT_TEAM para exportar todos los agentes, tareas y herramientas asociadas de un equipo de agentes a una cadena. La función toma team_name y params opcional como entrada y devuelve la definición de equipo exportada como CLOB.

Sintaxis

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

Parámetros

Notas de uso

• EXPORT_TEAM exporta la definición de equipo y los metadatos asociados para el equipo de Seleccionar agente de IA especificado.

• La exportación incluye el equipo y sus agentes, herramientas y tareas relacionados que forman parte de la especificación del equipo.

• La exportación no incluye definiciones de credenciales ni contraseñas de credenciales. Conserva solo los nombres de credenciales a los que se hace referencia cuando corresponde.

• La exportación no incluye implementaciones de soporte creadas por el usuario fuera de la especificación exportada. Estas dependencias excluidas incluyen procedimientos y funciones PL/SQL del cliente que utilizan las herramientas, los servicios REST externos, OCI Functions, las funciones AWS Lambda, las ACL de red y otros recursos externos.

• La exportación de las herramientas Select AI incorporadas incluye la definición de la herramienta en la especificación del equipo.

• Asegúrese de que la configuración de soporte necesaria existe en el entorno de destino antes de importar y utilizar el equipo exportado.

• Si el equipo, los agentes, las herramientas o las tareas exportados están desactivados, la especificación exportada incluye metadatos que marcan esos componentes como desactivados.

• Si Select AI Agent crea una tarea automáticamente durante la importación del equipo del agente porque la especificación importada no incluye una definición de tarea, la tarea generada no se incluye cuando el equipo del agente se vuelve a exportar. Solo se exportan las tareas definidas explícitamente en el equipo del agente.

• Si el CLOB devuelto es grande, escríbalo en fragmentos cuando lo guarde en un archivo.

Ejemplo

En el siguiente ejemplo, se exporta el equipo ReturnAgency a CLOB y se escribe la salida en un archivo mediante UTL_FILE.

DECLARE
  output          clob;
  params_clob     clob;
  file_handler    UTL_FILE.FILE_TYPE;
BEGIN
  output := DBMS_CLOUD_AI_AGENT.EXPORT_TEAM(
              team_name => 'ReturnAgency'
  );
END;
/
/

Procedimiento EXPORT_TEAM

Utilice el procedimiento DBMS_CLOUD_AI_AGENT.EXPORT_TEAM para exportar una definición de equipo de agente, incluidos sus agentes, tareas y definiciones de herramientas asociadas, a una cadena. El procedimiento escribe la definición de equipo exportada en un URI de Object Storage o en un archivo de directorio de base de datos cuando el valor de ubicación incluye el objeto de directorio y el nombre de archivo. El procedimiento toma un valor params opcional como entrada y devuelve la definición de equipo exportada como CLOB.

Sintaxis

DBMS_CLOUD_AI_AGENT.EXPORT_TEAM(
    team_name                        IN VARCHAR2,
    object_storage_credential_name   IN VARCHAR2,
    location                         IN VARCHAR2,
    params                           IN CLOB     DEFAULT NULL
  );

Parámetros

Notas de uso

• EXPORT_TEAM exporta la definición de equipo y los metadatos asociados para el equipo de Seleccionar agente de IA especificado.

• La exportación incluye el equipo y sus agentes, herramientas y tareas relacionados que forman parte de la especificación del equipo.

• La exportación no incluye definiciones de credenciales ni contraseñas de credenciales. Conserva solo los nombres de credenciales a los que se hace referencia cuando corresponde.

• La exportación no incluye implementaciones de soporte creadas por el usuario fuera de la especificación exportada.

• La exportación de las herramientas Select AI incorporadas incluye la definición de la herramienta en la especificación del equipo.

• Asegúrese de que la configuración de soporte necesaria existe en el entorno de destino antes de importar y utilizar el equipo exportado.

• Si el equipo, los agentes, las herramientas o las tareas exportados están desactivados, la especificación exportada incluye metadatos que marcan esos componentes como desactivados.

• Si Select AI Agent crea una tarea automáticamente durante la importación del equipo del agente porque la especificación importada no incluye una definición de tarea, la tarea generada no se incluye cuando el equipo del agente se vuelve a exportar. Solo se exportan las tareas definidas explícitamente en el equipo del agente.

Ejemplos

En el siguiente ejemplo, se exporta el equipo ReturnAgency y se escribe la salida exportada en la ubicación de Object Storage especificada.

DECLARE
  output          clob;
  params_clob     clob;
BEGIN
  DBMS_CLOUD_AI_AGENT.export_team(
              team_name => 'ReturnAgency',
              object_storage_credential_name  => 'OBJ_STORAGE_CRED',
              location => 'https://swiftobjectstorage.us-ashburn-1.oraclecloud.com/v1/my_namespace/my_bucket/my_data_folder/return_agency.json',
	            params => '{"overwrite": true}'

  );
END;
/

En el siguiente ejemplo se exporta el equipo ReturnAgency a un archivo de directorio de base de datos.

BEGIN
  DBMS_CLOUD_AI_AGENT.EXPORT_TEAM(
    team_name => 'ReturnAgency',
    location  => 'MY_DIR:return_agency.json'
  );
END;
/

Procedimiento IMPORT_TEAM

Utilice el procedimiento DBMS_CLOUD_AI_AGENT.IMPORT_TEAM para importar una especificación de equipo de agente a la base de datos. La especificación puede incluir metadatos de equipo y definiciones de agente, tarea y herramienta relacionadas. Solo importa la información almacenada en la especificación del equipo y el perfil de IA asociado. Puede proporcionar una cadena de especificación, una credencial y una ubicación de Object Storage o una ubicación de archivo de directorio de base de datos para importar la definición de equipo de un archivo.

Sintaxis

DBMS_CLOUD_AI_AGENT.IMPORT_TEAM(
    profile_name                   IN VARCHAR2,
    team_name                      IN VARCHAR2 DEFAULT NULL,
    specification                  IN CLOB     DEFAULT NULL,
    object_storage_credential_name IN VARCHAR2 DEFAULT NULL,
    location                       IN VARCHAR2 DEFAULT NULL,
    force                          IN BOOLEAN  DEFAULT FALSE
);

Parámetros

Notas de uso

• IMPORT_TEAM importa solo los componentes definidos en la especificación de equipo proporcionada.

• Import crea el equipo y sus agentes, herramientas y tareas relacionados que están presentes en la especificación.

• El parámetro specification y la combinación de object_storage_credential_name y location utilizan el mismo comportamiento de importación. La única diferencia es el origen del contenido de la especificación.

• La importación no crea recursos dependientes que no formen parte de la especificación. Estos recursos incluyen credenciales, procedimientos y funciones PL/SQL creados por el cliente, servicios REST externos, funciones de OCI, funciones de AWS Lambda, ACL de red, puntos finales, perfiles, índices y otros recursos de soporte externos. Cree estas dependencias por separado en el entorno de destino antes de utilizar el equipo importado.

• Las herramientas de selección de IA incorporadas no requieren recreación manual como definiciones de componentes importados. Sin embargo, cualquier configuración de entorno necesaria para esas herramientas ya debe existir en la base de datos de destino.

• Si la especificación no incluye una tarea, DBMS_CLOUD_AI_AGENT puede crear automáticamente una tarea durante la importación. Esta tarea generada es metadatos creados por el sistema y no es equivalente a una tarea definida explícitamente en la especificación de origen.

• Si force se define en TRUE, la importación comprueba los componentes importados en conflicto existentes por nombre, como agente, herramienta o tarea. Cuando se produce un conflicto, la importación borra el componente existente con el mismo nombre y vuelve a crear ese componente a partir de la especificación de importación. Este comportamiento solo se aplica a los componentes importados en conflicto.

• Este procedimiento no borra ni vuelve a crear dependencias externas ni recursos asociados que no forman parte de la especificación, como las funciones PL/SQL creadas por el cliente, las credenciales o las ACL de red.

• Si la especificación importada contiene metadatos que marcan el equipo, los agentes, las herramientas o las tareas como desactivados, Select AI Agent importa esos componentes como desactivados.

Ejemplos

Importar un equipo desde un archivo en Object Storage

En este ejemplo, se importa una definición de equipo de un archivo JSON almacenado en Object Storage. Utilice este método cuando ya haya exportado la definición de equipo a un archivo. En el siguiente ejemplo se importa el equipo ReturnAgency.

BEGIN
  DBMS_CLOUD_AI_AGENT.IMPORT_TEAM(
    profile_name                   => 'PROFILE_NAME',
    team_name                      => 'Marketing',
    object_storage_credential_name => 'cred1',
    location                       => 'https://swiftobjectstorage.us-ashburn-1.oraclecloud.com/v1/my_namespace/my_bucket/my_data_folder/return_agency.json'
  );
END;
/

Importación de un equipo desde un archivo de directorio

Importe una definición de equipo de agente Select AI desde un archivo JSON almacenado en un objeto de directorio. El parámetro location especifica el objeto de directorio y el nombre de archivo.

BEGIN
    DBMS_CLOUD_AI_AGENT.import_team(
        profile_name 		=> 'PROFILE_NAME',
        team_name 		=> 'returnagency',
        location 		=> 'MY_DIR:return_agency.json'
  );
END;
/

Importar un equipo de una especificación transferida como CLOB

En este ejemplo, se crean primero las funciones creadas por el usuario necesarias y, a continuación, se importa el equipo desde una especificación JSON almacenada en CLOB. Utilice este método al crear o modificar la definición de equipo dentro de PL/SQL.

-- Create required functions first

CREATE OR REPLACE FUNCTION run_sql(nl_query IN CLOB)
RETURN CLOB
IS
  v_query CLOB;
BEGIN
  v_query := '(Name,Description,Category,Date Created,Price,Discounted Price,Offer Expiration Date)
("AquaPure Water Pitcher", "2-liter BPA-free water pitcher with filter", "Kitchen", "2024-04-12", 34.95, 27.95, "2024-07-01")
("CozyLuxe Throw Blanket", "Ultra-soft microfiber throw blanket (50""x60"")", "Living Room", "2024-03-22", 19.99, None, None)
("SafeStep Bath Mat", "Non-slip bath mat, mildew resistant, gray", "Bathroom", "2024-05-05", 12.50, 9.99, "2024-06-15")
("PowerPlug Extension", "6-outlet surge protector power strip", "Electrical", "2024-01-10", 21.75, None, None)
("FreshGuard Storage Bags", "Set of 20 reusable silicone food storage bags", "Kitchen", "2024-03-17", 15.60, 12.48, "2024-06-10")';

  RETURN v_query;
END run_sql;
/

CREATE OR REPLACE FUNCTION email(contents IN CLOB)
RETURN CLOB
IS
BEGIN
  DBMS_OUTPUT.PUT_LINE('>>>>>>>> Agent generated:' || CHR(10) ||
                       contents || CHR(10) ||
                       '<<<<<<<<<');
  RETURN 'Email sent successfully';
END email;
/

DECLARE
  l_input_json CLOB;
BEGIN
  l_input_json :=
  q'[
{
    "agents": [],
    "component_type": "Agent",
    "description": "You are a marketing agent who helps plan campaigns.",
    "flows": [],
    "id": "1d02da...",
    "inputs": [],
    "llm_config": {
        "component_type": "OCI_CONFIG",
        "default_generation_parameters": {
            "max_tokens": null,
            "temperature": null,
            "top_p": null
        },
        "description": null,
        "id": "9e2a1...",
        "metadata": {},
        "model_id": "gpt-5.5",
        "name": "openai/gpt-5.5"
    },
    "metadata": {},
    "name": "Marketing assistant",
    "outputs": [],
    "system_prompt": "Help the user with tasks around marketing products for their business.",
    "tools": [
        {
            "component_type": "ServerTool",
            "description": "Send an email to the current user.",
            "id": "9fcc6...",
            "inputs": [
                {
                    "title": "content",
                    "type": "string"
                }
            ],
            "metadata": {},
            "name": "Email",
            "outputs": [
                {
                    "type": "string"
                }
            ]
        },
        {
            "component_type": "ServerTool",
            "description": "Generates a SQL query for the given natural language question, runs it, and returns the results.",
            "id": "ae1e6...",
            "inputs": [
                {
                    "title": "nl_query",
                    "type": "string"
                }
            ],
            "metadata": {},
            "name": "run_sql",
            "outputs": [
                {
                    "type": "string"
                }
            ]
        }
    ]
}
]';

  DBMS_CLOUD_AI_AGENT.IMPORT_TEAM(
    profile_name  => 'PROFILE_NAME',
    team_name     => 'TEAM_NAME',
    specification => l_input_json
  );
END;
/

Función GET_DEFINITION

Utilice la función DBMS_CLOUD_AI_AGENT.GET_DEFINITION para devolver la definición canónica PL/SQL de un objeto de agente de AI existente. La función reconstruye la definición mediante CREATE_AGENT, CREATE_TOOL, CREATE_TASK o CREATE_TEAM, según el tipo de objeto solicitado.

Por defecto, la función devuelve solo el objeto solicitado. Definadependen_objects en true cuando la definición de equipo devuelta debe incluir las definiciones de agente dependiente, tarea y herramienta necesarias para volver a crear el equipo.

Sintaxis

DBMS_CLOUD_AI_AGENT.GET_DEFINITION(
  object_type IN VARCHAR2,
  object_name IN VARCHAR2,
  params      IN CLOB DEFAULT NULL
) RETURN CLOB;

Parámetros

Devoluciones

Devuelve un CLOB que contiene uno o más bloques PL/SQL ejecutables canónicos. El bloque devuelto utiliza el procedimiento de creación para el tipo de objeto solicitado.

Notas de uso

• La función devuelve definiciones para objetos que son propiedad del emisor de llamada actual. No se incluyen el esquema cruzado ni los objetos otorgados o compartidos.
• Cuando se omite params o dependent_objects no es true, la salida solo contiene la definición de objeto solicitada. Hace referencia a objetos dependientes por nombre público; sin embargo, no incluye sus bloques de creación.
• Cuando dependent_objects es true, la salida incluye la definición de objeto solicitada y las definiciones dependientes necesarias para volver a crear el equipo.
• La definición devuelta conserva el contenido JSON estructurado orientado al usuario y excluye los atributos ocultos, los metadatos de vinculación interna y el contenido solo de implantación. Los nombres de credenciales públicas pueden aparecer cuando sea necesario para la recreación; sin embargo, no se devuelven valores secretos.

Ejemplo

Devolver una definición de equipo sin objetos dependientes y, a continuación, devolver la definición de equipo con objetos dependientes.

SELECT DBMS_CLOUD_AI_AGENT.GET_DEFINITION(
  object_type => 'TEAM',
  object_name => 'TEAM_NAME'
) AS definition
FROM dual;

SELECT DBMS_CLOUD_AI_AGENT.GET_DEFINITION(
  object_type => 'TEAM',
  object_name => 'TEAM_NAME',
  params      => '{"dependent_objects": true}'
) AS definition
FROM dual;