Pacote DBMS_CLOUD_AI_AGENT

Este pacote define e gerencia agentes, tarefas, ferramentas e orquestração do Select AI.

Observação: O suporte para o pacote DBMS_CLOUD_AI_AGENT está disponível no Oracle Database 19c a partir da versão 19.29 e no Oracle Database 26ai a partir da versão 23.26.

Resumo dos Subprogramas DBMS_CLOUD_AI_AGENT

Esta seção abrange os subprogramas DBMS_CLOUD_AI_AGENT do Select AI Agent fornecidos com o Autonomous AI Database.

Subprograma	Descrição
Procedimento CREATE_AGENT	Este procedimento cria um agente.
Atributos CREATE_AGENT	Fornece atributos para criar um agente.
Procedimento ENABLE_AGENT	Este procedimento ativa um agente.
Procedimento DISABLE_AGENT	Este procedimento desativa um agente.
Procedimento DROP_AGENT	Este procedimento elimina um agente existente.
Procedimento CREATE_TASK	Este procedimento cria uma tarefa que um agente e uma equipe de agente podem incluir.
Atributos CREATE_TASK	Fornece atributos para criar uma tarefa do agente.
Procedimento ENABLE_TASK	Este procedimento ativa uma tarefa do agente.
Procedimento DISABLE_TASK	Este procedimento desativa uma tarefa do agente.
Procedimento DROP_TASK	Este procedimento elimina uma tarefa de agente existente.
Procedimento CREATE_TOOL	Este procedimento cria ferramentas personalizadas que um agente pode incluir.
Atributos CREATE_TOOL	Fornece atributos para criar ferramentas.
Procedimento ENABLE_TOOL	Este procedimento ativa uma ferramenta registrada.
Procedimento DISABLE_TOOL	Este procedimento desativa uma ferramenta registrada.
Procedimento DROP_TOOL	Este procedimento elimina uma ferramenta existente.
Procedimento CREATE_TEAM	Este procedimento cria uma equipe de agente e inclui agentes e tarefas.
Atributos CREATE_TEAM	Fornece atributos para criar uma equipe de agente.
Função SET_TEAM	Este procedimento define a equipe do agente na sessão atual.
Função GET_TEAM	Este procedimento retorna a equipe do agente definida na sessão atual.
Função CLEAR_TEAM	Este procedimento limpa a equipe do agente definida na sessão atual.
Função RUN_TEAM	Este procedimento cria um novo agente ou executa um pausado.
Procedimento ENABLE_TEAM	Este procedimento permite que uma equipe de agentes.
Procedimento DISABLE_TEAM	Este procedimento desativa uma equipe de agente.
Procedimento DROP_TEAM	Este procedimento elimina uma equipe de agente existente.
Função DESCRIBE_TOOL	Retorna informações de metadados e esquema de entrada para uma ferramenta Selecionar Agente de IA.
Função RUN_TOOL	Chama uma ferramenta Selecionar Agente de IA por nome usando um payload de entrada JSON.
Função LIST_TEAMS	Lista as equipes de agentes disponíveis para o usuário que fez a chamada.
Função DESCRIBE_TEAM	Retorna metadados e recursos agregados para uma equipe de agente selecionada.
Função GET_TEAM_STATE	Retorna o estado de execução mais recente de uma conversa da equipe do agente.
Procedimento SET_EXECUTION_STATE	Atualiza um estado de execução da equipe de espera, como marcar uma sessão interativa como bem-sucedida.

Procedimento CREATE_AGENT

Use o procedimento DBMS_CLOUD_AI_AGENT.CREATE_AGENT para registrar um novo agente do AI na estrutura Selecionar Agente do AI. Defina a identidade do agente usando agent_name, configure seu comportamento com o parâmetro de atributos e, opcionalmente, forneça uma descrição.

Sintaxe

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

Parâmetro	Descrição
`agent_name`	Um nome para o agente AI. O nome do agente deve seguir as regras de nomenclatura do identificador Oracle SQL. O tamanho máximo do nome é de 125 caracteres. Este é um parâmetro obrigatório.
`attributes`	Atributos personalizados para o agente AI. Consulte Atributos CREATE_AGENT para obter mais detalhes.
`status`	Status do agente. O valor padrão é `enabled`. de
`description`	Descrição especificada pelo usuário para o agente AI. O valor padrão é NULL.

Exemplo

O exemplo a seguir cria um agente para processar devoluções de produtos do cliente. Para obter um exemplo completo, consulte Exemplo: Criar um Agente de Devolução de Produto.

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

Atributos CREATE_AGENT

Esses atributos definem a função de um agente e o nome do perfil do AI.

Atributos

Nome do Atributo	Valor padrão	Descrição
`profile_name`	-	O perfil de IA que o agente está usando para enviar solicitação ao LLM. Este é um parâmetro obrigatório.
`role`	-	Defina a função do agente e forneça contexto ao agente. Isso é enviado ao LLM. Este é um parâmetro obrigatório.
`enable_human_tool`	`True`	Permite que o agente faça perguntas ao usuário para obter informações ou esclarecimentos.
`short_term_memory_length`	30	Especifica o número máximo de giros de conversa incluídos em cada chamada do LLM para uma execução de tarefa.

O exemplo a seguir mostra como você pode personalizar atributos de agente no procedimento.

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

Procedimento ENABLE_AGENT

Este procedimento ativa o agente do AI que o usuário especifica. O procedimento altera o status do agente do AI para ENABLED.

Sintaxe

DBMS_CLOUD_AI_AGENT.ENABLE_AGENT(
   agent_name           IN  VARCHAR2
);

Parâmetros

Parâmetro Descrição

Parâmetro	Descrição
`agent_name`	Nome do agente do AI a ser ativado. Este parâmetro é obrigatório.

agent_name

Nome do agente do AI a ser ativado.

Este parâmetro é obrigatório.

Exemplo para Ativar Perfil de IA

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

Procedimento DISABLE_AGENT

Este procedimento desativa o agente do AI no banco de dados atual. O status do agente do AI é alterado para DISABLED por este procedimento.

Sintaxe

DBMS_CLOUD_AI_AGENT.DISABLE_AGENT(
   agent_name           IN  VARCHAR2
);

Parâmetros

Parâmetro Descrição

Parâmetro	Descrição
`agent_name`	Nome do agente AI. Este parâmetro é obrigatório.

agent_name

Nome do agente AI.

Este parâmetro é obrigatório.

Exemplo

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

Procedimento DROP_AGENT

O procedimento elimina um agente AI existente. Se o agente não existir, o procedimento gerará um erro.

Sintaxe

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

Parâmetros

Parâmetro Descrição

Parâmetro	Descrição
`agent_name`	Nome do agente AI. Este é um parâmetro obrigatório.
`force`	Se `TRUE`, o procedimento ignorará erros se o agente AI não existir. O valor padrão para este parâmetro é `FALSE`.

agent_name

Nome do agente AI.

Este é um parâmetro obrigatório.

force

Se TRUE, o procedimento ignorará erros se o agente AI não existir.

O valor padrão para este parâmetro é FALSE.

Exemplo

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

Observações de Uso

Use force para eliminar um agente e ignorar erros se o agente do AI não existir.

Procedimento CREATE_TASK

Use o procedimento DBMS_CLOUD_AI_AGENT.CREATE_TASK para definir uma tarefa que um agente Selecionar AI pode incluir em seu processo de raciocínio. Cada tarefa tem um nome exclusivo e um conjunto de atributos que especificam o comportamento do agente ao planejar e executar a tarefa.

Você pode definir dependências entre tarefas usando o atributo input, permitindo que o Select AI transmita a saída de uma tarefa para outra. Isso suporta raciocínio encadeado e fluxos de trabalho de várias etapas.

Sintaxe

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

Parâmetro	Descrição
`task_name`	Um nome exclusivo para a tarefa. Este é um parâmetro obrigatório.
`attributes`	Objeto JSON contendo atributos específicos da tarefa. Consulte Atributos CREATE_TASK.
`status`	Status da tarefa. O valor-padrão é `ENABLED`.
`description`	Descrição definida pelo utilizador para ajudar a identificar a tarefa. Esse valor é armazenado no banco de dados, mas não é enviado ao LLM. O valor default é NULL.

Exemplo

O exemplo a seguir cria uma tarefa para processar uma devolução de produto de um 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

Esses atributos definem as instruções e as ferramentas do agente disponíveis para a tarefa.

Atributos

Nome do Atributo	Valor padrão	Descrição
`instruction`	-	Uma declaração clara e concisa que descreve o que a tarefa deve realizar. Este texto é incluído no prompt enviado ao LLM. Você pode incluir um espaço reservado `{query}` para representar a entrada da sua linguagem natural. Por exemplo: `SELECT AI AGENT <user_prompt>` Este é um parâmetro obrigatório.
`tools`	-	Um array JSON de nomes de ferramentas que o agente pode usar para concluir a tarefa. Por exemplo: `"tools": ["RAG", "SQL", "WEBSEARCH", "NOTIFICATION"]`. Este é um parâmetro obrigatório.
`input`	-	Identifica outras tarefas cujas saídas devem ser usadas como entrada para esta tarefa. Selecione AI para fornecer automaticamente essas saídas ao LLM.
`enable_human_tool`	-	Permite que o agente faça perguntas ao usuário quando ele exigir informações ou esclarecimentos durante uma tarefa. O valor padrão é verdadeiro. Observação: A tarefa `enable_human_tool` substitui o atributo `enable_human_tool` do agente. Se o agente `enable_human_tool` for definido como `false` e a tarefa `enable_human_tool` for definida como `true`, durante a execução da tarefa, o LLM deverá fazer perguntas.

Procedimento ENABLE_TASK

Use o procedimento DBMS_CLOUD_AI_AGENT.ENABLE_TASK para ativar uma tarefa definida anteriormente. Isso altera o status da tarefa para ENABLED, permitindo que o agente a use durante o processamento.

Sintaxe

DBMS_CLOUD_AI_AGENT.ENABLE_TASK(
   task_name           IN  VARCHAR2
);

Parâmetros

Parâmetro Descrição

Parâmetro	Descrição
`task_name`	Nome para a tarefa a ser ativada. Este parâmetro é obrigatório.

task_name

Nome para a tarefa a ser ativada.

Este parâmetro é obrigatório.

Observações sobre Uso

A tarefa já deve existir no sistema. Este procedimento atualiza o status da tarefa, tornando-o disponível para o processo do agente durante workflows de argumentos.

Exemplo de Ativação de uma Tarefa

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

Procedimento DISABLE_TASK

Use o procedimento DBMS_CLOUD_AI_AGENT.DISABLE_TASK para desativar uma tarefa no banco de dados atual. Isso altera o status da tarefa para DISABLED, impedindo que o agente o use durante o processamento.

Sintaxe

DBMS_CLOUD_AI_AGENT.DISABLE_TASK(
   task_name           IN  VARCHAR2
);

Parâmetros

Parâmetro Descrição

Parâmetro	Descrição
`task_name`	Nome da tarefa a ser desativada. Este parâmetro é obrigatório.

task_name

Nome da tarefa a ser desativada.

Este parâmetro é obrigatório.

Observações sobre Uso

A desativação de uma tarefa não a exclui; você pode reativá-la posteriormente usando DBMS_CLOUD_AI_AGENT.ENABLE_TASK. Depois de desativada, a tarefa se torna inativa e o agente não a considera mais durante a seleção da tarefa.

Exemplo

O exemplo a seguir desativa uma tarefa existente.

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

Procedimento DROP_TASK

Use o procedimento DBMS_CLOUD_AI_AGENT.DROP_TASK para remover uma tarefa definida anteriormente do banco de dados. Se a tarefa não existir, você poderá suprimir o erro definindo o parâmetro force como TRUE.

Sintaxe

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

Parâmetros

Parâmetro Descrição

Parâmetro	Descrição
`task_name`	Nome da tarefa a ser eliminada. Este é um parâmetro obrigatório.
`force`	Se `TRUE`, o procedimento ignorará erros se a tarefa não existir. O valor default para esse parâmetro é `FALSE`.

task_name

Nome da tarefa a ser eliminada.

Este é um parâmetro obrigatório.

force

Se TRUE, o procedimento ignorará erros se a tarefa não existir.

O valor default para esse parâmetro é FALSE.

Exemplo

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

Observações sobre Uso

Use force para eliminar uma tarefa e ignorar erros se a tarefa não existir.

Procedimento CREATE_TOOL

Use o procedimento DBMS_CLOUD_AI_AGENT.CREATE_TOOL para registrar uma ferramenta personalizada que um agente pode usar durante o processamento de tarefas. Cada ferramenta é identificada por um tool_name exclusivo e inclui atributos que definem sua finalidade, lógica de implementação e metadados.

As ferramentas podem ser funções ou procedimentos PL/SQL personalizados ou tipos de ferramentas incorporados, como RAG, SQL, WEBSEARCH ou NOTIFICATION.

Sintaxe

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

Parâmetro	Descrição
`tool_name`	Um nome exclusivo para identificar a ferramenta. Este é um parâmetro obrigatório.
`attributes`	Atributos de ferramenta no formato JSON. Consulte Atributos CREATE_TOOL. Este é um parâmetro obrigatório.
`status`	Status da ferramenta. O valor-padrão é `ENABLED`.
`description`	Descrição definida pelo utilizador para ajudar a identificar a ferramenta. Esse valor é armazenado no banco de dados, mas não é enviado ao LLM. O valor default é NULL.

Exemplo

O exemplo a seguir cria uma ferramenta para gerar um e-mail para o destinatário.

BEGIN
  DBMS_CLOUD_AI_AGENT.CREATE_TOOL(
    tool_name  => 'NOTIFICATION',
    attributes => '{"tool_type": "EMAIL"}'
  );
END;
/

Atributos CREATE_TOOL

Esses atributos fornecem configuração de ferramenta usando um objeto JSON no parâmetro de atributos. Cada atributo configura como o agente usa a ferramenta durante o raciocínio.

Atributos

Nome do Atributo	Valor padrão	Descrição
`instruction`	-	Uma declaração clara e concisa que descreve o que a ferramenta deve realizar e como fazê-lo. Este texto é incluído no prompt enviado ao LLM. Este é um parâmetro obrigatório.
`function`	-	Especifica a função ou o procedimento PL/SQL a ser chamado quando a ferramenta é usada. Este é um parâmetro obrigatório para ferramentas personalizadas.
`tool_type`	-	Especifica um tipo de ferramenta incorporado. Se definido, `instruction` e `function` não serão obrigatórios. Os valores possíveis são: `SQL` `RAG` `WEBSEARCH` `NOTIFICATION` Você pode criar ferramentas integradas com nomes e parâmetros personalizados. Você também pode criar várias ferramentas incorporadas com o mesmo `tool_type`, mas com `tool_params` diferente.
`tool_params`	-	Especifica parâmetros para registrar ferramentas incorporadas.
`tool_inputs`	-	Descreve os argumentos de entrada. Semelhante aos comentários da coluna em uma tabela. Por exemplo: `"tool_inputs": [ { "name": "data_guard", "description": "Only supported values are "Enabled" and "Disabled"" } ]`

Pré-requisitos para a Ferramenta Incorporada

Execute estas etapas antes de usar ferramentas incorporadas:

Ferramenta RAG

Crie um perfil de IA que faça referência a um índice vetorial. Consulte Aprimorar Prompts de Linguagem Natural Usando Geração Aumentada de Recuperação (RAG).

Ferramenta de NOTIFICAÇÃO

Os seguintes itens são suportados: SLACK e EMAIL.

Ferramenta SLACK:

Configure um aplicativo Slack para receber mensagens do Autonomous Database.
Crie uma credencial usando DBMS_CLOUD_NOTIFICATION para enviar notificações do Slack do Autonomous Database. Consulte Enviar Notificações do Slack do Autonomous AI Database.

Ferramenta E-MAIL:

Observação: A ferramenta de e-mail envia uma notificação por e-mail do OCI.

Identifique seu ponto final SMTP. Por exemplo, selecione um dos pontos finais 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

Conceda acesso SMTP usando uma ACL. Consulte Configurando a Conexão SMTP.
Gere credenciais SMTP para a entrega de e-mail. O pacote UTL_SMTP usa credenciais para autenticação com servidores de entrega de e-mail quando você envia um e-mail. Consulte Gerar Credenciais SMTP para um Usuário para obter mais informações.
Criar remetentes aprovados. Conclua esta etapa para todos os endereços de e-mail que você usa como endereço From com o subprograma UTL_SMTP.MAIL. Consulte Gerenciando Remetentes Aprovados para mais informações.
Conceda acesso SMTP ao usuário adicionando a Access Control Entry (ACE). Para obter mais detalhes, consulte Enviar E-mail no Autonomous AI Database.

Tipos de ferramentas incorporadas no pacote DBMS_CLOUD_AI_AGENT

Você pode registrar ferramentas incorporadas usando os atributos tool_type e tool_params.

Tipo de Ferramenta	Descrição	Parâmetros Obrigatórios
`SQL`	Traduz linguagem natural em consultas SQL.	`profile_name`
`RAG`	Executa Geração Aumentada de Recuperação por meio de pesquisa vetorial.	`profile_name`
`NOTIFICATION`	Envia mensagens para um canal do Slack ou envia e-mails usando SMTP. Opções disponíveis: `slack` `email`	`notification_type`. Quando `notification_type` é `slack`, `credential_name` e `channel` são obrigatórios. Quando `notification_type` for `email`, `credential_name`, `recipient`, `sender` e `smtp_host` serão obrigatórios.
`WEBSEARCH`	Pesquisa informações da web.	`credential_name`

Procedimento ENABLE_TOOL

Use o procedimento DBMS_CLOUD_AI_AGENT.ENABLE_TOOL para ativar uma ferramenta registrada anteriormente. Isso altera o status da ferramenta para ENABLED, permitindo que o agente use suas tarefas.

Sintaxe

DBMS_CLOUD_AI_AGENT.ENABLE_TOOL(
   tool_name           IN  VARCHAR2
);

Parâmetros

Parâmetro Descrição

Parâmetro	Descrição
`tool_name`	Nome da ferramenta a ser ativada. Este parâmetro é obrigatório.

tool_name

Nome da ferramenta a ser ativada.

Este parâmetro é obrigatório.

Exemplo

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

Procedimento DISABLE_TOOL

Use o procedimento DBMS_CLOUD_AI_AGENT.DISABLE_TOOL para desativar uma ferramenta registrada. Isso altera o status da ferramenta para DISABLED, impedindo que o agente o use em tarefas.

Sintaxe

DBMS_CLOUD_AI_AGENT.DISABLE_TOOL(
   tool_name           IN  VARCHAR2
);

Parâmetros

Parâmetro Descrição

Parâmetro	Descrição
`tool_name`	Nome da ferramenta a ser desativada. Este parâmetro é obrigatório.

tool_name

Nome da ferramenta a ser desativada.

Este parâmetro é obrigatório.

Exemplo

O exemplo a seguir desativa uma ferramenta existente.

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

Procedimento DROP_TOOL

Use o procedimento DBMS_CLOUD_AI_AGENT.DROP_TOOL para remover uma ferramenta registrada anteriormente com o agente. Se a tarefa não existir, você poderá suprimir o erro definindo o parâmetro force como TRUE.

Sintaxe

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

Parâmetros

Parâmetro Descrição

Parâmetro	Descrição
`tool_name`	Nome da ferramenta a ser eliminada. Este é um parâmetro obrigatório.
`force`	Se `TRUE`, o procedimento ignorará erros se a ferramenta não existir. O valor padrão para este parâmetro é `FALSE`.

tool_name

Nome da ferramenta a ser eliminada.

Este é um parâmetro obrigatório.

force

Se TRUE, o procedimento ignorará erros se a ferramenta não existir.

O valor padrão para este parâmetro é FALSE.

Exemplo

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

Observações sobre Uso

Use force para eliminar uma ferramenta e ignorar erros se a ferramenta não existir.

Procedimento CREATE_TEAM

Use o procedimento DBMS_CLOUD_AI_AGENT.CREATE_TEAM para definir uma equipe de agentes de IA que trabalham juntos para realizar tarefas. Você especifica agentes e suas tarefas associadas, além de como as tarefas devem ser processadas.

Sintaxe

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

Parâmetro	Descrição
`team_name`	Um nome exclusivo para identificar a equipe do agente de IA. Este é um parâmetro obrigatório.
`attributes`	String formatada em JSON que define atributos de equipe, como agentes e processo. Consulte Atributos CREATE_TEAM. Este é um parâmetro obrigatório.
`status`	Status da equipe. O valor-padrão é `ENABLED`.
`description`	Descrição definida pelo usuário para identificar a finalidade da equipe. Esse valor é armazenado no banco de dados, mas não é enviado ao LLM. O valor default é NULL.

Exemplo

O exemplo a seguir cria uma equipe de agente para processar a devolução do produto de um 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

Esses atributos fornecem a configuração da equipe do agente de IA. Cada equipe tem um team_name exclusivo e usa um conjunto de atributos para definir sua estrutura e estratégia de execução.

Atributos

Nome do Atributo Valor padrão Descrição

Nome do Atributo	Valor padrão	Descrição
`agents`	-	Especifica agentes de listagem de array JSON e suas tarefas correspondentes. Um agente pode ser atribuído a várias tarefas usando o mesmo nome. Este é um parâmetro obrigatório. Exemplo: `[ {"name": "", "task": ""} ]`
`process`	-	Especifica como as tarefas são executadas. Use `"sequential"` para que as tarefas sejam executadas uma após a outra em ordem.
`long_term_memory_length`	30	Especifica o número máximo de resumos no nível da tarefa anterior incluídos no prompt do sistema como contexto de memória no início de cada nova execução.

agents

Especifica agentes de listagem de array JSON e suas tarefas correspondentes. Um agente pode ser atribuído a várias tarefas usando o mesmo nome.

Este é um parâmetro obrigatório.

Exemplo:

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

process - Especifica como as tarefas são executadas. Use "sequential" para que as tarefas sejam executadas uma após a outra em ordem.

long_term_memory_length 30 Especifica o número máximo de resumos no nível da tarefa anterior incluídos no prompt do sistema como contexto de memória no início de cada nova execução.

Função SET_TEAM

Use DBMS_CLOUD_AI_AGENT.SET_TEAM para especificar a equipe do agente do AI para a sessão atual.

Depois que uma equipe é definida, somente a ação select ai agent é ativada, o sistema não suporta outras ações Selecionar IA.

Sintaxe

DBMS_CLOUD_AI_AGENT.SET_TEAM(
    team_name      IN  VARCHAR2,
);

Parâmetros

Parâmetro Descrição

Parâmetro	Descrição
`team_name`	Especifica o nome da equipe do Agente AI a ser usada na sessão atual. A equipe já deve existir no sistema. Este parâmetro é obrigatório.

team_name

Especifica o nome da equipe do Agente AI a ser usada na sessão atual. A equipe já deve existir no sistema.

Este parâmetro é obrigatório.

Exemplo

O exemplo a seguir define a equipe do agente de IA especificada pelo usuário na sessão atual.

EXEC DBMS_CLOUD_AI_AGENT.SET_TEAM('ReturnAgency');

Função GET_TEAM

Use DBMS_CLOUD_AI_AGENT.GET_TEAM para retornar a equipe do agente do AI para a sessão atual.

Sintaxe

DBMS_CLOUD_AI_AGENT.GET_TEAM RETURN VARCHAR2;

Exemplo

O exemplo a seguir retorna a equipe do agente de IA na sessão atual.

SELECT DBMS_CLOUD_AI_AGENT.GET_TEAM from DUAL;

Função CLEAR_TEAM

Use DBMS_CLOUD_AI_AGENT.CLEAR_TEAM para limpar o conjunto de equipes do agente AI na sessão atual. Este procedimento não elimina a equipe.

Sintaxe

DBMS_CLOUD_AI_AGENT.CLEAR_TEAM;

Exemplo

O exemplo a seguir limpa a equipe do agente AI na sessão atual.

BEGIN
  DBMS_CLOUD_AI_AGENT.CLEAR_TEAM;
END;
/

Função RUN_TEAM

Use DBMS_CLOUD_AI_AGENT.RUN_TEAM para iniciar uma nova equipe de agente do AI ou retomar uma pausa que esteja aguardando entrada humana. Se você fornecer um ID de processo existente e o processo de equipe associado estiver no estado WAITING_FOR_HUMAN, a função retomará o workflow usando a entrada fornecida como resposta humana.

Sintaxe

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

Parâmetros

Parâmetro Descrição

Parâmetro	Descrição
`team_name`	Especifica o nome da equipe do Agente AI a ser usada na sessão atual. A equipe já deve existir no sistema. Este parâmetro é obrigatório.
`user_prompt`	Especifica a consulta ou resposta do usuário fornecida à tarefa. Se a tarefa estiver no estado `RUNNING`, a entrada atuará como um espaço reservado para o `{query}` na instrução da tarefa. Se a tarefa estiver no estado `WAITING_FOR_HUMAN`, a entrada servirá como resposta humana.
`params`	Especifica os parâmetros personalizados usados durante o processo da equipe do agente de IA. Os parâmetros suportados incluem: `conversation_id`: Identifica a sessão de conversa associada à equipe do agente. Use esse parâmetro para integrações de aplicativos sem monitoramento de estado (por exemplo, o Oracle APEX AI Application Generator) para distinguir entre diferentes conexões de usuário. `variables`: Defina pares de chave/valor que forneçam entrada adicional para a equipe do agente. Essas variáveis ajudam a personalizar o comportamento da equipe durante o processo.

team_name

Especifica o nome da equipe do Agente AI a ser usada na sessão atual. A equipe já deve existir no sistema.

Este parâmetro é obrigatório.

user_prompt

Especifica a consulta ou resposta do usuário fornecida à tarefa.

Se a tarefa estiver no estado RUNNING, a entrada atuará como um espaço reservado para o {query} na instrução da tarefa.

Se a tarefa estiver no estado WAITING_FOR_HUMAN, a entrada servirá como resposta humana.

params

Especifica os parâmetros personalizados usados durante o processo da equipe do agente de IA. Os parâmetros suportados incluem:

conversation_id: Identifica a sessão de conversa associada à equipe do agente. Use esse parâmetro para integrações de aplicativos sem monitoramento de estado (por exemplo, o Oracle APEX AI Application Generator) para distinguir entre diferentes conexões de usuário.
variables: Defina pares de chave/valor que forneçam entrada adicional para a equipe do agente. Essas variáveis ajudam a personalizar o comportamento da equipe durante o processo.

Exemplo

O exemplo a seguir executa a equipe do agente de IA especificada pelo usuário na sessão atual.

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 || '"}'
);

Procedimento ENABLE_TEAM

Use o procedimento DBMS_CLOUD_AI_AGENT.ENABLE_TEAM para ativar uma equipe de agente de IA especificada pelo usuário. Isso altera o status da equipe para ENABLED.

Sintaxe

DBMS_CLOUD_AI_AGENT.ENABLE_TEAM(
   team_name           IN  VARCHAR2
);

Parâmetros

Parâmetro Descrição

Parâmetro	Descrição
`team_name`	Nome da equipe do agente de IA a ser ativada. Este parâmetro é obrigatório.

team_name

Nome da equipe do agente de IA a ser ativada.

Este parâmetro é obrigatório.

Exemplo

O exemplo a seguir ativa uma equipe de agente de IA especificada pelo usuário.

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

Procedimento DISABLE_TEAM

Use o procedimento DBMS_CLOUD_AI_AGENT.DISABLE_TEAM para desativar uma equipe de agente do AI existente. Isso altera o status da equipe para DISABLED.

Sintaxe

DBMS_CLOUD_AI_AGENT.DISABLE_TEAM(
   team_name           IN  VARCHAR2
);

Parâmetros

Parâmetro Descrição

Parâmetro	Descrição
`team_name`	Nome da equipe do agente de IA a ser desativada. Este parâmetro é obrigatório.

team_name

Nome da equipe do agente de IA a ser desativada.

Este parâmetro é obrigatório.

Exemplo

O exemplo a seguir desativa uma equipe de agente do AI existente.

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

Procedimento DROP_TEAM

Use o procedimento DBMS_CLOUD_AI_AGENT.DROP_TEAM para remover uma equipe de agente do AI criada anteriormente.

Sintaxe

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

Parâmetros

Parâmetro Descrição

Parâmetro	Descrição
`team_name`	Nome da equipe a ser eliminada. Este é um parâmetro obrigatório.
`force`	Se `TRUE`, o procedimento ignorará erros se a equipe não existir. O valor padrão para este parâmetro é `FALSE`.

team_name

Nome da equipe a ser eliminada.

Este é um parâmetro obrigatório.

force

Se TRUE, o procedimento ignorará erros se a equipe não existir.

O valor padrão para este parâmetro é FALSE.

Exemplo

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

Observações de Uso

Use force para eliminar uma equipe e ignorar erros se a equipe não existir.

Função DESCRIBE_TOOL

Use a função DBMS_CLOUD_AI_AGENT.DESCRIBE_TOOL para retornar metadados JSON para uma ferramenta. O resultado inclui o nome da ferramenta, a descrição, os atributos e as informações do esquema de entrada que um cliente compatível com MCP pode usar para a descoberta da ferramenta.

Sintaxe

DBMS_CLOUD_AI_AGENT.DESCRIBE_TOOL(
  tool_name IN VARCHAR2
) RETURN CLOB;

Parâmetros

Parâmetro	Descrição
`tool_name`	Nome da ferramenta Selecionar Agente AI cujos metadados são retornados.

Retorna

Retorna um CLOB que contém metadados de ferramenta e informações de argumento formatados em JSON.

Exemplo

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

Função RUN_TOOL

Use a função DBMS_CLOUD_AI_AGENT.RUN_TOOL para chamar uma ferramenta criada por nome. O parâmetro de entrada passa os argumentos da ferramenta como um payload JSON.

Sintaxe

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

Parâmetros

Parâmetro	Descrição
`tool_name`	Nome da ferramenta Selecionar Agente AI a ser chamada.
`input`	Payload de entrada JSON informado para a ferramenta.

Retorna

Retorna um CLOB que contém o resultado da execução da ferramenta.

Exemplo

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

Função LIST_TEAMS

Use a função DBMS_CLOUD_AI_AGENT.LIST_TEAMS para enumerar equipes de agentes disponíveis para o usuário que faz a chamada. O resultado pode ser usado por camadas de integração compatíveis com A2A para descoberta da equipe.

Sintaxe

DBMS_CLOUD_AI_AGENT.LIST_TEAMS
  RETURN CLOB;

Parâmetros

Parâmetro	Descrição
Nenhum(a)	Esta função não tem parâmetros.

Retorna

Retorna um CLOB que contém um array JSON. Cada entrada inclui o nome e a descrição da equipe.

Exemplo

SELECT DBMS_CLOUD_AI_AGENT.LIST_TEAMS()
FROM dual;

Função DESCRIBE_TEAM

Use a função DBMS_CLOUD_AI_AGENT.DESCRIBE_TEAM para retornar metadados de uma equipe de agentes. A função mapeia as ferramentas Selecionar Agente de IA disponíveis para a equipe na representação de habilidades compatíveis com A2A.

Sintaxe

DBMS_CLOUD_AI_AGENT.DESCRIBE_TEAM(
  team_name IN VARCHAR2
) RETURN CLOB;

Parâmetros

Parâmetro	Descrição
`team_name`	Nome da equipe do agente cujos metadados e recursos são retornados.

Retorna

Retorna um CLOB que contém um objeto JSON com o nome da equipe, a descrição, a versão opcional e a lista de habilidades.

Observações sobre Uso

Habilidades são uma representação de protocolo de ferramentas para clientes compatíveis com A2A. Eles não introduzem um novo tipo de objeto de banco de dados Selecionar Agente do AI.

Exemplo

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

Função GET_TEAM_STATE

Use a função DBMS_CLOUD_AI_AGENT.GET_TEAM_STATE para retornar o estado de execução mais recente de uma conversa da equipe do agente.

Sintaxe

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

Parâmetros

Parâmetro	Descrição
`team_name`	Nome da equipe do agente cujo estado de execução mais recente é retornado.
`params`	Objeto JSON opcional. Use `conversation_id` para recuperar o estado de execução mais recente de uma conversa específica. Se omitido, a conversa da sessão atual é usada.

Retorna

Retorna um estado de execução do VARCHAR2, como RUNNING, WAITING_FOR_HUMAN, SUCCEEDED ou FAILED.

Exemplo

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

Procedimento SET_EXECUTION_STATE

Use o procedimento DBMS_CLOUD_AI_AGENT.SET_EXECUTION_STATE para atualizar uma execução de equipe de espera para um estado especificado. Isso é útil para workflows de chamada de ferramenta direta do agente em que o aplicativo controla quando a sessão interativa é concluída.

Sintaxe

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

Parâmetros

Parâmetro	Descrição
`team_name`	Nome da equipe do agente cujo estado de execução é atualizado.
`state`	Estado de execução a ser definido. O valor-padrão é `SUCCEEDED`.
`params`	Objeto JSON opcional. Use `conversation_id` para identificar a conversa cujo estado de execução é atualizado.

Exemplo

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