AI Agents

Padrões de Sistemas e Supervisor de Vários Agentes

Um sistema multiagente é um design de aplicativo de IA no qual uma solicitação de usuário é tratada por vários agentes cooperantes, em vez de um agente grande e multifuncional.

Cada agente tem sua própria função, instruções, configuração do modelo, política de memória e ferramentas permitidas. O fluxo define como a solicitação se move entre esses agentes e como a resposta final é produzida.

Esse design é útil quando um fluxo de trabalho se separa naturalmente em responsabilidades especializadas. Por exemplo, um agente pode recuperar dados, outro pode chamar uma API, outro pode resumir descobertas e um supervisor pode decidir qual especialista usar e combinar os resultados em uma única resposta.

Observação:

Como princípio de design, é melhor começar com o menor design de agente que atenda aos requisitos. Adicione vários agentes quando a separação de preocupações melhorar a confiabilidade, a segurança, a capacidade de manutenção ou a observabilidade mais do que aumenta o custo e a complexidade.

Benefícios dos sistemas multiagentes

Os sistemas multiagentes são mais adequados para:

Especialização: dê a cada agente um trabalho focado, um prompt e um conjunto de ferramentas em vez de um bloco de instruções lotado.
Roteamento e decomposição: permita que um supervisor interprete a solicitação, a divida em subtarefas e escolha o especialista certo para cada subtarefa.
isolamento de ferramentas e dados: exponha ferramentas confidenciais ou de alto impacto apenas aos agentes responsáveis por usá-las.
Governança e solução de problemas: facilitam a inspeção de transferências, propriedade da ferramenta, configurações de memória e pontos de falha.

Quando Escolher Designs de Vários Agentes ou Agentes Únicos

Um único agente com mais ferramentas geralmente é o primeiro projeto certo. É mais simples de testar, mais barato de executar e mais fácil de raciocinar quando a tarefa tem um objetivo claro e um modelo de permissão. Use um design de vários agentes quando o fluxo de trabalho se beneficiar de funções explícitas, acesso limitado a ferramentas ou um supervisor que possa coordenar várias saídas de especialistas.

Pergunta de Design	Usar agentes únicos quando...	Usar vários agentes quando...
Forma da tarefa	O pedido tem um objetivo principal e um stile de resposta.	A solicitação deve ser decomposta, encaminhada, verificada ou sintetizada entre as especialidades.
Ferramentas e dados	O mesmo conjunto de instruções e modelo de permissão podem governar com segurança todas as ferramentas	Agentes diferentes precisam de ferramentas, origens de dados ou limites de acesso diferentes.
Instruções	O prompt permanece claro mesmo com todas as regras de negócios e orientação de ferramentas em um só lugar.	As instruções são mais fáceis de manter como prompts menores e específicos da função.
Custo e latência	Você deseja o caminho mais curto da mensagem do usuário para a resposta.	Os benefícios de confiabilidade, governança ou capacidade de manutenção justificam uma orquestração extra.
Diagnosticando e Solucionando Problemas	Falhas são simples de depurar em um único rastreamento.	Você precisa de transferências explícitas, isolamento de estado e propriedade mais clara para cada etapa.

Padrão Suportado: Orchestrator/Supervisor

A experiência atual da tela suporta o padrão do orquestrador/supervisor. Nesse padrão, o Trigger de Chat recebe a mensagem do usuário, os Guardrails opcionais avaliam a entrada e um Agente Supervisor age como o orquestrador para o restante do fluxo.

O supervisor deve se concentrar no planejamento, na rota, na delegação e na síntese da resposta final. Ele decide qual agente executor deve lidar com uma tarefa, envia a esse executor uma instrução com escopo, revisa o resultado e, em seguida, delega outra etapa ou retorna a resposta final. Os agentes executores devem ser especialistas mais restritos: eles fazem o trabalho atribuído, usam suas ferramentas anexadas e retornam resultados úteis ao supervisor.

Sobre o Visual Flow Canvas

Um agente é montado arrastando nós e modelos de ferramenta da paleta esquerda para a tela e, em seguida, conectando os nós na ordem em que a solicitação deve se deslocar.

A seleção de um nó abre um painel de configuração na parte inferior da tela.

Tela do criador visual do agente. A paleta, o seletor de modo e o controle de zoom são rotulados e realçados.

Elemento da Tela	Objetivo
Trigger de Bate-papo	Ponto de entrada para uma mensagem do usuário. Na captura de tela, esse nó é rotulado como Mensagem e normalmente fica na parte superior do fluxo. Um nó de trigger de chat pode ser conectado a um agente, um agente supervisor ou um nó de guardrails. Apenas um trigger de chat é permitido por tela.
Guardrails de proteção	Camada opcional de política e segurança colocada antes ou depois do trabalho do modelo. As políticas de guardrails incluem PII, moderação de conteúdo e detecção de injeção imediata. Um nó de guardrails pode filtrar o tráfego entre um acionador de chat e um nó de agente, entre um supervisor e agentes executores ou entre nós de agente e ferramenta. Recomendamos um único nó de guardrails entre o trigger de chat e o nó do agente.
Agente Supervisor	O orquestrador. Ele recebe a solicitação do usuário, decide qual agente executor ou ferramenta deve lidar com cada tarefa e coordena a resposta final. Apenas um agente supervisor é permitido em uma tela.
Agente	Um agente executor. Cada executor deve ter uma especialidade clara, como recuperação de dados, pesquisa de API, resumo ou resposta a perguntas de documentos. Use um agente/executor para um único sistema de agente.
Modelos de ferramentas	Recursos reutilizáveis que podem ser anexados a um executor individual ou agente supervisor. Os modelos de ferramentas incluem SQL, RAG, Prompt, HTTP, servidor MCP remoto e Ferramenta personalizada.
Desenvolvimento / Playground	Seletor de modo acima da tela. O desenvolvimento é usado durante a edição do sistema agentic; o Playground é usado para iniciar sessões de teste e inspecionar o comportamento do agente. O playground requer que uma computação de IA seja anexada ao seu agente.
Controle de zoom	Seletor de zoom da tela. As capturas de tela mostram níveis de zoom de 60% e 90%.

Criar um Agente

Você pode criar um agente em um espaço de trabalho em que tenha a permissão Gerenciar.

Na Home page, navegue até seu espaço de trabalho.
Clique em Fluxos do Agente no painel de navegação esquerdo.
Clique em Criar Agente ou clique em Criar no canto superior direito.
Forneça um nome e descrição para o agente.
Para Modo de criação de fluxo do agente, selecione Visual builder.
Opcional: No menu drop-down Computação AI, selecione uma computação a ser usada para o agente.
Clique em Criar. Comece a criar seu agente arrastando um nó da paleta para a tela.

Observação:
Inicie o seu primeiro build de agente simples: um Trigger de Chat, um Agente de executor. Adicione complexidade após uma execução bem-sucedida da sua primeira compilação, como trilhos de proteção, ferramentas adicionais ou até mesmo design de sistema de vários agentes.

Adicionar Trigger de Chat e Agente à Tela do Visual Builder

Sua primeira etapa após a criação de um agente com o Visual Builder deve ser adicionar um acionador de chat e um agente supervisor.

O acionador recebe a mensagem do usuário. O supervisor interpreta a solicitação, planeja o trabalho e delega a agentes executores ou ferramentas. Você pode arrastar nós na tela, configurá-los e conectá-los posteriormente.

Navegue até o agente em seu espaço de trabalho.
Clique e arraste um Trigger de Bate-papo da paleta para a tela. O nó aparece na tela como uma Mensagem.
Clique e arraste um Agente do Supervisor para a tela.
Clique e arraste o identificador do conector no nó Acionador de Chat para conectá-lo ao nó do Agente.

O crachá Supervisor Agent exibe quantos agentes e ferramentas estão conectados. Em uma nova compilação, o Supervisor Agent mostra: Agents (0) Tools (0).

Trigger de chat e agente supervisor na tela do Visual Builder. O crachá abaixo do agente supervisor indica "Agentes (0) Ferramentas (0)".

Configurar um Agente Supervisor

Você precisa configurar um agente de supervisor adicionado à tela do Visual Builder com instruções que descrevem a função de supervisor.

Você configura um agente supervisor com os seguintes campos.

A tela do Visual Builder é exibida. O agente supervisor seleciona e exibe a guia Configuração.

Campo	Configuração
Nome do Agente	Forneça um nome descritivo para o agente do supervisor. Um nome bom e descritivo será benéfico ao depurar o comportamento do sistema por meio de rastreamentos e logs.
Descrição do Agente	Forneça uma descrição da finalidade, da função e do comportamento geral do agente. Útil para fins de documentação.
Região	Escolha a região na qual o modelo do OCI Generative AI usado pelo Supervisor Agent está hospedado. Consulte Modelos de IA Generativa por Região.
Modelo	Escolha o modelo de serviço OCI Generative AI usado pelo supervisor. A lista drop-down lista os modelos disponíveis na região selecionada.
Instruções do agente	Descreva a função de supervisor, as regras de roteamento, a política de delegação, as expectativas de uso da ferramenta e o formato de resposta final.

Navegue até o agente em seu espaço de trabalho.
Clique no nó Agente do Supervisor na sua tela.
Forneça um nome e uma descrição minuciosos para o seu agente supervisor.
Digite a região e o modelo do modelo de serviço do OCI Generative AI usado pelo supervisor.
Forneça as instruções do agente para seu Agente Supervisor.

Instruções de Supervisor Sugeridas

Você deve usar o campo Instruções para um Agente Supervisor para tornar o supervisor responsável pela orquestração, não por executar cada tarefa em si.

Mantenha as instruções concretas para que as decisões de roteamento sejam previsíveis. Consulte o seguinte para obter um exemplo de um conjunto de instruções do Supervisor:

You are the supervisor for a multi-agent system.

Responsibilities:
- Understand the user's request and break it into subtasks.
- Select the most appropriate executor agent or tool for each subtask.
- Do not perform specialist work yourself when an executor agent is available.
- Ask for clarification only when required information is missing.
- Combine executor outputs into a concise final answer.
- Mention important assumptions, limits, or failed tool calls in the final answer.

Routing rules:
- Use the SQL agent for structured data questions.
- Use the HTTP agent/tool for external API lookups.
- Use the RAG agent/tool for document or knowledge-base questions.
- Use the prompt tool for reusable prompt-only transformations.

Configurar Memória do Agente Supervisor e Isolamento de Estado

A guia Memória de um Agente Supervisor controla a quantidade de histórico de conversação e saída de ferramentas disponível para o supervisor e quanto contexto é compartilhado com agentes executores.

Você configura o estado de memória e isolamento para o Agente Supervisor com os campos a seguir.

A tela do Visual Builder é exibida. Um agente supervisor é selecionado e a guia Memória é exibida.

Campo	Configuração
Ativar Memória do Agente	Ative quando os usuários precisarem de continuidade de várias voltas. Desativar para tarefas isoladas de uso único. Este campo não pode ser desativado para Agentes do Supervisor.
Limitar histórico de conversas	Ative para truncar a janela de contexto do LLM após o limite especificado ser atingido. Desativar para mostrar o histórico completo.
Configuração de truncamento	Se a opção Limitar histórico de conversas estiver ativada, use esse campo para definir as condições para truncar a janela de contexto. As opções são: Manter N últimas mensagens Orçamento de token Ambos
Limites Máximos de Mensagens e Orçamento de Token	Uma ou ambas as opções são exibidas, dependendo da sua escolha para Configuração de Execução. Os valores padrão são 20 mensagens e 5000 tokens. Recomendamos começar com valores moderados e ajustar conforme necessário.
Isolamento de Estado para Agentes Executores	Selecione Sem Monitoramento de Estado, Privado ou Compartilhado. Sem Monitoramento de Estado: Cada agente executor vê apenas a tarefa atribuída pelo supervisor. Não há história entre as chamadas. Selecione esta opção se desejar o contexto de isolamento mais forte e menos de agente cruzado. Privado: Cada agente executor vê apenas suas próprias interações passadas. Não é possível ver outros agentes executores da conversa de usuário original. Selecione esta opção se o seu executor precisar de continuidade em suas próprias tarefas, mas não deve compartilhar o contexto com outros agentes. Compartilhado: Os agentes do executor podem ver o histórico completo de conversas entre agentes e usuários. Todos os agentes trabalham em um contexto compartilhado. Selecione esta opção se precisar de um amplo compartilhamento de contexto e tiver revisado os riscos de privacidade e de injeção imediata.

Navegue até o agente em seu espaço de trabalho.
Clique no nó Agente do Supervisor na sua tela.
Clique na guia Memória.
Escolha se deseja ativar Limitar histórico de conversas. Selecione uma Configuração de Execução e defina limites, se ativado.
Escolha uma opção para Isolamento de Estado para Agentes do Executor.

Guia Parâmetro de Modelos

A guia Parâmetros do modelo permite configurar parâmetros específicos do modelo que estão disponíveis para o modelo selecionado.

Os parâmetros do modelo podem ser configurados separadamente para agentes de supervisor e executor. Os parâmetros que você pode usar incluem temperatura, K superior, P superior e penalidade de frequência.

Observação:

Somente um subconjunto de modelos expõe parâmetros configuráveis. Além disso, os parâmetros variam entre as famílias de modelos.

A tela do Visual Builder é exibida. Um agente supervisor é selecionado e a guia de parâmetros do modelo é exibida.

Adicionar Guardrails a um Agente

Você pode adicionar camadas adicionais de proteção aos seus agentes adicionando um ou mais nós de corrimão à sua tela.

Por padrão, nenhum corrimão é aplicado aos seus sistemas agênticos além do que o provedor de modelo selecionado está oferecendo pronto para uso para seus modelos. Os corrimãos podem ser colocados entre o Trigger de Chat e o Agente do Supervisor para que as políticas sejam aplicadas antes que uma solicitação chegue ao agente do supervisor e antes que o agente do supervisor retorne uma resposta ao chamador.

Corrimão	Options	Quando usar
Informações Pessoais Identificáveis (PII)	Guias Entrada e Saída Caixas de Seleção para Pessoa, Endereço, Número de Telefone, E-mail	Use quando o fluxo deve bloquear ou mascarar dados pessoais confidenciais antes ou depois do processamento do modelo.
Prevenção de moderação de conteúdo	Linhas de entrada e saída com as opções Bloquear, Informar e Permitir.	Use para definir como o fluxo lida com conteúdo de ódio, sexual, violento, tóxico, depreciativo ou assediante.
Detecção de Injeção de Prompt	Linha de entrada com as opções Bloquear e Permitir.	Use para reduzir a chance de que instruções maliciosas substituam as instruções do sistema ou do agente.

Para obter mais informações sobre configurações de guardrail, consulte Guardrails.

Navegue até o agente em seu espaço de trabalho.
Arraste um nó Guardrails da paleta para a tela. Coloque-o entre o nó do Trigger de Chat e o nó do Agente do Supervisor.
Exclua a conexão entre o Trigger de Chat e o Agente Supervisor passando o mouse sobre a conexão e clicando no X vermelho.
Clique e arraste a alça do conector no Trigger do Chat para o nó Guardrail. Em seguida, clique e arraste a alça do conector do nó Guardrail para o Agente do Supervisor.
Clique no nó Guardrail para abrir a página Configuração.
Configure os guardrails para selecionar a ação desejada para verificações de entrada e saída.

Adicionar Agentes e Ferramentas do Executor a um Agente

Você pode adicionar agentes executores a ferramentas para executar trabalhos especializados para o agente supervisor.

No exemplo abaixo, o Agente Supervisor delega a AGENT_1 e AGENT_2. AGENT_1 está conectado às ferramentas SQL_1 e HTTP_1.

A tela do Visual Builder é exibida. Um nó de trigger de chat está conectado a um nó de guardrail, que está conectado a um nó de supervisor. O nó do supervisor é conectado a dois nós de agente, AGENT_1 e AGENT_2. AGENT_1 está conectado a dois nós de ferramentas, SQL_1 e HTTP_1.

Navegue até o agente em seu espaço de trabalho.
Arraste um nó do Agente da paleta para a tela. Os nós do agente devem ser colocados abaixo de um Agente Supervior.
Arraste Ferramentas da paleta para a tela.
Clique e arraste a alça do conector no Agente do Supervisor para estabelecer conexão com os nós do Agente.
Clique e arraste a alça do conector em seus Agentes para se conectar aos nós da Ferramenta.

Configuração do Agente do Executor

Os nós do agente podem ser configurados modificando as definições nas guias Configuração, Memória e Modelo para ajudá-lo a definir a finalidade de cada agente.

Os agentes devem ser configurados de forma restrita, dada uma função e uma meta específicas, para que o agente supervisor possa rotear o trabalho de forma confiável.
Tela de construção visual. Um nó de acionador de chat é conectado a um agente supervisor, que é conectado a dois nós de agente, AGENT_1 e AGENT_2. AGENT_1 está conectado a dois nós de ferramentas, SQL_1 e HTTP_1.

Tabela 22-1 Guia Configuração do Agente

Campo	Configuração
Nome do Agente	A melhor prática é nomear cada agente executor de acordo com sua especialidade, como SQL_AGENT, DOCUMENT_AGENT, API_AGENT ou SUMMARY_AGENT. Como o nome de cada agente executor fica visível para o agente supervisor, use nomes descritivos.
Descrição do Agente	Forneça uma descrição detalhada de cada agente executor. A descrição de cada agente executor fica visível para o agente supervisor.
Região	Escolha a região na qual o modelo do OCI Generative AI usado pelo Agente está hospedado. Consulte Modelos de IA Generativa por Região.
Modelo	Escolha o modelo de serviço do OCI Generative AI usado pelo agente. O menu drop-down lista os modelos disponíveis na região selecionada. Selecione um modelo que se ajuste à tarefa do executor. Os agentes executores não precisam usar o mesmo modelo que o agente supervisor.
Instruções do agente	Descreva exatamente o que o executor deve fazer, quais ferramentas ele pode usar e qual estrutura de saída ele deve retornar.

Guia Memória do Agente Executor

No caso de agentes executores conectados a um agente supervisor, a memória para executores é configurada no nó supervisor e aplicada a todos os agentes executores.

Campo	Configuração
Ativar Memória do Agente	Ative quando os usuários precisarem de continuidade de várias voltas. Desativar para tarefas isoladas de uso único.
Limitar histórico de conversas	Ative para truncar a janela de contexto do LLM após o limite especificado ser atingido. Desativar para mostrar o histórico completo.
Configuração de truncamento	Se a opção Limitar histórico de conversas estiver ativada, use esse campo para definir as condições para truncar a janela de contexto. As opções são: Manter N últimas mensagens Orçamento de token Ambos
Limites Máximos de Mensagens e Orçamento de Token	Uma ou ambas as opções são exibidas, dependendo da sua escolha para Configuração de Execução. Os valores padrão são 20 mensagens e 5000 tokens. Recomendamos começar com valores moderados e ajustar conforme necessário.
Isolamento de Estado para Agentes Executores	Selecione Sem Monitoramento de Estado, Privado ou Compartilhado. Sem Monitoramento de Estado: Cada agente executor vê apenas a tarefa atribuída pelo supervisor. Não há história entre as chamadas. Selecione esta opção se desejar o contexto de isolamento mais forte e menos de agente cruzado. Privado: Cada agente executor vê apenas suas próprias interações passadas. Não é possível ver outros agentes executores da conversa de usuário original. Selecione esta opção se o seu executor precisar de continuidade em suas próprias tarefas, mas não deve compartilhar o contexto com outros agentes. Compartilhado: Os agentes do executor podem ver o histórico completo de conversas entre agentes e usuários. Todos os agentes trabalham em um contexto compartilhado. Selecione esta opção se precisar de um amplo compartilhamento de contexto e tiver revisado os riscos de privacidade e de injeção imediata.

Guia Parâmetros do Modelo do Agente Executor

A guia Parâmetros do modelo permite configurar parâmetros específicos do modelo que estão disponíveis para o modelo selecionado.

Observação:

Somente um subconjunto de modelos expõe parâmetros configuráveis. Os parâmetros também variam entre as famílias de modelos.

Exemplos de parâmetros incluem temperatura, K superior, P superior e penalidade de frequência. Os parâmetros do modelo podem ser configurados separadamente para agentes de supervisor e executor.

Instruções do Executor Sugeridas

You are the SQL executor agent.

Responsibilities:
- Translate the supervisor's task into safe SQL tool usage.
- Use only the SQL tools attached to this agent.
- Return a concise answer plus any important query assumptions.
- Do not invent data. If the tool cannot answer, say what is missing.
- Return structured output with: answer, evidence, assumptions, and follow_up_needed.

Lista de Verificação para Agentes por meio do Visual Builder

Use essa lista como guia para garantir que você tenha incluído e configurado todos os componentes necessários para um agente criado usando o Visual Builder.

Criar Lista de Verificação

O agente tem exatamente um ponto de entrada esperado: Disparador de Chat / Mensagem.
Os corrimãos são conectados na posição pretendida e ativados quando necessário. Recomendamos a inserção de guardrails entre a mensagem do trigger e o agente.
O Agente do Supervisor tem uma região selecionada, um modelo selecionado e instruções de orquestração. O mesmo para os agentes executores.
Configure a memória do sistema de vários agentes na guia Memória do agente Supervisor. Selecione o isolamento do estado do executor que corresponda aos requisitos de privacidade e continuidade.
Cada Agente executor tem uma especialidade clara e instruções restritas.
Cada ferramenta é anexada somente ao agente que deve usá-la.
Nenhum nó está desconectado.
Uma computação de IA é anexada ao sistema agentic para testar ferramentas individuais e para executar a experiência do Playground.

Tabela 22-2 Problemas Comuns

Problema	Provável Causa	Ação Sugerida
O supervisor não chama um executor	As instruções do supervisor são muito vagas ou nenhum executor está conectado.	Adicione regras de roteamento explícitas e confirme se o nó do executor está conectado ao supervisor.
Executor retorna respostas amplas ou fora do tópico	As instruções do executor são muito gerais.	Torne a função de executor mais restrita e defina a estrutura de saída necessária.
A ferramenta não foi usada	A ferramenta está desconectada ou anexada ao agente errado.	Verifique a conexão da ferramenta e o crachá de contagem de ferramentas do agente.
Guardrail não atira	A seção Guardrail está configurada, mas não ativada.	Abra o nó guadrails e confirme se a alternância da seção está ativada.
Vazamentos de contexto entre agentes	O isolamento do estado é definido como Compartilhado ou a memória é mais ampla do que o pretendido.	Use isolamento Stateless ou Privado para uma separação mais rigorosa.
Perguntas de acompanhamento perdem contexto	A memória está desativada ou o truncamento é muito agressivo.	Ative a memória e ajuste o limite máximo de mensagens.

Fluxo do Agente Através do Código

Você pode trazer sua própria base de código LangGraph para agentes de IA no Oracle AI Data Platform Workbench ou criar um novo agente LangGraph diretamente na plataforma por meio da experiência de codificação do agente.

Você pode usar a biblioteca Python do utilitário AI Data Platform Workbench aidputils para configurar seu modelo básico e importar ferramentas do sistema para seu agente. Para obter referência da API aidputils, consulte API do Aidp-utils para o Oracle AI Data Platform Workbench.

Agent SkillsTest aberto na guia Desenvolvimento.

Você cria um agente por meio do código fazendo upload de um arquivo de código existente ou criando arquivos de código diretamente no seu agente por meio do editor em linha.

O editor de código em linha nos agentes suporta os seguintes tipos de arquivo de código:

Python (.py)
JSON
TXT
CSV
PSV
SH
Pasta

Você pode ver e navegar pelos arquivos de código disponíveis clicando na lista drop-down do seletor de arquivos.

Página do agente com a lista drop-down do seletor de arquivos aberta e destacada

Arquivos de Entrada e Dependência

Arquivos de entrada são arquivos de código que têm a classe com métodos de configuração e chamada esperados para um agente definido como código. O Oracle AI Data Platform Workbench requer que você defina um arquivo de entrada para agentes por meio de código.

Arquivos de dependência são arquivos que incluem bibliotecas de terceiros exigidas pelo seu agente definidas como código. Os arquivos de dependência geralmente são arquivos requirements.txt que contêm uma lista das bibliotecas de terceiros necessárias.

Observação:

As bibliotecas de terceiros são instaladas quando você testa seu código no editor clicando no botão Reproduzir ou quando você testa o agente na guia Testar. Recomendamos a instalação de bibliotecas de terceiros testando o código primeiro. Erros durante a instalação das bibliotecas são exibidos na célula de saída.

Classe do Agente

AgentBasic é uma classe de modelo para configurar e chamar um agente de conversação simples usando um workflow LangGraph com monitoramento de estado. Ele demonstra a estrutura necessária para o desenvolvimento mínimo de agentes com dois métodos principais:

setup(): Inicializa o workflow do agente e define o gráfico.
invoke(user_query, **kwargs): Executa o agente em uma mensagem do usuário e retorna a resposta.

Ele pode ser executado e testado diretamente usando uma função main() antes da integração em um sistema maior.

Definição

class AgentBasic:
    def __init__(self) -> None:
        self.graph = None
    def setup(self) -> None:
        self.graph = StateGraph(MessagesState)
        self.graph.add_node(mock_llm)
        self.graph.add_edge(START, "mock_llm")
        self.graph.add_edge("mock_llm", END)
        self.graph = self.graph.compile()
        system_prompt = "Be a helpful assistant."
    async def invoke(self, user_query: str, **kwargs):
        user_message = HumanMessage(content=user_query)
        messages = {"messages": [dict(user_message)]}
        try:
            return self.graph.invoke(messages)
        except Exception as e:
            import traceback
            logger.error(f"Exception while calling invoke {e}", exc_info=True)
            print("Stack trace:\n", traceback.format_exc())

Testar chamada

Esta chamada de teste é ideal para testes funcionais iniciais.

Observação:

Inclua um ponto de entrada principal para testes independentes.

import asyncio

async def main():
test_agent = AgentBasic()
test_agent.setup()
result = await test_agent.invoke("Hi there")
print("Agent response:", result)
if __name__ == "__main__":
   asyncio.run(main())

Como funciona:

O script cria um agente, o configura e envia uma mensagem de usuário de amostra.
O agente responde ({"messages": [{"role": "ai", "content": "hello world"}]} neste exemplo.

Guia de Uso

Crie uma classe Agente com os métodos de configuração e chamada.

configuração()	Inicializa o workflow do agente	agent.setup()
chamar()	Executa o agente com uma mensagem do usuário	await agent.invoke("Sua pergunta")

Assíncrono: invoke() é um método assíncrono; use-o com await ou execute em um loop assíncrono.
Testando: O guarda main() incluído (if __name__ == "__main__":) facilita o teste do agente antes da implantação.

Criar um Agente Através do Código por Upload

Você pode criar seu aplicativo de agente de ponta a ponta com código existente fazendo upload da sua base de código LangGraph.

O Oracle AI Data Platform Workbench suporta o LangGraph versão 1.0.1.

Observação:

Você pode fazer upload de arquivos e pastas individuais até um máximo de 500 arquivos, cada arquivo pode ter um tamanho máximo de 500 MB. O upload é limitado a um tamanho total de 5 GB.

Navegue até o agente em seu espaço de trabalho. Clique no nome do agente.
Clique em Fazer Upload.
Arraste e solte um arquivo no painel ou clique para procurar para selecionar um arquivo.
Clique em Fazer Upload.

Criar um Agente Através do Código Criando um Novo Código

Você pode criar seu aplicativo de agente de ponta a ponta com o código existente criando o código diretamente no seu agente por meio do editor de código.

O editor de código suporta os seguintes tipos de arquivo:

Python (.py)
JSON
TXT
CSV
PSV
SH
Pastas

Navegue até o agente em seu espaço de trabalho. Clique no nome do agente.
Clique em Adicionar novo arquivo.
Informe um nome para o seu arquivo de código.
Selecione um tipo de arquivo na lista drop-down.
Clique em Criar.

Definir um Arquivo de Entrada para Agentes por meio de Código

Seu agente de IA por meio do código requer um arquivo de entrada que tenha a classe necessária, a configuração e os métodos de chamada esperados para seu agente.

Navegue até o agente em seu espaço de trabalho. Clique no nome do agente.
Na guia Code Editor, localize o arquivo de entrada no painel de navegação esquerdo. Se o arquivo não existir, você poderá fazer upload dele clicando em Fazer Upload ou criá-lo clicando em Adicionar novo arquivo.
Clique com o botão direito do mouse no arquivo de entrada e clique em Definir arquivo de entrada. Você também pode selecionar o arquivo e clicar no botão Definir arquivo de entrada no canto superior direito do editor de código.

Definir um Arquivo de Dependência para Agentes por meio de Código

É necessário definir um arquivo de dependência para que os agentes fluam pelo código que contém qualquer biblioteca de terceiros da qual seu código depende.

Navegue até o agente em seu espaço de trabalho. Clique no nome do agente.
Na guia Code Editor, localize o arquivo de dependência no painel de navegação esquerdo, geralmente requirements.txt. Se o arquivo não existir, você poderá fazer upload dele clicando em Fazer Upload ou criá-lo clicando em Adicionar novo arquivo.
Clique com o botão direito do mouse no arquivo de dependência e clique em Definir dependência. Você também pode selecionar o arquivo e clicar no botão Definir arquivo de dependências no canto superior direito do editor de código.

Código do Agente de Teste

Você pode testar o código usado para seu agente na guia Testar para validar e depurar o código.

Você deve ter uma computação de IA anexada ao seu agente para testar.

Navegue até o agente em seu espaço de trabalho. Clique no nome do agente.
Clique na guia Playground.
Clique em Reproduzir para testar o arquivo de código selecionado.

Uma célula de saída na metade inferior da janela do editor de código exibe as saídas de instruções de impressão ou registro em log no código. Os erros também são exibidos na célula de saída.

Habilidades do agente na experiência de codificação

As Habilidades do Agente permitem que um agente descubra e use instruções específicas da tarefa, arquivos de referência, modelos, ativos e scripts executáveis opcionais sem codificar esse conhecimento de domínio nas instruções do agente.

Uma habilidade é armazenada como uma pasta na sua base de código do agente. Cada habilidade tem um arquivo SKILL.md necessário que descreve o que a habilidade faz e como o agente deve usá-lo. Uma habilidade também pode incluir arquivos de suporte, como esquemas, exemplos, prompts, modelos, ativos ou scripts.

Para obter mais informações, consulte Visão Geral das Habilidades do Agente.

As habilidades do agente suportam um modelo de divulgação progressiva:

O agente descobre que existe uma habilidade.
O agente só ativa a habilidade quando ela é relevante.
O agente carrega arquivos adicionais da pasta de habilidades somente quando necessário.
O agente poderá executar um ponto de entrada de habilidade explicitamente declarado, se a habilidade permitir.

Quando usar Habilidades do Agente

Você deve usar Habilidades quando quiser empacotar recursos de agente reutilizáveis, como:

Instruções específicas do domínio
Fluxos de trabalho de codificação ou análise de dados
Orientação para geração de SQL
Manuais do processo de negócios
Modelos de arquivo
Referências do esquema
Scripts reutilizáveis para cálculos, transformações ou pesquisas seguras

As habilidades são úteis quando o agente deve ter acesso a conhecimentos especializados e reutilizáveis, mas você não deseja colocar todo esse conhecimento diretamente no prompt do agente.

Como as habilidades funcionam em tempo de execução

No runtime, o aplicativo host determina quais diretórios de habilidades estão disponíveis, como pastas de habilidades no nível do projeto e no nível do usuário. A plataforma carrega os metadados de cada habilidade de SKILL.md e cria um catálogo com chave por nome de habilidade.

Em seguida, o agente pode usar ferramentas relacionadas a habilidades:

Ferramenta	Objetivo
`activate_skill(name)`	Carrega as instruções de habilidade de SKILL.md.
`list_skill_files(name, path)`	Lista os arquivos disponíveis em uma pasta de habilidades.
`load_skill_file(name, path)`	Carrega um arquivo de suporte da pasta de habilidades.
`run_skill_entrypoint(name, entrypoint, args_json, timeout_seconds)`	Executa um ponto de entrada Python declarado explicitamente, se permitido pela habilidade.

Alguns ambientes também podem incorporar um resumo das habilidades disponíveis diretamente no prompt do sistema. Nessa configuração, o agente pode descobrir as habilidades disponíveis no prompt e usar activate_skill quando precisar de instruções completas.

Estrutura da Pasta de Habilidades

Uma habilidade usa um layout de pasta no estilo Habilidades do Agente:

<skills_dir>/
	some-skill/
		SKILL.md
		references/
		...
		scripts/
		...
		assets/
		...

Somente SKILL.md é obrigatório. As outras pastas são opcionais.

Pasta ou Arquivo	Obrigatório	Objetivo
`SKILL.md`	Sim	Metadados e instruções principais da habilidade.
`references/`	No	Suporte a documentação, esquemas, exemplos ou modelos.
`scripts/`	No	Scripts Python que podem ser executados apenas quando explicitamente declarados como pontos de entrada.
`assets/`	No	Ativos estáticos usados pela habilidade.

Escrevendo SKILL.md

Cada habilidade deve incluir frontmatter YAML no topo de SKILL.md, seguido por instruções de Markdown.

Exemplo Básico

---
name: sql-helper
description: Helps the agent write safe SQL queries using project schemas.
license: internal
compatibility: "agent-platform"
metadata:
  owner: data-platform
  domain: analytics
allowed-tools: "analyzeQuery inspectSchema"
---

# SQL Helper

Use this skill when the user asks for SQL generation, query review, or schema-aware analysis.

Before writing SQL:
1. Inspect the relevant schema files in `references/`.
2. Prefer explicit column names.
3. Avoid destructive statements unless the user explicitly asks for them and the environment allows them.

Tabela 22-3 Campos de Material Frontal Suportados

Campo	Obrigatório	Descrição
name	Sim	Nome de habilidade exclusivo usado pelo catálogo e pelas ferramentas.
descrição	Sim	Descrição curta usada para descoberta e roteamento.
licença	No	Licença ou política de uso da habilidade.
compatibilidade	No	Nota de compatibilidade para runtimes ou plataformas suportados.
metadados	No	Mapa de metadados de string para string.
ferramentas permitidas	No	Lista de ferramentas separadas por espaço que essa habilidade permite.
pontos de entrada	No	Lista de pontos de entrada executáveis declarados pela habilidade.

Adicionando Arquivos de Suporte

Os arquivos de suporte permitem que uma habilidade mantenha conteúdo detalhado fora das instruções principais. Isso mantém o SKILL.md focado enquanto ainda dá ao agente acesso a um contexto mais rico. Por exemplo:

skills/
	sql-helper/
		SKILL.md
		references/
			warehouse_schema.md
			query_style_guide.md
			examples.md

O agente pode inspecionar esses arquivos com:

list_skill_files("sql-helper", "references")
load_skill_file("sql-helper", "references/warehouse_schema.md")

Use arquivos de suporte para conteúdo como:

Esquemas do banco de dados
Exemplos de API
Modelos de prompt
Guias de estilo
Glossários de domínio
Guias passo a passo
Casos de teste ou exemplos

Criando uma Habilidade Executável

Uma habilidade pode, opcionalmente, expor o comportamento executável reutilizável por meio de run_skill_entrypoint. Destina-se a operações controladas, como cálculos, transformações, validação ou extração de dados estruturados.

As habilidades executáveis devem atender a dois requisitos:

A habilidade deve incluir run_skill_entrypoint nas ferramentas permitidas.
O script deve ser declarado explicitamente na seção de pontos de entrada do SKILL.md.

Exemplo de Habilidade Executável

skills/
	statistics-helper/
		SKILL.md
		scripts/
			summarize_numbers.py

HABILIDADE.md

---
name: statistics-helper
description: Computes basic summary statistics for numeric data.
allowed-tools: "load_skill_file list_skill_files run_skill_entrypoint"
entrypoints:
  - name: summarize_numbers
    script: scripts/summarize_numbers.py
    func: run
    description: Returns count, min, max, mean, and median for a list of numbers.
---

# Statistics Helper

Use this skill when the user asks for basic descriptive statistics.
scripts/summarize_numbers.py:
from statistics import mean, median

def run(*, values: list[float]) -> dict:
    if not values:
        raise ValueError("values must not be empty")

    return {
        "count": len(values),
        "min": min(values),
        "max": max(values),
        "mean": mean(values),
        "median": median(values),
    }
Example invocation:
run_skill_entrypoint(
  name="statistics-helper",
  entrypoint="summarize_numbers",
  args_json="{\"values\": [10, 20, 30, 40]}",
  timeout_seconds=10
)
The runner returns structured output that includes exit_code, stdout, stderr, and a best-effort parsed result when the script prints or returns JSON.

Regras para Pontos de Entrada Executáveis

Pontos de entrada executáveis são intencionalmente restritos. A plataforma só executa arquivos Python que são:

Localizado sob o diretório/scripts da habilidade
Declarado no frontmatter dos pontos de entrada da habilidade
Permitido pela definição allowed-tools da habilidade

A plataforma não fornece execução de script arbitrário de uso geral. Scripts que não são declarados em SKILL.md não são executáveis.

O executor de script usa um timeout, assume como padrão 10 segundos, executa o Python com comportamento de modo isolado e aplica restrições de caminho. No entanto, a execução baseada em subprocesso não é uma sandbox completa do sistema operacional. Para uso em produção, deve-se considerar um isolamento maior, como contêineres, sistemas de arquivos restritos ou controles de rede.

Permissões de Ferramenta com allowed-tools

allowed-tools atua como um gate de permissão no nível da habilidade. Para uma habilidade somente para documentação, você só pode permitir ferramentas de leitura de arquivos:

allowed-tools: "load_skill_file list_skill_files"

Para uma habilidade que pode executar scripts declarados, inclua run_skill_entrypoint:

allowed-tools: "load_skill_file list_skill_files run_skill_entrypoint"

Não adicione run_skill_entrypoint a menos que a habilidade realmente precise de comportamento executável.

Como deixar seus agentes descobrirem e usarem habilidades

Para complementar seu agente com habilidades, você deve instanciar um catálogo de habilidades, um middleware de habilidades e converter habilidades em ferramentas usando os seguintes objetos da biblioteca aidpUtils:

Ferramenta	Objetivo
`discover_skill_catalog`	Determinar locais de pesquisa de habilidades padrão (projeto + usuário) Criar um Catálogo de Habilidades com base em diretórios descobertos
`SkillMiddleware`	Anexe o resumo de habilidades disponíveis e as regras de roteamento ao prompt do sistema. Forneça ajudantes de fábrica para construção de middleware orientada a espaços de trabalho.
`make_skill_tools`	Este método retorna as ferramentas de descoberta de habilidades – activate_skill, list_skill_files, load_skill_file e run_skill_entrypoint. Essas ferramentas podem ser usadas pelo agente para ativar e executar diferentes habilidades.

Veja a seguir um exemplo do que seu arquivo de entrada incluiria:

from aidputils.agents.skills.discovery import discover_skill_catalog
from aidputils.agents.skills.middleware import SkillMiddleware
from aidputils.agents.skills.tools.factories import make_skill_tools
...
class SchoolGradeAgentWithEmbededSkills:
	...
	def init(self) -> None: 
		...
		self.catalog = discover_skill_catalog(skill_folder_whitelist=None)
		self.skill_middleware = SkillMiddleware(self.catalog)
		self.tools = make_skill_tools(self.catalog)

Você pode depurar seu catálogo de habilidades adicionando esta instrução do logger ao seu código. Isso imprimirá todas as habilidades descobertas no catálogo de habilidades:

for info in self.catalog.list():
	logger.info("skill_id=%s name=%s desc=%s root=%s skill_file=%s", info.skill_id, info.name, info.description, info.root_dir, info.skill_file)

Precedência de Habilidade

A plataforma pode carregar habilidades de vários locais, como diretórios de nível de projeto e de usuário. O catálogo agrega esses locais em uma única lista de habilidades com chave de nome.

Quando vários armazenamentos contêm uma habilidade com o mesmo nome, a precedência determina qual deles é usado. Os armazenamentos posteriores substituem os anteriores, o que permite que um aplicativo host controle se as habilidades no nível do usuário, as habilidades no nível do projeto ou as habilidades no nível do espaço de trabalho têm prioridade.

Melhores Práticas de Criação de Habilidades

Mantenha o SKILL.md focado

Use SKILL.md para as instruções principais que o agente precisa imediatamente após a ativação. Coloque esquemas longos, exemplos e material de referência em referências/.

Escreva descrições claras

O campo de descrição é usado para descoberta. Torne-o específico o suficiente para que o agente saiba quando ativar a habilidade.

Bom:

description: Helps generate BigQuery SQL using the finance warehouse schema.

Menos útil:

description: Helps with data.

Usar nomes de ponto de entrada explícitos

Os nomes dos pontos de entrada devem descrever claramente a operação:

entrypoints: 
   - name: validate_query 
   - name: summarize_numbers 
   - name: transform_csv

Evite nomes vagos, como:

entrypoints: 
   - name: run 
   - name: do_it

Retornar resultados estruturados

Scripts executáveis devem retornar resultados serializáveis JSON sempre que possível. Isso torna a saída mais fácil para o agente inspecionar e usar.

Evite execução desnecessária

Prefira instruções e arquivos de referência quando possível. Use pontos de entrada executáveis somente para operações que realmente exigem código.

Adicionar uma Nova Habilidade

Você pode adicionar novas habilidades do Agente criando uma nova pasta dentro do diretório de habilidades e adicionando os arquivos e pastas necessários.

Crie uma pasta no diretório de habilidades: .agents/skills/<skill-name>/.

Adicione um arquivo SKILL.md com o material de frente necessário.

---
name: <skill-name>
description: <what this skill helps the agent do>
---

Escreva as instruções de habilidade em Markdown abaixo do frontmatter.
Adicione arquivos de suporte opcionais em:
```
references/
assets/
scripts/
```
Se a habilidade for executável, adicione run_skill_entrypoint a allowed-tools, declare a entrypoints em SKILL.md e coloque a implementação do Python em scripts/.

Adicionar um Novo Recurso Executável a uma Habilidade Existente

Você pode adicionar uma nova operação executável a uma habilidade existente para expandir os recursos do SKILL.md.

1. Adicione um arquivo Python no diretório scripts/ da habilidade.
```
.agents/skills/<skill-name>/scripts/my_operation.py 
```

2. Implemente uma função run(...).

def run(*, input_text: str) -> dict:
    return {
        "length": len(input_text),
        "uppercase": input_text.upper(),
    }

3. Adicionar um ponto de entrada correspondente a SKILL.md.

allowed-tools: "load_skill_file list_skill_files run_skill_entrypoint"
entrypoints:
  - name: my_operation
    script: scripts/my_operation.py
    func: run
    description: Processes input text and returns structured output.

4. Teste o ponto de entrada com um objeto JSON como argumentos.
```
{
  "input_text": "hello"
}
```

Diagnóstico e Solução de Problemas de Habilidades do Agente

Se você encontrar problemas com a implementação de Habilidades do Agente, verifique esta lista para obter ajuda para resolver seu problema.

O agente não vê minha habilidade

Verifique se:

A pasta de habilidades está localizada em um diretório de habilidades configurado.
A pasta contém SKILL.md.
SKILL.md tem frontmatter YAML válido.
O frontmatter inclui nome e descrição.

O agente ativa a habilidade errada

Verifique se há nomes de habilidades duplicados nos diretórios de habilidades. Se duas habilidades tiverem o mesmo nome, a precedência do catálogo determinará qual delas será usada.

Não é possível carregar um arquivo de suporte

Verifique se:

O arquivo está dentro da pasta de habilidades.
O caminho não inclui travessias como ../.
O arquivo não está oculto.
O arquivo não foi excluído, como __pycache__ ou .pyc.

Um ponto de entrada não será executado

Verifique se:

run_skill_entrypoint está incluído nas ferramentas permitidas.
O ponto de entrada é declarado em SKILL.md.
O caminho do script está em scripts/.
O script é um arquivo .py.
O nome da função no func existe no script.
Os argumentos são um objeto JSON válido.

Um ponto de entrada expira

Aumente timeout_seconds somente se a operação demorar mais. Para operações de longa execução ou com uso intenso de recursos, considere mover a operação para um serviço dedicado ou um ambiente de execução mais isolado.

Exemplo: Concluir Habilidade do Agente

Este exemplo demonstra como seria uma habilidade completa do agente após a implementação.

Estrutura da Pasta

skills/
	customer-support-reply/
		SKILL.md
		references/
			tone_guide.md
			refund_policy.md
			escalation_rules.md

HABILIDADE.md

---
name: customer-support-reply
description: Helps draft customer support replies using the company tone guide and policy references.
allowed-tools: "load_skill_file list_skill_files"
metadata:
  owner: support-operations
  domain: customer-support
---

# Customer Support Reply

Use this skill when the user asks for help drafting, reviewing, or improving a customer support response.

Workflow:

1. Identify the customer’s issue.
2. Load the relevant policy file from `references/` if needed.
3. Draft a clear, empathetic response.
4. Avoid making commitments that are not supported by policy.
5. Recommend escalation when the request matches the escalation rules.
This skill does not run code. It gives the agent structured instructions and optional policy files that can be loaded only when relevant.

Teste do Agente

Você pode testar seus agentes para visualizar e depurar a saída deles. Você também pode criar e gerenciar sessões de teste para explorar diferentes cenários de teste para seus agentes.

A primeira etapa para testar um agente é anexá-lo a uma computação de IA. A ação de anexar um agente envia uma cópia do seu agente para uma computação de IA. Desde que seu agente esteja anexado a uma computação AI, todas as alterações feitas no seu agente serão propagadas para a computação anexada toda vez que você clicar no botão Testar.

Depois de clicar no botão Test, você será levado ao playground de teste.

Página do agente aberta para Testar Playground. Os painéis Chat, Traces e Spans e Explorer estão destacados

O playground de teste tem os seguintes componentes:

Uma janela de chat na qual você pode iniciar uma sessão e começar a conversar com o agente ou retomar uma sessão existente
Uma representação baseada em gráfico do agente
Um painel mostrando uma árvore de rastreamentos e intervalos gerados durante a sessão
Um painel do explorador de rastreamentos e intervalos que exibe atributos de rastreamentos e intervalos, entrada/saída. A guia Detalhes inclui IDs, horário inicial e final, tempo de execução e as guias Eventos destacam os erros durante a execução.

O Playground permite que você interaja e teste cada agente de forma independente, se desejar. Por padrão, o agente supervisor é selecionado, mas você pode optar por conversar e testar cada agente executor de forma independente. Isso permite simular o comportamento de um agente supervisor emitindo solicitações para agentes executores. Para fazer isso, selecione o agente que deseja testar no menu drop-down na janela de chat.

Rastreamentos e intervalos são exibidos no painel central assim que você cria sua primeira mensagem. Cada tarefa corresponde a uma mensagem de usuário diferente. Você pode clicar no cursor esquerdo para expandir o rastreamento e inspecionar os intervalos.

Teste seus Agentes no Playground

Você pode testar o visual builder e os agentes baseados em LangGraph no playground de Teste para validar e depurar seus agentes.

Você deve ter uma computação de IA anexada ao seu agente para testar. Você pode adicionar um novo cluster de computação AI seguindo Create an AI Cluster for an Agent ou anexar um cluster de computação AI existente seguindo Attach an Existing AI Cluster to an Agent.

Navegue até o agente em seu espaço de trabalho. Clique no nome do agente.
Na parte superior da tela, clique em Playground. Pode levar alguns segundos para enviar o agente à sua computação anexada.

Seu agente é exibido no playground de teste.

Criar uma Sessão de Teste do Agente

Você pode criar uma sessão de teste para iniciar uma nova conversa com seu agente.

Todas as sessões criadas no destino do playground de teste em que o agente está hospedado na computação anexada. Depois que uma sessão é criada, ela pode ser retomada posteriormente.

Navegue até o agente em seu espaço de trabalho. Clique no nome do agente.
Na parte superior da tela, clique em Playground
No seletor de sessão, clique em Criar uma sessão.
Inicie uma caixa de diálogo com seu agente informando uma consulta na caixa de chat.

Retomar uma Sessão de Teste do Agente

Você pode retomar as sessões de teste do agente criadas anteriormente.

Observação:

Você só pode retomar as sessões criadas.

Navegue até o agente em seu espaço de trabalho. Clique no nome do agente.
Na parte superior da tela, clique em Playground
No menu suspenso da sessão, selecione uma sessão anterior.
Retome sua caixa de diálogo com seu agente informando uma consulta na caixa de bate-papo.

Excluir uma Sessão de Teste do Agente

Você pode excluir sessões de teste para agentes hospedados na computação AI anexada e sessões que foram criadas em um agente implantado.

Navegue até o agente em seu espaço de trabalho.
Clique na guia Sessões.
Ao lado da sessão que você deseja excluir, clique em Ações e, em seguida, clique em Excluir.
Clique em Excluir.

Sobre Ferramentas do Agente

O Oracle AI Data Platform Workbench suporta modelos de ferramentas que podem ser configurados para acessar seus dados e se adequar aos seus casos de uso.

Os agentes suportam configurações que consistem em um único agente que pode estabelecer interface com uma ou mais ferramentas. O Oracle AI Data Platform Workbench oferece três modelos de ferramentas que podem ser configurados para uso por meio de fluxos visuais ou código:

Código Personalizado: A ferramenta Código Personalizado permite que os desenvolvedores de IA implementem suas ferramentas usando Python. Os desenvolvedores empacotam sua ferramenta em um ZIP, fazem upload dela para seu espaço de trabalho e a configuram como um nó em seu agente. As ferramentas de código personalizado são destinadas a casos em que as ferramentas incorporadas não fornecem a integração de que precisam.
Solicitação HTTP: as ferramentas de Solicitação HTTP permitem que os desenvolvedores usem chamadas de API REST suportadas em seus agentes, aproveitando as APIs do AI Data Platform Workbench e as funções que eles fornecem. Os agentes podem usar APIs REST para criar objetos do espaço de trabalho, verificar detalhes, extrair listas ou modificar objetos existentes. Para obter uma lista completa das APIs disponíveis, consulte API REST para o Oracle AI Data Platform Workbench.
Prompt: A ferramenta de prompt permite que o desenvolvedor de IA defina um prompt parametrizado que pode ser emitido para um LLM para sua escolha. Os casos de uso comuns de uma ferramenta de prompt incluem tarefas de redação de e-mail, tarefas de tradução, conversão de estilo, mensagem de commit git e explicações de código.
RAG: A ferramenta RAG permite que os agentes obtenham conhecimento externo relevante antes de gerar uma resposta. No AI Data Platform Workbench, a ferramenta RAG consulta uma base de conhecimento (26ai Vector Search) e recupera partes de documentos semanticamente relevantes. Esses chunks são então passados para o agente para geração de resposta.
SQL: A ferramenta SQL permite que os agentes executem consultas SQL em origens de dados estruturadas registradas por meio de catálogos externos, como Oracle Autonomous AI Lakehouse, Oracle Autonomous AI Transaction Processing ou Oracle AI Database. A ferramenta destina-se a cenários em que as consultas SQL são predefinidas e podem ser parametrizadas. O objetivo é permitir que um agente atribua valores aos parâmetros. Esta ferramenta não é uma ferramenta NL2SQL que gera uma consulta SQL com base em um prompt de linguagem natural.

Observação:
A ferramenta SQL só executa consultas com dados em um catálogo externo. Não suporta dados armazenados em um catálogo padrão.

Ferramentas de Fluxo do Agente por meio do Fluxo Visual

Ao adicionar ferramentas a agentes por meio do fluxo visual, você pode encontrar ferramentas em Modelos de ferramenta no seu agente. Você adiciona uma ferramenta ao seu agente arrastando-a e soltando-a na tela de fluxo visual. Depois de arrastar o nó da ferramenta na tela, o nó se conecta automaticamente com o agente.

Uma página do agente com a seção Modelos de ferramenta destacada e uma seta apontando das ferramentas para a tela

Cada ferramenta pode ser configurada na guia Parâmetros e ser testada independentemente do agente clicando na guia Teste.

Observação:

Você deve anexar um AI Compute ao seu agente para poder testar uma ferramenta do sistema. Se nenhuma computação estiver anexada, a guia Testar será desativada.

Ferramentas de Fluxo do Agente por meio do Código LangGraph

Você adiciona ferramentas RAG, SQL e Prompt aos agentes codificados por LangGraph por meio de uma instância da classe AIDPToolConf().

from aidputils.agents.toolkit.configs import AIDPToolConf
aidp_tool =  AIDPToolConf(name, description, tool_class , conf, params)

Os parâmetros espelham a experiência de fluxo visual para ferramentas. Para cada ferramenta, você deve fornecer:

Nome: um nome descritivo para ajudar os usuários e o LLM a entender a finalidade da ferramenta.
Descrição: Um resumo completo que fornece informações suficientes para que os usuários e LLMs entendam o que a ferramenta faz.
tool_class: O tipo de ferramenta suportado, PromptTool, SQLTool ou RAGTool.
conf: A configuração da ferramenta. Esta informação está oculta do LLM.
params: Os parâmetros expostos ao LLM.

Ferramenta de Build

A ferramenta Código Personalizado permite que os desenvolvedores de agentes estendam a Plataforma de Dados de IA com seu próprio código Python.

Você empacota a implementação da ferramenta como um arquivo ZIP, faz upload dela para o seu espaço de trabalho e a configura como um nó de ferramenta de Código Personalizado no agente. O agente chama seu código como uma ferramenta, com parâmetros fornecidos pelo LLM no runtime.

A ferramenta Código Personalizado destina-se a casos em que as ferramentas incorporadas (HTTP, SQL, RAG, MCP) não abrangem a integração de que você precisa - por exemplo, quando você precisa executar computação local, analisar um formato específico do domínio ou compor várias etapas que devem aparecer para o agente como uma única chamada de ferramenta.

O AI Data Platform Workbench tem os seguintes limites ao fazer upload de um arquivo ZIP com código Python para sua ferramenta de código personalizado:

Restrição	Limite
Tamanho máximo do ZIP	10 MB
Tamanho máximo do arquivo dentro do ZIP	10 MB por arquivo
Tamanho total máximo descompactado	500 MB
Percurso do caminho	Bloqueado (../ rejeitado)

Observação:

As ferramentas de Código Personalizado são executadas na computação de IA anexada ao seu agente. O código tem acesso ao ambiente de computação e ao acesso de rede de saída sujeito à configuração de rede do espaço de trabalho. Faça upload do código apenas de fontes em que você confia.

Parâmetros da ferramenta de código personalizado

Na guia Parâmetros, você define as configurações estáticas para cada classe de ferramenta no pacote. O menu suspenso Tool Class permite alternar entre as ferramentas descobertas no pacote.

A página da ferramenta Código Personalizado está aberta. A guia Parâmetros é selecionada. O painel Configuração é mostrado à esquerda. O painel de definição da Ferramenta de IA é mostrado à direita.

A guia Parâmetros da ferramenta de código personalizado inclui as seguintes seções:

Classe de ferramenta: Selecione a classe de ferramenta a ser configurada. O menu suspenso é preenchido com base nas classes registradas no tool_implementation.py.
Descrição: Uma descrição clara e concisa do que a ferramenta faz. A descrição é fornecida ao agente e ajuda o LLM a decidir quando chamar a ferramenta. A descrição padrão é lida em tool_config.json e pode ser substituída aqui.
Configuração: As definições estáticas de que a ferramenta precisa no runtime. Essas são as chaves definidas no objeto de configuração de tool_config.json. Exemplos incluem timeout, base_dir, max_output_lines e referências de credenciais. Os valores de configuração suportam referências de parâmetro de runtime {{variable}}. As variáveis de sessão não são substituídas no momento na configuração de ferramenta personalizada; se você precisar de um valor de sessão, informe-o como um parâmetro de runtime do agente.
Definição da ferramenta de IA: o esquema exposto ao agente, incluindo o nome da ferramenta, a descrição e os parâmetros de runtime que o agente pode passar. O esquema é renderizado automaticamente do array de esquema em tool_config.json.

Criação da ferramenta de código personalizado

Um pacote de ferramentas Código personalizado é um arquivo ZIP com a seguinte estrutura:

my_tool.zip 
├── tool_implementation.py    # Required. Contains the tool class(es). 
├── tool_config.json          # Required. Tool metadata and schema. 
├── requirements.txt          # Optional. Python dependencies. 
├── utils/                    # Optional. Helper modules. 
│   ├── __init__.py 
│   └── helpers.py 
├── config/                   # Optional. Static configuration files. 
│   └── settings.yaml 
└── wheels/                   # Optional. Bundled wheel files for offline install. 
    └── humanize-4.15.0-py3-none-any.whl

tool_implementation.py

Cada classe de ferramentas estende CustomToolBase e é decorada com @BaseTool.register. A classe deve implementar o método de classe _execute_tool, que recebe a configuração da ferramenta, os parâmetros de tempo de execução do agente e as variáveis de contexto do sistema, e retorna um valor, como dict, str ou list.

Veja a seguir um modelo de exemplo em branco de um tool_implementation.py:

"""Custom Code tool implementation.""" 
from aidputils.agents.tools.custom_tools.base import CustomToolBase 
 
 
@BaseTool.register 
class MyTool(CustomToolBase): 
    """Brief description of what the tool does.""" 
 
    @classmethod 
    def _validate_config(cls, conf, runtime_params, **context_vars): 
        """Optional. Validate configuration before execution. 
        Raise ValueError to abort the call. 
        """ 
        # Example: require an api_key in the tool configuration 
        if not conf.get("conf", {}).get("api_key"): 
            raise ValueError("api_key is required") 
 
    @classmethod 
    def _execute_tool(cls, conf, runtime_params, **context_vars): 
        """Required. Implement the tool logic. 
 
        Args: 
            conf: the AIDPToolConf dict. User configuration values 
                live under conf["conf"] when the tool is invoked from 
                a deployed agent. During a Test run the tool may 
                receive a flat conf dict; the Developer Toolkit example 
                below uses a small _get_cfg helper that tolerates both 
                shapes. 
            runtime_params: the runtime parameters passed by the 
                agent at invocation time. 
            context_vars: system context (such as datalake_id). 
 
        Returns: 
            Any value (dict, str, list, ...). It will be wrapped into 
            the MCP response by the framework. 
 
            To signal a failure, raise an exception: 
              - ValueError -> INVALID_CONFIG 
              - any other exception -> TOOL_EXECUTION_ERROR 
            Do NOT return {"error": "..."}; the framework wraps a 
            successful return in {"response": ..., "success": True}, 
            so a returned error dict is treated as a normal payload 
            and the agent will not see it as a failure. 
        """ 
        tool_conf = conf.get("conf", conf) 
        param_value = runtime_params.get("my_param", "") 
        # Tool logic here 
        return {"output": f"Processed: {param_value}"} 
 
    @classmethod 
    def _transform_response(cls, response): 
        """Optional. Transform the response before MCP formatting.""" 
        return response

tool_config.json

O arquivo tool_config.json descreve as ferramentas do pacote — nome para exibição, descrição, versão, esquema de parâmetro de runtime e valores de configuração padrão. Cada ferramenta registrada em tool_implementation.py deve ter uma entrada correspondente no array de ferramentas.

Veja a seguir um modelo de exemplo em branco de um tool_config.json:

{
   "displayName": "My Tool Package",
   "description": "Brief description of the tool package.",
   "tools": [
     {
       "toolClassName": "MyTool",
       "displayName": "My Tool",
       "description": "Clear description of when the agent should call this tool.",
       "version": "1.0.0",
       "schema": [
         {
           "name": "my_param",
           "type": "string",
           "description": "What this parameter is for."
         }
       ],
       "conf": {
         "timeout": 30
       }
     }
   ]
 }

Tipos de Campo do Esquema

A guia Parâmetros no visual builder aceita string, número e booliano. O runtime aceita um conjunto mais amplo ao criar tool_config.json manualmente: int, inteiro, float, double, number, numérico, bytes, list, array, sequência, dict, map, mapping, set, tuple, none, null, plus generic forms like list[int]. Esses tipos mais amplos são utilizáveis em JSON, mas não são expostos no menu suspenso da IU.

requerimentos.txt

O arquivo requirements.txt lista as dependências do Python que sua ferramenta precisa. A sintaxe pip padrão é suportada, incluindo especificadores de versão e comentários. O arquivo é opcional. Se sua ferramenta usar apenas a biblioteca padrão Python ou pacotes pré-instalados, você não precisará de um requirements.txt.

Veja a seguir um exemplo em branco de requirements.txt:

# List third-party dependencies one per line. 
# Examples: 
# humanize>=4.0 
# python-dateutil>=2.8,<3.0 
# beautifulsoup4==4.12.3

O AI Data Platform Workbench filtra as dependências no requirements.txt antes de instalá-las na computação AI, para evitar conflitos de runtime com a própria plataforma. As regras de filtragem são as seguintes:

Categoria	Exemplo	Ação
Pacotes de plataforma	langgraph, langchain-core, langchain-oci, langchain_mcp_adapters, pyyaml	Descartado (quebraria o runtime do agente).
Pacotes pré-instalados	oci, requisições, request-toolbelt, websockets, criptografia, certifi, pyopenssl, urllib3, pydantic, pydantic-core, pydantic-settings, numpy, oracledb, sqlalchemy, aiohttp, httpx, httpx-sse, anyio, jsonschema, orjson	Ignorado (já disponível, não há necessidade de declarar).
Instalações de URL ou VCS	git+https://..., -e ./local_pkg	Bloqueado (segurança).
Todos os outros	humanizar, beautyifulsoup4, jmespath	Instalado.

Observação:

As dependências declaradas no requirements.txt são instaladas durante a implantação completa do agente. As dependências não são instaladas durante uma única execução de teste no painel de configuração. Se a sua ferramenta depender de pacotes de terceiros, implante o agente primeiro e, em seguida, exerça a ferramenta no Playground.

Para ferramentas que precisam de dependências que não são pré-instaladas e onde a instalação offline determinística é importante, você pode empacotar arquivos .whl dentro de um diretório wheels/ na raiz do ZIP. A plataforma é instalada a partir do diretório de rodas local primeiro e volta para o índice do pacote somente se necessário. Esta é a abordagem recomendada para ferramentas de produção.

Empacotando rodas para instalação off-line

pip download \
  --dest wheels/ \
  --platform manylinux_2_28_x86_64 \
  --python-version 3.11 \
  --only-binary=:all: \
  -r requirements.txt

Ganchos do Ciclo de Vida da Ferramenta

As ferramentas de código personalizado suportam três métodos de ciclo de vida. Somente _execute_tool é obrigatório.

Método	Quando chamado	Objetivo
_validate_config	Antes da _execute_tool	Valida a configuração. Emitir ValueError para abortar a chamada antes de ser executada.
_ferramenta_execute	Em cada chamada de ferramenta	Obrigatório. Implementa o comportamento da ferramenta. Retorna qualquer valor (dit, str, list) e gera uma exceção para sinalizar uma falha (ValueError → INVALID_CONFIG, qualquer outra exceção → TOOL_EXECUTION_ERROR). Não use um comando {"error": "..."} retornado, pois ele é tratado como uma carga útil normal.
_resposta_transformação	Após _execute_tool	Transforme a resposta antes que ela seja encapsulada no formato MCP e retornada ao agente.
prompt_template	string	Modelo de prompt usado pelo LLM, com variáveis no formato {{variable}} para inserção dinâmica

Valores de configuração versus parâmetros de tempo de execução

Ferramentas de código personalizado têm duas fontes distintas de entrada que são fáceis de confundir. Os valores de configuração são provenientes da seção Configuração da guia Parâmetros e são incorporados à ferramenta quando o agente é implantado. Os parâmetros de tempo de execução vêm do agente no momento da chamada e são diferentes em cada chamada.

Os valores de configuração são acessados via conf.get("conf", conf). Use-os para coisas que não mudam entre chamadas — URLs base, referências de credenciais, timeouts e limites de saída.
Os parâmetros de tempo de execução são acessados via runtime_params.get("nome"). Use-os para os valores que o agente realmente decide no momento da chamada — a consulta, o caminho do arquivo, o corpo da solicitação.

Observação:

Os valores de configuração podem passar pela substituição do modelo e podem chegar como strings, mesmo quando você os definiu como números. Sempre coagir valores de configuração numéricos defensivamente, por exemplo: int(tool_conf.get("timeout", 30)).

Várias Ferramentas por Pacote

Um único ZIP pode conter várias classes de ferramentas. Cada classe registrada com @CustomToolBase.register se torna uma ferramenta separada no agente. O painel Tools na guia Package lista todas as ferramentas descobertas e permite que você ative cada uma de forma independente. Cada ferramenta é configurada separadamente na guia Parâmetros através do menu suspenso Classe da ferramenta.

Ferramenta de código através do Código LangGraph

No criador de código, uma ferramenta de Código Personalizado é registrada por meio da biblioteca aidpUtils Python, fazendo referência ao pacote carregado e selecionando uma de suas classes de ferramentas.

from aidputils.agents.toolkit.tool_helper import create_langgraph_tool
 from aidputils.agents.toolkit.configs import AIDPToolConf
 
hello_tool_conf = AIDPToolConf(
     name="hello_tool",
     description="Returns a hello world greeting.",
     tool_class="HelloTool",  # the class registered with @BaseTool.register
     conf={},                  # values from tool_config.json "conf"; supports {{variable}} substitution
     params=[
         {"name": "name", "type": "string",
          "description": "Name to greet."}
     ],
 )
 
hello_tool = create_langgraph_tool(hello_tool_conf.model_dump())

tool_class deve ser o nome exato da classe registrado via @BaseTool.register em tool_implementation.py. O framework procura a classe no BaseTool.tool_class_registry[tool_class]. conf espelha o objeto conf da entrada correspondente no tool_config.json.

Observação:

Não coloque package_path ou tool_class_name dentro de conf, pois eles não são consumidos.

Ferramentas de Código Personalizado do Agente de Teste

A guia Testar permite que você execute a ferramenta sem executar o agente completo. Forneça valores para quaisquer parâmetros de runtime e quaisquer variáveis de sessão referenciadas na configuração. Em seguida, clique em Executar para chamar a ferramenta e exibir a resposta.

A página da ferramenta Código Personalizado está aberta. A guia Testar é selecionada. Os parâmetros de teste são mostrados no painel esquerdo. Os resultados dos testes são mostrados no painel direito,

Observação:

Se sua ferramenta depender de pacotes de terceiros declarados em requirements.txt, as dependências serão instaladas durante a implantação completa do agente, não durante uma única execução de teste. Para testar o código que depende de pacotes adicionais, implante o agente primeiro e, em seguida, invoque a ferramenta no Playground.

Adicionar uma Ferramenta Personalizada a um Agente

Você pode adicionar uma ferramenta personalizada aos seus agentes para permitir que você use seu próprio código Python para estender a Plataforma de Dados de IA.

Observação:

Uma computação de IA deve ser anexada ao seu agente antes de adicionar uma ferramenta de código personalizado. O AI compute é necessário para instalar dependências e executar a ferramenta.

Navegue até o seu agente.
Em Modelos de ferramenta, arraste e solte uma ferramenta personalizada na tela.
Na guia Pacote, clique para selecionar o arquivo ZIP com seu código personalizado ou arraste-o e solte-o na tela. Aguarde a conclusão do upload.
Revise a lista de ferramentas descobertas na seção Ferramentas da guia Pacote. Cada classe de ferramenta encontrada em seu tool_implementation.py é listada com seu nome, descrição e versão da classe.
Selecione as ferramentas a serem ativadas. As ferramentas desativadas não são expostas ao agente.
Opcional: Clique na guia Testar. Forneça parâmetros de teste e clique em Enviar. Consulte os resultados do teste no painel Resultados do teste.

Ferramenta remota do servidor MCP

Os desenvolvedores de fluxo de agentes podem conectar seus fluxos de agentes a servidores MCP (Remote Model Context Protocol) usando a ferramenta Remote MCP Server.

A ferramenta MCP está disponível tanto no visual builder quanto nas experiências do code builder. Na experiência do code builder, a conexão MCP pode ser configurada por meio da biblioteca aidpUtils Python. Nesta seção, você será guiado pelas experiências do construtor visual e do construtor de código.

Observação:

Esse recurso suporta servidores MCP com transportes transmitíveis por HTTP (servidores remotos). Não há suporte para servidores MCP locais de stdio-transport.

Credenciais MCP no Armazenamento de Credenciais do Oracle AI Data Platform Workbench

Ao configurar seu servidor MCP, você precisa selecionar se o servidor MCP remoto requer Sem Autenticação ou um Token do portador. Se o servidor MCP exigir um token de autenticação, esse token precisará ser adicionado ao Armazenamento de Credenciais para que possa ser referenciado pelo servidor MCP.

Ao criar uma credencial de servidor MCP, você seleciona a opção Token secreto para Tipo de credencial e, em seguida, fornece a chave de identificador, como uma Chave de API e o valor do token. Para obter mais informações, consulte Criar Credenciais (Visualização).

Observação:

Uma única credencial pode conter várias chaves.

Os servidores MCP disponíveis publicamente não exigem autenticação adicional. Por exemplo, a conexão com https://mcp.deepwiki.com/mcp teria esta aparência:

A caixa de diálogo Adicionar servidor MCP personalizado é exibida. As informações são preenchidas para o servidor MCP disponível publicamente DeepWiki.

Como Expor Ferramentas MCP ao Agente

Depois que uma conexão bem-sucedida com o servidor MCP remoto tiver sido estabelecida, você poderá começar a configurar quais ferramentas hospedadas no servidor você deseja expor ao seu agente. O painel de configuração do servidor MCP é mostrado abaixo no caso do servidor MCP DeepWiki.

A página de configuração da ferramenta de servidor MCP remoto é exibida. A guia Ferramentas é selecionada.

À esquerda, a guia Ferramentas exibe uma lista de ferramentas disponíveis no servidor MCP. Você deve adicionar ferramentas para expô-las ao seu agente. Você pode fazer isso clicando na opção Adicionar tudo para expor todas as ferramentas de uma só vez ou clicando em cada opção de ferramenta Adicionar individualmente para selecionar um subconjunto das ferramentas.

A página de configuração da ferramenta de servidor MCP remoto é exibida. A guia Ferramentas é selecionada e os botões Adicionar tudo e Adicionar são realçados.

No exemplo abaixo, adicionamos duas ferramentas (read_wiki_structure, read_wiki_structure). Você pode remover ferramentas clicando em Remover.

A página de configuração da ferramenta de servidor MCP remoto é exibida. A guia Ferramentas é selecionada e read_wiki_structure é selecionado em Adicionado. O botão Remover está visível para read_wiki_structure.

O painel direito da guia Ferramentas fornece documentação sobre cada ferramenta, incluindo o nome da ferramenta, a descrição da ferramenta e os parâmetros da ferramenta. Na captura de tela abaixo, mostro um exemplo para a ferramenta de servidor GitHub MCP add_comment_to_pending_review.

A página de configuração da ferramenta de servidor MCP remoto é exibida. A guia Ferramentas é realçada. O nome da ferramenta, a descrição da ferramenta, a substituição da descrição da ferramenta, os Parâmetros da ferramenta e as alternâncias para Expor ao agente são indicados por texto e setas vermelhas.

O Oracle AI Data Platform Workbench fornece alguns controles adicionais sobre cada ferramenta. Você pode ocultar parâmetros do agente e designar valores a esses parâmetros. Por exemplo, no GitHub, você pode escolher o seu agente para comentar apenas um repositório pré-determinado, como oracle-aidp-samples. Para isso, desative o parâmetro repo e atribua um valor padrão na caixa de texto:

A página de configuração da ferramenta de servidor MCP remoto é exibida. A guia Ferramentas é selecionada. No painel direito, o parâmetro do repositório é realçado e o valor é oracle-aidp-samples. É rebocada.

No campo Instruções da Ferramenta, você também pode substituir a descrição da ferramenta e fornecer uma descrição alternativa com instruções adicionais. Para a maioria dos casos de uso, recomendamos que você adote a descrição fornecida pelo servidor MCP.

A página de configuração da ferramenta de servidor MCP remoto é exibida. A guia Ferramentas é selecionada. No painel direito, o campo Instruções da ferramenta (opcional) é destacado e uma instrução alternativa é fornecida no campo abaixo.

Ferramenta de servidor MCP remoto por meio do código LangGraph

A biblioteca Python aidpUtils oferece aos desenvolvedores a capacidade de selecionar um servidor MCP remoto e expor um subconjunto de suas ferramentas a um agente criado com o LangGraph. Para obter referência da API aidputils, consulte API do Aidp-utils para o Oracle AI Data Platform Workbench.

Você pode criar uma coleção de ferramentas permitidas criando uma instância de build_structured_tools_from_allowed_mcp_tools:

from aidputils.agents.toolkit.tool_helper import build_structured_tools_from_allowed_mcp_tools

TOOLS = build_structured_tools_from_allowed_mcp_tools(
allowed_tools=<ALLOWED_MCP_TOOLS>, 
	server_name=<MCP_SERVER_NAME>, 
	endpoint=<MCP_ENDPOINT>, 
	transport="streamable_http", 
	auth=<MCP_AUTH>, 
	headers={} 
)

Onde:

<MCP_SERVER_NAME> é um nome para exibição que você deseja dar ao seu servidor MCP. Isso é usado para fins de documentação e não é exposto ao agente.
<MCP_ENDPOINT> é o ponto final do servidor MCP (por exemplo, https://api.githubcopilot.com/mcp/)
<MCP_AUTH> é um dicionário com a chave "authType". Essa chave pode ter dois valores: NO_AUTH ou BEARER_TOKEN. No caso de BEARER_TOKEN, outra chave é esperada: "token" com o valor do token do portador.
<ALLOWED_MCP_TOOLS> é uma lista das ferramentas, do servidor MCP, que você deseja expor ao seu agente. Cada ferramenta precisa de uma definição completa da ferramenta JSON seguindo o protocolo MCP.

Veja a seguir um exemplo:

MCP_SERVER_NAME = "test_mcp" 
MCP_ENDPOINT = "http://144.25.36.217:9301/mcp" 
MCP_AUTH = { "authType": "BEARER_TOKEN", "token": "valid-123" }

{
  "ALLOWED_TOOLS": [
    {
      "tool": {
        "name": "get_current_weather",
        "description": "Get current weather for a given city with advanced options.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "city": {
              "type": "string"
            },
            "unit": {
              "type": "string",
              "default": "metric"
            },
            "include_historical": {
              "type": "boolean",
              "default": false
            },
            "detailed": {
              "type": "boolean",
              "default": true
            },
            "timeout": {
              "type": "integer",
              "default": 30
            }
          },
          "required": [
            "city"
          ]
        }
      },
      "instruction": "",
      "argOverrides": {}
    },
    {
      "tool": {
        "name": "get_forecast",
        "description": "Get forecast for a given city with customizable options.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "city": {
              "type": "string"
            },
            "days": {
              "type": "integer",
              "default": 5
            },
            "unit": {
              "type": "string",
              "default": "metric"
            },
            "include_alerts": {
              "type": "boolean",
              "default": false
            },
            "detailed": {
              "type": "boolean",
              "default": true
            },
            "hourly": {
              "type": "boolean",
              "default": false
            }
          },
          "required": [
            "city"
          ]
        }
      },
      "instruction": "",
      "argOverrides": {}
    }
  ]
}

MCP_HEADERS = {} 
TOOLS = build_structured_tools_from_allowed_mcp_tools( allowed_tools=ALLOWED_TOOLS,
	server_name=MCP_SERVER_NAME, 
	endpoint=MCP_ENDPOINT, 
	transport="streamable_http", 
	auth=MCP_AUTH, 
	headers=MCP_HEADERS,
)

O objeto TOOLS pode ser usado ao criar uma instância de um agente com langchain.agent create_agent no método setup() da definição do agente de classe:

def setup(self):
    logger.info("Initializing TestMcpAgent")

    oci_llm = init_oci_llm(llm_conf)

    system_prompt = textwrap.dedent(
        """
        You're a weather agent. Append 12345 to every response.
        """
    ).strip()

    self.agent = create_agent(
        name="test_mcp_high_code",
        model=oci_llm,
        tools=TOOLS,
        system_prompt=system_prompt,
        debug=True,
    )

    logger.info("Agent ready.")

Como alternativa, se você estiver usando uma variável de sessão para armazenar o valor de um token de portador, uma referência a uma variável de sessão criada anteriormente poderá ser designada à chave de token do dicionário de configuração de autenticação. Por exemplo:

test_mcp_auth_config = { "authType": "BEARER_TOKEN", "token" : "{{sessionvariables.cred.mcp.test_mcp.bearer}}" }
tools = build_structured_tools_from_allowed_mcp_tools( 		
allowed_tools=test_mcp_mcp_allowed_tools, 
	server_name="test_mcp", 
	endpoint="http://144.25.36.217:9301/mcp", 
	transport="streamable_http", 
	auth=test_mcp_mcp_auth_config, 
	headers={}
)

Exemplos de código para ferramentas de servidor MCP remoto

Fornecemos amostras de código de ponta a ponta para vários cenários MCP no repositório do GitHub de Amostras do AI Data Platform Workbench.

Testando Ferramentas Remotas do Servidor MCP

Depois que as ferramentas são selecionadas, o próximo passo geralmente é testar ferramentas individuais para garantir que elas se comportem como esperado. Isso pode ser feito através da guia Testar do nó da ferramenta MCP.

A página de configuração da ferramenta de servidor MCP remoto é exibida. A guia Testar é destacada.

Selecione uma das ferramentas que você adicionou na guia Ferramentas, forneça valores de parâmetros e clique no botão Testar.

A página de configuração da ferramenta de servidor MCP remoto é exibida. A guia Testar é selecionada. As informações de list_branches são exibidas no painel esquerdo. A resposta de teste é exibida no painel direito.

A saída da ferramenta é exibida no painel direito.

A guia de detalhes fornece informações sobre o método de autenticação, o URL do servidor MCP e a descrição.

A página de configuração da ferramenta de servidor MCP remoto é exibida. A guia Detalhes é destacada.

O botão Editar ao lado do método de autenticação permite que você modifique a configuração do nó de ferramenta MCP remoto. Você pode alterar o nome de exibição, a descrição e o token ao portador usado ao estabelecer a conexão:

A caixa de diálogo Editar servidor MCP personalizado é exibida. Os detalhes do https://api.githubcopilot.com/mcp são preenchidos.

Conectar um Agente a um Servidor MCP Remoto no Visual Builder

Você pode adicionar acesso a um servidor MCP remoto ao seu agente arrastando o nó de ferramenta do servidor MCP Personalizado para a tela.

Se você não vir a ferramenta de servidor MCP Personalizado disponível, talvez seja necessário reiniciar a computação AI existente ou criar uma nova.

Observação:

A computação de IA que hospeda o agente herda as definições de rede de seu espaço de trabalho. Se você ativar o acesso à rede privada para o espaço de trabalho que hospeda a computação AI, seu agente só poderá acessar servidores MCP hospedados em sua VCN e sub-rede privadas selecionadas. Seu agente pode não conseguir acessar servidores HTTP remotos disponíveis na internet pública.

Navegue até o seu agente.
Na guia Fluxo, em Modelos de Ferramenta, clique e arraste Servidor MCP personalizado para a tela.
Forneça o URL do servidor para o servidor MCP.
Forneça um nome de exibição para o servidor MCP. Este é o nome do nó que é exibido na tela do visual builder.
Opcional: Forneça uma descrição para o servidor MCP. O campo de descrição não é fornecido ao agente.
No menu drop-down Autenticação, selecione um método de autenticação.
- Sem Autenticação: Use esta opção se o servidor MCP remoto estiver disponível publicamente e não exigir autenticação.
- Token do portador: Use esta opção se o servidor MCP remoto exigir um token de autenticação. Você deve armazenar a chave de API no Armazenamento de Credenciais do Oracle AI Data Platform Workbench e fornecer uma referência à entrada do armazenamento de credenciais.
Clique em Conectar. O AI Data Platform Workbench testa a conexão e reporta o resultado.

Ferramenta de solicitação HTTP

A ferramenta Solicitação HTTP permite que seu agente chame qualquer API REST HTTPS.

Você configura a solicitação, incluindo método, URL, cabeçalhos, parâmetros de consulta, corpo da solicitação, autenticação e, opcionalmente, uma etapa de otimização de resposta. Em seguida, o agente chama o ponto final no runtime. A ferramenta de solicitação HTTP está disponível no visual builder e no code builder. No code builder, a ferramenta é configurada através da biblioteca aidpUtils Python.

Observação:

A ferramenta de solicitação HTTP suporta apenas solicitações https:// e HTTP://. Conexões WebSocket (ws/wss), uploads de arquivos binários e certificados autoassinados não são suportados.

Observação:

A computação de IA que hospeda o agente herda as definições de rede de seu espaço de trabalho. Se você ativar o acesso à rede privada para o espaço de trabalho que hospeda a computação AI, seu agente só atingirá pontos finais HTTP na sua VCN e sub-rede privadas selecionadas. Seu agente não pode acessar pontos finais disponíveis na internet pública.

As seguintes definições devem ser fornecidas ao configurar uma ferramenta de Solicitação HTTP:

Configuração	Descrição
Método HTTP	O verbo HTTP a ser usado. Os métodos suportados são GET, POST, PUT, PATCH e DELETE.
URL	O URL completo do ponto final de destino. O URL suporta referências de variável de sessão `{{sessionVariables.variable_name}}` e referências de parâmetro de runtime `{{variable}}`. Por exemplo: `https://api.example.com/users/{{user_id}}/orders`.
Localização	O tempo máximo que a ferramenta aguardará uma resposta do ponto final remoto. O default é 30 segundos e o máximo é 300 segundos.
Tipo de autenticação	O método de autenticação a ser usado ao chamar o ponto final. Consulte a seção Autenticação abaixo para obter a lista de métodos de autenticação suportados.

Observação:

As ferramentas de Código Personalizado são executadas na computação de IA anexada ao seu agente. O código tem acesso ao ambiente de computação e ao acesso de rede de saída sujeito à configuração de rede do espaço de trabalho. Faça upload do código apenas de fontes em que você confia.

Cabeçalhos

Os cabeçalhos são pares de chave/valor enviados com a solicitação HTTP. É possível adicionar quantos cabeçalhos forem necessários clicando no botão Adicionar novo. Os valores de cabeçalho podem fazer referência a variáveis de sessão e parâmetros de tempo de execução usando a sintaxe {{variable_name}}.

Observação:

Para cabeçalhos confidenciais, use o campo Tipo de autenticação para garantir que as credenciais sejam injetadas com segurança no Armazenamento de Credenciais. Autorização, Cookie e X-API-Key são cabeçalhos confidenciais e não podem ser definidos por meio da seção Cabeçalhos.

Parâmetros de Consulta

Os parâmetros de consulta são anexados ao URL como a string de consulta. Você pode adicionar quantos parâmetros de consulta forem necessários clicando no botão Adicionar novo. Como cabeçalhos, os valores de parâmetro de consulta podem fazer referência a variáveis de sessão e parâmetros de runtime.

Descrição

O campo de descrição descreve o que a ferramenta faz, quando ela deve ser usada e que tipo de saídas ou efeitos ela produz. A descrição é fornecida ao agente e ajuda o LLM a decidir quando chamar a ferramenta.

Ao escrever a descrição, você deve se concentrar em:

• Finalidade: Explique o que a ferramenta foi projetada para fazer em uma frase clara. Exemplo: "Esta ferramenta recupera tickets de suporte ao cliente de uma base de conhecimento e os resume por nível de prioridade."
Quando usá-lo: Descreva as condições sob as quais o agente deve chamar essa ferramenta versus outra.
Entradas e saídas: Descreva brevemente os parâmetros necessários à ferramenta e a forma do que ela retorna.

Autenticação da Solicitação HTTP

A ferramenta Solicitação HTTP suporta vários métodos de autenticação. Selecione o método apropriado na lista suspensa Tipo de autenticação.

Tipo de Autenticação	Descrição
Sem autenticação	Nenhuma autenticação foi adicionada à solicitação. Use essa opção para pontos finais acessíveis publicamente.
Controladora de Recursos do OCI	A solicitação é assinada usando o OCI Resource Principal da computação de IA. Use isso ao chamar serviços do OCI, como o Object Storage ou o serviço OCI Generative AI. O acesso é regido pelas políticas do OCI IAM.
Autenticação Básica	Um nome de usuário e uma senha são codificados e enviados no cabeçalho Autorização. As credenciais devem ser armazenadas no Armazenamento de Credenciais.
Token do Portador	Um token de portador é enviado no cabeçalho Autorização. O token deve ser armazenado no Armazenamento de Credenciais.
Autenticação de Cabeçalho	Uma chave de API é enviada em um cabeçalho personalizado (como X-API-Key). O nome do cabeçalho é configurável e o valor da chave deve ser armazenado no Armazenamento de Credenciais.

Quando você seleciona um método de autenticação que requer um segredo, o painel de configuração exibe um seletor de credenciais. Clique no seletor de credenciais para selecionar uma credencial armazenada anteriormente ou crie uma nova no Armazenamento de Credenciais. Consulte a seção Armazenando uma credencial no Armazenamento de credenciais da documentação do servidor MCP para obter o procedimento passo a passo.

Variáveis de Sessão e Parâmetros de Runtime

As variáveis de sessão podem ser referenciadas no URL, nos valores de cabeçalho, nos valores de parâmetro de consulta e no corpo da solicitação usando a sintaxe {{sessionVariables.variable_name}}. Os parâmetros de runtime passados pelo agente no momento da chamada podem ser referenciados usando a sintaxe {{variable_name}}.

Por exemplo, o seguinte URL combina uma variável de sessão para a região com um parâmetro de runtime para o nome do bucket:

https://objectstorage.{{sessionVariables.region}}.oraclecloud.com/n/my-namespace/b/{{bucket}}/o

Quando a ferramenta é executada, {{sessionVariables.region}} é substituído pelo valor da variável de sessão da região para a sessão atual e {{bucket}} é substituído pelo valor que o agente passou no momento da chamada.

Observação:

Os valores de modelo são codificados por URL automaticamente quando substituídos no URL ou nos parâmetros de consulta. Você não precisa codificá-los por URL.

Definição da Ferramenta AI

O lado direito do painel de configuração mostra a definição da Ferramenta de IA. Este é o esquema que é exposto ao agente e inclui o nome da ferramenta, a descrição e a lista de parâmetros de runtime que o agente pode passar ao chamar a ferramenta. A definição da Ferramenta de IA é gerada automaticamente no campo Descrição e nos placeholders {{variable}} detectados no URL, cabeçalhos, parâmetros de consulta e corpo.

O painel de definição da Ferramenta de IA é o painel no lado direito do painel de configuração da ferramenta HTTP mostrado anteriormente neste documento. Até que você forneça uma descrição e defina pelo menos um parâmetro de tempo de execução, o painel de definição da Ferramenta AI mostrará uma mensagem de espaço reservado. Depois de preencher a descrição e fazer referência a pelo menos um {{variable}} no URL, cabeçalhos, parâmetros de consulta ou corpo, o esquema será renderizado no painel.

Otimizando Resposta para o Agente

Muitas APIs retornam respostas grandes que incluem campos que o agente não precisa. O envio de toda a resposta de volta ao agente consome tokens e pode degradar a qualidade do raciocínio do agente. A ferramenta Solicitação HTTP fornece uma seção de otimização de Resposta que permite reduzir o payload de resposta antes de ser retornado ao agente.

Três estratégias de otimização são suportadas:

Seleção de campo JSON: selecione um subconjunto de campos de uma resposta JSON. Você pode especificar um caminho para um objeto aninhado usando notação de ponto (como data.results) e uma lista de campos a serem incluídos ou excluídos.
Seletor CSS HTML: extrai um subconjunto de uma resposta HTML usando um seletor CSS (como article.content). Como opção, remova tags HTML para retornar somente texto.
Troncamento de texto: limita a resposta em um número máximo de caracteres para evitar respostas de texto excessivamente grandes.

Tratamento de Erros e Códigos de Erro

Quando a solicitação HTTP falha, a ferramenta retorna uma resposta de erro estruturada ao agente. O erro inclui um código de erro, uma mensagem legível e detalhes sobre a falha. O agente pode usar essas informações para decidir se deseja tentar novamente, recorrer a uma ferramenta diferente ou relatar a falha ao usuário.

Código de Erro	Categoria	Definição	Recuperáveis
CONNECTION_TIMEOUT	Rede	O ponto final remoto não respondeu dentro do tempo limite configurado.	Sim
FALHA_DE_DNS	Rede	Não foi possível resolver o nome do host no URL.	Sim
CONNECTION_REFUSED	Rede	O ponto final remoto recusou a conexão.	Sim
ERRO_CERTIFICADO_SL	TLS	Não foi possível validar o certificado TLS do ponto final remoto.	No
NÃO AUTORIZADO	401 HTTP	O ponto final remoto rejeitou as credenciais. Verifique se a referência da credencial é válida e não expirou. Para o Controlador de Recursos do OCI, confirme se a computação de IA tem um Controlador de Recursos ativo neste ambiente.	No
PROIBIDO	HTTP 403	As credenciais foram autenticadas com sucesso, mas não têm permissão para o recurso solicitado. Verifique os escopos de API, as permissões ou a política do serviço IAM anexada ao recurso.	No
NOT_FOUND	404 HTTP	O ponto final remoto não pôde localizar o recurso solicitado.	No
LIMIT_TAXA	429 HTTP	O ponto final remoto está limitando a taxa do chamador. Tente novamente após o atraso indicado pelo cabeçalho Repetir Após.	Sim
SERVER_ERROR	HTTP 5xx	O ponto final remoto retornou um erro de servidor. Muitas vezes uma questão transitória.	Sim
SERVICE_UNAVAILABLE	503 HTTP	O ponto final remoto está temporariamente indisponível.	Sim
INVALID_TEMPLATE	Validação	Não foi possível resolver uma referência `{{variable}}`. Verifique se cada variável de sessão referenciada e parâmetro de runtime estão definidos e têm um valor no momento da chamada.	No
INVÁLIDO_URL	Validação	O URL é mal formado, usa um protocolo não suportado ou é resolvido para um endereço bloqueado (por exemplo, um endereço IP privado ou um ponto final de metadados na nuvem).	No
RESPOSTA_GRANDE	Validação	A resposta excedeu o tamanho máximo de resposta de 10 MB.	No
RATE_LIMIT_EXCEDIDO	Plataforma	O agente excedeu o limite de taxa de solicitação por agente da plataforma (60 solicitações por minuto) ou o limite de simultaneidade (10 solicitações simultâneas).	Sim

Cada resposta de erro inclui um campo de orientação com uma próxima etapa sugerida e um campo de detalhes com o tempo decorrido e qualquer contexto específico do erro, como o código de status HTTP.

Ferramenta de solicitação HTTP por meio do Código LangGraph

No code builder, a ferramenta HTTP Request é configurada por meio da biblioteca aidpUtils Python. Defina um AIDPToolConf com o tool_class definido como HttpEndpointTool e informe o dicionário de configuração no campo conf.

from aidputils.agents.toolkit.tool_helper import create_langgraph_tool
from aidputils.agents.toolkit.configs import AIDPToolConf

weather_http_tool_def = {
    "method": "GET",
    "url": "https://api.openweathermap.org/data/2.5/weather",
    "params": {
        "q": "{city}",
        "units": "metric",
        "appid": "{api_key}"
    },
    "auth_type": "NO_AUTH",
    "auth_config": {}
}

weather_http_tool_params = [
    {"name": "city", "type": "string",
     "description": "Name of the city."},
    {"name": "api_key", "type": "string",
     "description": "OpenWeather API key."}
]

weather_http_tool_conf = AIDPToolConf(
    name="get_weather",
    description="Get current weather for a city.",
    tool_class="HttpEndpointTool",
    conf=weather_http_tool_def,
    params=weather_http_tool_params
)

weather_tool = create_langgraph_tool(weather_http_tool_conf.model_dump())

O dicionário conf suporta os mesmos campos do visual builder: método, url, cabeçalhos, parâmetros, corpo, auth_type, auth_config e response_optimization. A lista de parâmetros define os parâmetros de runtime que o agente pode passar.

auth_type	campos auth_config
NO_AUTH	`{}` (vazio)
RESOURCE_PRINCIPAL	`{}` (vazio)
BÁSICO_AUTH	nome de usuário, senha (ou username_vault_id, password_vault_id para credenciais no OCI Vault)
PORTADOR_AUTH	bearer_token (ou bearer_token_vault_id)
API_KEY_AUTH	api_key (ou api_key_vault_id), header_name (X-API-Key padrão)
OAUTH2_CLIENT_CREDENTIALS	token_endpoint, escopo, client_id, client_secret (ou client_id_vault_id, client_secret_vault_id)

Ferramentas de Código Personalizado do Agente de Teste

A guia Testar permite que você execute a ferramenta sem executar o agente completo. Forneça valores para quaisquer parâmetros de runtime e quaisquer variáveis de sessão referenciadas na configuração. Em seguida, clique em Executar para chamar a ferramenta e exibir a resposta.

O painel de resposta mostra o código de status HTTP, os cabeçalhos de resposta, o corpo da resposta e o tempo decorrido em milissegundos. Se a otimização de resposta estiver ativada, a resposta otimizada também será mostrada ao lado da resposta bruta.

Adicionar uma Ferramenta de Solicitação HTTP a um Fluxo de Agente

Você pode adicionar uma ferramenta de solicitação HTTP aos seus agentes para permitir que você chame APIs REST HTTPS.

Observação:

Uma computação de IA deve ser anexada ao seu agente antes de adicionar uma ferramenta de código personalizado. O AI compute é necessário para instalar dependências e executar a ferramenta.

Navegue até o seu agente.
Nos modelos de Ferramenta, arraste e solte uma ferramenta de Solicitação HTTP na tela.
Na guia Parâmetros, forneça o método HTTP. Os métodos suportados são GET, POST, PUT, PATCH e DELETE.
Em URL, forneça o URL completo do ponto final de destino. Você pode usar referências de variáveis de sessão {{sessionVariables.variable_name}} e referências de parâmetros de runtime {{variable}}. Por exemplo: https://api.example.com/users/{{user_id}}/orders.
Para Timeout, forneça o tempo máximo que a ferramenta aguarda por uma resposta de um ponto final remoto em segundos. O valor máximo de timeout é 300. Se nenhum valor for fornecido, o padrão será 30 segundos.
No menu drop-down Autenticação, selecione o tipo de autenticação apropriado.
Forneça os cabeçalhos da sua solicitação HTTP. Clique em Adicionar novo para adicionar mais cabeçalhos.
Forneça quaisquer parâmetros de consulta para sua solicitação HTTP. Clique em Adicionar novo para adicionar outros parâmetros.
Opcional: Clique na guia Testar. Forneça parâmetros de teste e clique em Enviar. Consulte os resultados do teste no painel Resultados do teste.

Ferramenta de Prompt

A ferramenta de prompt permite chamar um LLM em um agente de IA com um prompt templatizado e retorna a resposta do LLM de volta ao agente.

Os prompts fornecidos ao LLM podem incluir parâmetros identificados por chaves duplas, por exemplo, {{PARAMETER_NAME}}. Os valores de parâmetro são atribuídos pelo agente quando a ferramenta é chamada.

Quando Usar as Ferramentas de Prompt

Em princípio, as instruções escritas em uma ferramenta de prompt podem ser incluídas diretamente nas instruções do agente ou fornecidas diretamente pelo usuário final em uma mensagem do usuário. No entanto, existem situações em que a ferramenta de prompt é uma abordagem melhor:

Seu prompt é longo, exigindo instruções de formato detalhadas que abrangem vários tokens dos anos 100.
Incorporar o prompt nas instruções do agente aumentaria o uso do contexto e aumentaria significativamente os custos, especialmente se você estiver adotando um LLM da SOTA para seu agente.
É preciso minimizar o tamanho das instruções dadas ao agente para reduzir o custo.
A tarefa definida pela ferramenta de prompt pode ser tratada por um LLM menor e mais rápido do que o modelo de raciocínio usado pelo agente. Modelos menores são geralmente econômicos e, em alguns casos, podem ser especializados para gerar dados em uma determinada modalidade ou formato.
Uma ferramenta de prompt permite que parâmetros de entrada estruturados controlem a geração de saída. Se o seu caso de uso pode ser parametrizado e a geração pode variar de sessão para sessão, encapsular a geração em uma ferramenta de prompt faz sentido.

Além disso, o encapsulamento das instruções de geração em uma ferramenta de prompt segue muitas práticas recomendadas de arquitetura de agente moderno, incluindo reutilização de ferramentas, capacidade de manutenção, modalidade, consistência de saída, escalabilidade e governança. Alguns exemplos de casos de uso incluem:

Geração de emails, relatórios, resumos, artigos, etc. seguindo uma estrutura pré-definida e aprovada que pode ser usada como um modelo
Geração de saídas JSON complexas
Soma, extração de frases-chave, tarefas de explicação em documentos
Geração de consulta
Geração de modalidade específica (por exemplo, imagens, vídeos, áudio, dados da nuvem de pontos, etc.) que são otimizados para um modelo específico

Ferramentas de Prompt por meio do Fluxo Visual

Veja a seguir um exemplo de uma ferramenta de prompt criada por meio de fluxo visual que solicita a um LLM que gere títulos de postagens de blog com base em um tópico designado pelo agente:

Você é um estrategista de blog principal. Sua tarefa é debater ideias convincentes de postagem de blog com base em um determinado tópico. Para o {{topic}}, gere 5 títulos exclusivos de postagem de blog. Para cada título, inclua uma descrição de uma frase do ângulo que o post levaria. Apresente a saída como uma lista numerada.

Agente aberto com uma ferramenta de prompt selecionada na tela

Para este exemplo, é necessário configurar os seguintes parâmetros para a ferramenta de prompt:

Nome da ferramenta: Use um nome descritivo para a ferramenta para ajudar a orientar o agente. Neste exemplo, sugerimos blog_ideas. Evite usar nomes inúteis como tool123.
Descrição da ferramenta: Forneça uma descrição abrangente do que a ferramenta faz. Se houver limitações para a ferramenta ou se houver cenários em que a ferramenta não deve ser usada, liste-os no campo de descrição.
Região OCI e LLM de serviço de GenAI: Selecione a região OCI para preencher a lista de LLMs disponíveis nessa região e, em seguida, selecione seu LLM.
Parâmetros LLM: Parâmetros como máximo de tokens de saída, temperatura e p superior são configurados na guia Parâmetros do Modelo. Se você não atribuir valores, os valores padrão do serviço OCI Generative AI serão usados.
Consulta: O prompt usado para definir a finalidade da ferramenta é definido no campo Consulta.

Parâmetros que você define no prompt preenchem automaticamente o painel de definição Ferramenta AI. Forneça ao seu agente uma descrição de cada parâmetro, bem como o tipo de parâmetro e o valor padrão, sempre que aplicável.

Ferramenta de prompt do agente com a guia Parâmetros aberta. O parâmetro do tópico é destacado no campo Consulta e uma seta aponta para a seção de definição da Ferramenta de IA na qual os campos de parâmetro da ferramenta são destacados.

Ferramenta de prompt através do Código LangGraph

Se você estiver criando seu agente por meio do código, poderá configurar a mesma ferramenta de prompt no exemplo de fluxo visual da seguinte forma:

prompt_config = {
  "llm": {
    "model_id" : "xai.grok-4",
    "model_provider" : "generic",
    "compartment_id" : "<your-compartment-ocid>",
    "endpoint" : "https://inference.generativeai.<oci-region>.oci.oraclecloud.com"
  }, "prompt_template": """
You are a master blog strategist. Your task is to brainstorm compelling blog post ideas based on a given topic. For the given {{topic}}, generate 5 unique blog post titles. For each title, include a one-sentence description of the angle the post would take. Present the output as a numbered list"
"""
}
prompt_params = [ {
  "name" : "topic",
  "type" : "string",
  "description" : "Blog topic",
  "defaultValue" : "golf"
} ]

Em seguida, instancie a AIDPToolConf da seguinte forma:

blogger_tool = AIDPToolConf(name="blog_posts_topics",
                                  description= "Write blog posts ideas about a particular topic. ",
                                  tool_class = "PromptTool", conf=prompt_config params=prompt_params)

Por fim, você cria uma ferramenta compatível com LangGraph com a função de utilitário create_langgraph_tool() a partir de aidputils:

from aidputils.agents.toolkit.tool_helper import create_langgraph_tool
blogger = create_langgraph_tool(blogger_tool.model_dump())

Você adiciona a ferramenta recém-criada a um agente ReAct. No LangGraph, o código tem a seguinte aparência:

tools_agent1 = [blogger_tool]
self.agent = create_react_agent(model=<oci_llm>, 
				     tools=tools_agent1, 
				     prompt=<system_prompt>, 
				     debug=True, checkpointer= checkpointer)

Tabela 22-4 Propriedades de Configuração da Ferramenta de Prompt

Property	Tipo	Descrição
llm	objeto	Detalhes e parâmetros da conexão LLM
id_modelo	string	Identificador do modelo a ser usado (por exemplo, "xai.grok-4")
provedor_modelo	string	Nome do provedor do modelo LLM (por exemplo, "genérico")
compartment_id	string	OCID do compartimento do Oracle Cloud Infrastructure (OCI)
ponto final	string	URL do Ponto Final do modelo
prompt_template	string	Modelo de prompt usado pelo LLM, com variáveis no formato {{variable}} para inserção dinâmica

Ferramentas de Prompt do Agente de Teste

Você testa a ferramenta independentemente do agente clicando na guia Testar e preenchendo o valor de cada parâmetro. O prompt é enviado ao LLM selecionado.

Ferramenta de prompt do agente aberta na guia Teste

Verifique se a ferramenta de prompt está bem definida e documentada para melhorar os resultados do seu agente.

Adicionar uma ferramenta de prompt a um agente

Você pode adicionar uma ferramenta de prompt aos seus agentes para permitir que você defina prompts parametrizados emitidos para o LLM de sua escolha.

Navegue até o seu agente.
Em Modelos de ferramentas, arraste e solte uma ferramenta Prompt na tela.
Na guia Configuração, selecione o LLM a ser usado e forneça o prompt do LLM. Clique em Código para fornecer a configuração como código JSON.
Forneça uma Temperatura para a resposta como um valor entre 0,0 e 1,0, em que 0,0 fornece uma resposta estritamente factual e 1,0 fornece a resposta mais criativa.
Clique em Aplicar .
Forneça as definições de quaisquer parâmetros que você tenha estabelecido na configuração. Clique em Código para fornecer a configuração como código JSON.
Clique em Aplicar.
Opcional: Clique na guia Testar. Forneça parâmetros de teste e clique em Enviar. Consulte os resultados do teste no painel Resultados do teste.

Ferramenta RAG

A ferramenta RAG emite uma consulta em linguagem natural para um armazenamento de vetores e recupera documentos com base na similaridade semântica entre a consulta e os documentos armazenados.

Observação:

Uma base de conhecimento é um prerrequisito para a criação de uma ferramenta de RAG. Para obter mais informações, consulte Base de Conhecimento.

Ferramentas RAG através do Fluxo Visual

A ferramenta RAG exige que você, como desenvolvedor do agente, forneça valores para os seguintes parâmetros:

Agente aberto com uma ferramenta RAG selecionada na tela

Agente voltado para:
- Nome da ferramenta: Um nome descritivo para a ferramenta que ajuda você e outros usuários a identificar sua função.
- Descrição da ferramenta: Um breve resumo que fornece uma visão geral da ferramenta.
Configuração da ferramenta:
- Base de conhecimento: Uma base de conhecimento armazenada em um dos seus catálogos do Oracle AI Data Platform Workbench.

O agente definirá o valor do campo de consulta com base em sua conversa com o usuário final. Este campo de consulta usa uma consulta de linguagem natural.

Limite é o número de blocos de documentos que você deseja que a ferramenta recupere do armazenamento de vetores. Esse valor é definido pelo desenvolvedor do agente, não pelo próprio agente.

Você pode simular uma consulta emitida pelo agente clicando na guia de teste do RAG também:

Seção de definição da Ferramenta AI da ferramenta RAG do Agente mostrando os campos Consulta e K Principais

Ferramentas RAG por meio do Código LangGraph

A criação de uma ferramenta RAG em seu agente por meio do código requer a configuração das mesmas configurações e parâmetros do fluxo visual. Por exemplo, você define os parâmetros RAG da seguinte forma:

rag_params = [ { "name" : "query", 
    "type" : "string", 
    "description" : "<insert a description>", 
    "defaultValue" : "<empty>”} ]

Em seguida, configure a configuração RAG:

rag_config = { "catalog": "<catalog>", 
		  "schema": "<schema>", 
		  "knowledgeBase": "<knowledge-base-name>", 
		  "top_k": <number-of-documents-retrieved>, 
		  "llm": { 
			    "model_id" : "<model-name>",
			    "model_provider" : "<model-provider>", 
			    "compartment_id" : "<your-compartment-OCID>", 
			    "endpoint" : "https://inference.generativeai.<oci-region>.oci.oraclecloud.com" } 
}

Por fim, você cria uma ferramenta compatível com LangGraph com a função de utilitário create_langgraph_tool() a partir de aidputils:

from aidputils.agents.toolkit.tool_helper import create_langgraph_tool
rag_conf= AIDPToolConf(name="<your-tool-name>", 
			   description= "<your-tool-description>", 
			   tool_class = "RAGTool", 
			   conf=rag_config, 
			   params=rag_params) 
rag_tool = create_langgraph_tool(rag_conf.model_dump())

Tabela 22-5 Propriedades de Configuração da Ferramenta RAG

Property	Tipo	Descrição
llm	objeto	Detalhes da conexão do LLM
catalog	string	Identificador do catálogo de dados
schema	string	Esquema no catálogo
base de conhecimento	string	Nome ou chave da base de conhecimento a ser pesquisada
top_k	inteiro	Número dos principais documentos correspondentes a serem recuperados

Ferramentas RAG do Agente de Teste

Você pode testar a ferramenta RAG na guia Testar depois de anexar seu agente a um cluster de computação AI. Para obter mais informações, consulte Anexar um Cluster de IA Existente a um Agente.

Adicionar uma Ferramenta RAG a um Agente

Você pode adicionar uma ferramenta de geração aumentada de recuperação (RAG) aos seus agentes para permitir que o agente extraia conhecimento externo relevante ao gerar uma resposta.

Navegue até o seu agente.
Em Modelos de ferramentas, arraste e solte uma ferramenta RAG na tela.
Na guia Configuração, selecione a base de conhecimento da qual a ferramenta RAG extrai informações e forneça o prompt para definir as informações a serem extraídas. Clique em Código para fornecer a configuração como código JSON.
Clique em Aplicar .
Forneça as definições de quaisquer parâmetros que você tenha estabelecido na configuração. Clique em Código para fornecer a configuração como código JSON.
Clique em Aplicar.
Opcional: Clique na guia Testar. Forneça parâmetros de teste e clique em Enviar. Consulte os resultados do teste no painel Resultados do teste.

Ferramenta SQL

A ferramenta SQL permite que os desenvolvedores de fluxo de agentes executem consultas SQL predefinidas em tabelas registradas em um catálogo da Oracle AI Data Platform.

Você grava a consulta no design time e define as variáveis de tempo de execução necessárias. O agente fornece valores para essas variáveis quando chama a ferramenta, e os resultados retornam como linhas estruturadas que o agente pode resumir ou passar para um nó downstream.

Agente aberto na guia Desenvolvimento. Um nó de agente SQL_Agent está na tela. O nó da ferramenta SQL é selecionado em Modelos de ferramenta no painel esquerdo.

A ferramenta SQL suporta dois dialetos de consulta. O Spark SQL é executado em tabelas de catálogo padrão armazenadas na AI Data Platform e requer um cluster do Spark. O Oracle SQL é executado em um banco de dados externo, como o Oracle Autonomous AI Database. Você escolhe o dialeto por ferramenta, e o resto da configuração é o mesmo para ambos.

Observação:

A ferramenta SQL destina-se a consultas de leitura. Uma ferramenta típica executa uma instrução SELECT e retorna linhas. O catálogo, o esquema e a consulta que você configura são privados da ferramenta e não são expostos ao agente. Somente o nome da ferramenta, a descrição e a definição da Ferramenta de IA (as variáveis de tempo de execução) ficam visíveis para o agente.

Observação:

A ferramenta de consulta SQL não inicia automaticamente clusters interrompidos. Como resultado, o cluster do Spark usado para a sua ferramenta de consulta do Spark SQL deve ter uma duração de Para Sempre. Se o cluster tiver permissão para girar para baixo em um timeout de inatividade, as consultas SQL do Spark param de funcionar em produção quando o cluster é interrompido.

Consultas Estáticas e Dinâmicas

Uma consulta estática retorna exatamente o que você especifica, sem nenhuma decisão de runtime pelo agente. Uma consulta dinâmica inclui um ou mais placeholders {{variable}} que sinalizam ao agente que o valor está definido no runtime. Para cada espaço reservado, você fornece um nome, um tipo, um valor padrão opcional e uma descrição que o agente usa para escolher o valor.

Por exemplo, a seguinte consulta estática retorna um conjunto de resultados fixo:

SELECT customer_name, region, amount, category 
FROM test_customers 
WHERE period_year = 2025 
ORDER BY customer_name

A substituição do literal por um placeholder {{year}} o transforma em uma consulta dinâmica que o agente pode parametrizar:

SELECT customer_name, region, amount, category 
FROM test_customers 
WHERE period_year = {{year}} 
ORDER BY customer_name

À medida que você adiciona espaços reservados, o painel de definição da Ferramenta de IA é preenchido com cada variável para que você possa definir seu tipo, valor padrão e descrição.

Os placeholders podem aparecer em qualquer lugar da consulta, inclusive nas funções internas. A seguinte consulta Spark SQL corresponde a um valor de severidade sem distinção entre maiúsculas e minúsculas:

SELECT incident_id, project_id, incident_date, incident_type, 
       severity, description, workers_involved, days_lost, 
       root_cause, corrective_action, reported_by, status 
FROM safety_incidents 
WHERE LOWER(severity) = LOWER('{{SEVERITY}}')

Dê a cada variável uma descrição clara e um padrão sensato. A descrição informa ao agente quais valores são válidos e o padrão é usado quando o agente não fornece um.

A definição da Ferramenta de IA é exibida com a variável SEVERITY. A variável tem uma descrição de: Nível de gravidade do incidente: Maior, Moderado, Menor.

Observação:

Nomes de marcador diferenciam maiúsculas de minúsculas. Um placeholder escrito como {{SEVERITY}} e um escrito como {{severity}} são tratados como duas variáveis diferentes, a menos que você use consistentemente letras minúsculas.

Editando a Configuração como JSON

Você pode editar a configuração da ferramenta SQL diretamente como JSON usando a alternância de exibição de código. Isso é útil para copiar uma ferramenta entre fluxos ou fazer edições em massa.

{ 
  "catalogKey": "construction_data", 
  "schemaKey": "admin", 
  "query": "SELECT project_id, project_name, client_name, ...", 
  "isRowLimitEnabled": null, 
  "maxRows": null 
}

O painel Configuração do nó da ferramenta SQL está aberto para a guia Parâmetros. A Exibição de Código é selecionada e o campo do esquema de Entrada exibe o código de exemplo.

Limites de Linha

Você pode limitar o número de linhas que a ferramenta retorna selecionando Máximo de linhas a serem retornadas e informando um valor limite. Os limites de linha protegem o desempenho e controlam o volume de dados enviado de volta ao agente.

Defina esse valor em relação ao modelo que seu agente está usando. Valores maiores podem causar falhas do agente quando as consultas retornam linhas ou colunas largas com valores de texto grandes. Se você estiver vendo erros inesperados do agente, comece reduzindo maxRows.

O limite de linhas é aplicado à própria consulta SQL, antes da execução da consulta. A maioria dos modelos detecta o limite e o coloca à superfície do usuário final. Para uma consulta estática, o limite retorna as primeiras n linhas disponíveis.

Painel Configuração da ferramenta SQL cortado para a opção Máximo de linhas a serem retornadas. A opção é selecionada e um limite de linha de 1000 é especificado.

Observação:

Se você não quiser que seus limites de linha sejam exibidos para os usuários finais, instrua o agente de acordo com suas instruções.

Exemplos de Consulta

Você pode ver exemplos de consulta e um guia para gravar consultas de ferramenta SQL no botão Exibir exemplos de consulta e guia.

A página de configuração da Ferramenta SQL é exibida. Os exemplos e o botão de guia Exibir Consulta são destacados.

O guia mostra diferentes padrões de consulta e fornece diferentes recomendações sobre parâmetros de consulta.

A caixa de diálogo de exemplos e guias da Ferramenta SQL é exibida.

Ferramentas SQL por meio do Código LangGraph

Assim como no fluxo visual, você começa a criar uma ferramenta SQL para seu agente por meio do código LangGraph criando uma consulta:

sql_config = { "catalogKey": "adw23ai_phx", 
	  "schemaKey": "gold", 
	  "query": """Select ... from ... limit {{max_number}}""" }

Você documenta cada parâmetro na consulta SQL no argumento params com um nome, tipo, descrição e, opcionalmente, um defaultValue.

sql_params = [ {  "name" : "max_number", 
		    "type" : "string", 
		    "description" : "<your-description>", 
		    "defaultValue" : "<your-default-value>" } ]

Por fim, você cria uma ferramenta compatível com LangGraph com a função de utilitário create_langgraph_tool() a partir de aidputils:

from aidputils.agents.toolkit.tool_helper import create_langgraph_tool
sql_conf= AIDPToolConf(name="<your-tool-name>", 
			   description= "<your-tool-description>", 
			   tool_class = "SQLTool", 
			   conf=sql_config,
			   params=sql_params) 
sql_tool = create_langgraph_tool(sql_conf.model_dump())

Tabela 22-6 Propriedades de Configuração da Ferramenta SQL

Property	Tipo	Descrição
chave do catálogo	string	Identificador da conexão do catálogo ou do banco de dados
chave do esquema	string	Nome do esquema no catálogo/banco de dados
consulta	string	String de Consulta SQL, pode incluir placeholders em {{}}

Ferramentas SQL do Agente de Teste

A guia Testar executa a ferramenta por conta própria, sem executar o fluxo completo do agente. O teste funciona da mesma forma para ambos os dialetos. Abra a guia Testar, forneça um valor para cada parâmetro de runtime (ou use os padrões) e clique em Enviar para executar a consulta e exibir a resposta.

Observação:

Testar uma ferramenta requer que seu agente esteja anexado a uma computação de IA. Uma computação de IA será anexada se o rótulo AI Compute estiver verde com a computação de IA selecionada em um estado ATIVO.

Referência do Comando SQL

As consultas de ferramentas SQL são consultas de leitura criadas a partir das cláusulas SQL padrão. O dialeto Oracle SQL segue o Oracle SQL em relação ao banco de dados externo. O dialeto Spark SQL tem como alvo tabelas de catálogo padrão, que são tabelas do Delta Lake; o catálogo padrão atualmente executa o Spark 3.5 com o Delta Lake 3.2.0. A maioria das cláusulas é escrita da mesma maneira em ambos os dialetos, porque ambas seguem o SQL padrão. A principal diferença é como cada dialeto limita o número de linhas. A tabela a seguir lista as cláusulas e palavras-chave mais usadas nas consultas de ferramentas SQL, com a forma de cada dialeto.

Palavra-chave ou cláusula	Objetivo	SQL da Oracle	Spark SQL
SELECIONAR	Escolha as colunas a serem retornadas	`SELECT col1, col2`
DISTINCT	Retornar somente linhas exclusivas	`SELECT DISTINCT col`	`SELECT DISTINCT col`
FROM	Nomear a tabela de origem	`FROM table_name`	`FROM table_name`
WHERE	Filtrar linhas por uma condição	`WHERE col = value`	`WHERE col = value`
E OU NÃO	Combinar ou negar condições	`a AND b OR NOT c`	`a AND b OR NOT c`
IN	Corresponder a qualquer valor em uma lista	`col IN (a, b, c)`	`col IN (a, b, c)`
BETWEEN	Corresponder a um intervalo inclusivo	`col BETWEEN x AND y`	`col BETWEEN x AND y`
COMO	Corresponder a um padrão de texto	`col LIKE 'A%'`	`col LIKE 'A%'`
IS NULL	Teste para valores ausentes	`col IS NULL`	`col IS NULL`
ORDENAR POR	Classificar o resultado	`ORDER BY col DESC`	`ORDER BY col DESC`
AGRUPAR POR	Agrupar linhas para agregação	`GROUP BY col`	`GROUP BY col`
HAVING	Filtrar linhas agrupadas	`HAVING COUNT(*) > 1`	`HAVING COUNT(*) > 1`
ENTRAR EM	Combinar linhas de duas tabelas	`a JOIN b ON a.id = b.id`	`a JOIN b ON a.id = b.id`
AS	Alias a uma coluna ou tabela	`col AS name`	`col AS name`
UNION ALL	Combinar dois conjuntos de resultados	`q1 UNION ALL q2`	`q1 UNION ALL q2`
CASE	Retornar um valor condicionalmente	`CASE WHEN c THEN x END`	`CASE WHEN c THEN x END`
Agregados	Sumariar em linhas	`COUNT SUM AVG MIN MAX`	`COUNT SUM AVG MIN MAX`
Limite da linha	Capitalizar o número de linhas	`FETCH FIRST n ROWS ONLY`	`LIMIT n`

Observação:

Você normalmente não escreve o limite de linha sozinho. A configuração de Máximo de linhas a serem retornadas a aplica a você. Os formulários FETCH FIRST e LIMIT são úteis somente quando você deseja um limite explícito dentro da consulta.

Para obter uma gramática SQL completa e os mecanismos de consulta por trás de cada dialeto, consulte as seguintes referências:

SQL da Oracle AI Data Platform

Gramática SQL

Spark SQL e Delta Lake (Catálogo Padrão)

As tabelas de catálogo padrão são as tabelas do Delta Lake. O catálogo padrão atualmente executa o Spark 3.5 com o Delta Lake 3.2.0.

Sintaxe SQL do Apache Spark: Instruções DML Consulta SQL do Spark e sintaxe de instrução DML.
Delta Lake: operações DELETE, UPDATE e MERGE em tabelas Delta de exclusões, atualizações e mesclagens de tabelas.
Delta Lake: Comandos do utilitário Table Operações do utilitário como OPTIMIZE e VACUUM.
Delta Lake: Usar clustering líquido para tabelas Delta Clustering líquido para layout de tabela Delta.

Adicionar uma Ferramenta SQL a um Agente

Você pode adicionar uma ferramenta SQL aos seus agentes para permitir que o agente execute consultas SQL em origens de dados estruturados em catálogos externos registrados.

Navegue até o seu agente.
Nos modelos de Ferramenta, arraste e solte uma ferramenta SQL na tela.
Clique e arraste a alça do conector no agente para estabelecer conexão com o nó da ferramenta.
Clique duas vezes no nó SQL para abrir o painel de configuração.
Forneça um nome e a descrição para sua ferramenta. A descrição é fornecida ao agente e ajuda a decidir quando chamar a ferramenta.
Escolha o Dialeto da consulta:
- O Spark SQL grava consultas em catálogos padrão da AI Data Platform.
- O Oracle SQL grava consultas em catálogos externos da AI Data Platform.
Observação:
O Spark SQL requer um cluster Spark em execução no espaço de trabalho do AI Data Platform Workbench.
Na lista drop-down Cluster, selecione um cluster do Spark em execução. Clique em Criar cluster para provisionar um novo cluster do Spark. Consulte Criar um Cluster Personalizado para obter orientação sobre como criar um novo cluster.

Observação:
A ferramenta de consulta SQL não inicia automaticamente clusters interrompidos. Como resultado, o cluster do Spark usado para a sua ferramenta de consulta do Spark SQL deve ter uma duração de Para Sempre. Se o cluster tiver permissão para girar para baixo em um timeout de inatividade, as consultas SQL do Spark param de funcionar em produção quando o cluster é interrompido.
Em Procurar catálogo, use o campo de pesquisa para localizar um catálogo por nome ou clique no gerenciador de catálogos para localizar o catálogo.
No campo Consulta, informe sua consulta. Clique em Exibir exemplos e guia de Consulta para abrir um painel contendo padrões prontos que você pode copiar ou adaptar.
Selecione Máximo de linhas a serem retornadas para limitar o número de linhas retornadas pelos resultados da sua consulta.

Observação:
Se a sua consulta puder retornar mais linhas do que esse limite, considere adicionar parâmetros de pesquisa como {{customer_name}} ou {{region}} para que o agente possa encontrar dados mais específicos.
No painel Definição da Ferramenta AI, defina o tipo, o valor padrão e a descrição das variáveis definidas na sua consulta.
Opcional: Clique na guia Testar. Forneça parâmetros de teste e clique em Enviar. Consulte os resultados do teste no painel Resultados do teste.

Memória do Agente

A memória do agente é a parte de um sistema de agente de IA que permite ao agente reter e reutilizar informações em turnos, tarefas ou sessões.

Ao contrário da janela de contexto do modelo, que é temporária e limitada ao prompt atual, a memória pode persistir fatos, preferências, decisões anteriores, saídas de ferramentas, planos intermediários ou observações sobre o ambiente.

Memória do Agente na Plataforma de Dados AI

A AI Data Platform fornece memória de curto prazo que é limitada à duração de uma sessão. Você pode configurar o que pode ser mantido na memória na guia Memória do seu agente.

Configuração de Memória de Agente Único

A configuração de memória de um único sistema de agente pode ser encontrada na guia Memória do nó do agente.

A tela do criador visual é exibida com um único nó de agente, InvoiceAnalyst. O nó é selecionado e a guia Memória é realçada.

Configuração da Memória	Descrição
Ativar Memória do Agente	Esta configuração ativa a memória do agente. Quando desativado, o agente é essencialmente um sistema sem monitoramento de estado. Cada turno é tratado de forma independente, e nenhuma pergunta de acompanhamento pode ser feita. Recomendamos que a memória esteja ativada.
Limitar histórico de conversas	Quando essa seleção for desativada, as curvas anteriores preencherão a memória até que o modelo fique sem contexto e um erro seja retornado. Se forem esperadas sessões curtas, não há problema em desativar essa configuração. No entanto, para a maioria dos casos de uso, recomendamos limitar o histórico de conversas.
Configuração de truncamento	Se você optar por limitar o histórico da conversa, poderá decidir truncar o histórico: Mantendo apenas as últimas N mensagens (usuário + agente) Definição de um orçamento geral de token (primeiro a entrar, primeiro a sair) Ou ambos, o que vier primeiro aciona o truncamento da memória do agente
Limites Máximos de Mensagens	Se você optar por manter as últimas N mensagens, poderá definir um valor N.
Orçamento de token	Como alternativa, você pode definir um orçamento geral de token. Os primeiros tokens são eliminados para manter os mais recentes na memória.

Configuração da Memória do Sistema de Vários Agentes (Padrão do Supervisor)

A memória de um sistema de vários agentes é configurada na guia Memória do agente supervisor.

A tela do construtor visual exibiu um multiagente. O nó AccountsManager é selecionado e a guia Memória é exibida.

A memória para um sistema de vários agentes é imposta e não pode ser desativada, e as opções de truncamento de memória exibidas no nó do agente supervisor só são aplicadas à memória do agente supervisor. Cada política de truncamento de memória do agente executor pode ser configurada na guia Memória do nó executor com base na política de isolamento de estado selecionada para todo o sistema.

A configuração de memória do sistema de vários agentes também permite selecionar a política de compartilhamento de memória dos agentes executores. Três opções são possíveis: Stateless, Private e Shared. Observe que a política é aplicada a todos os agentes executores.

Isolamento de Estado para Agentes Executores	Descrição
Sem Informações de Estado	Cada agente executor vê apenas a tarefa atribuída pelo supervisor. Não há história entre as chamadas. Nenhuma solicitação de acompanhamento pode ser feita ao agente supervisor pelo agente executor. Se stateless for selecionado, a memória de cada agente executor será desativada.
Privado(a)	Cada agente executor vê apenas suas próprias interações passadas. Não é possível ver outros agentes executores ou a conversa original do usuário com o agente supervisor.
Compartilhado	Os agentes executores podem ver o histórico completo de conversas entre agentes e usuários. Todos os agentes trabalham em um contexto compartilhado. Se compartilhado for selecionado, você poderá configurar a política de truncamento de memória separadamente para cada agente executor em cada guia Memória do nó do agente.

Variáveis de Sessão

Você pode usar variáveis de sessão personalizadas definidas pelo agente para fornecer pontos de dados contextuais adicionais aos seus agentes durante uma sessão do usuário.

O que são Variáveis de Sessão?

Variáveis de sessão personalizadas e definidas pelo agente fornecem pontos de dados contextuais adicionais ao agente durante uma sessão do usuário. As variáveis podem ser usadas para uma variedade de finalidades, incluindo a definição de valores de parâmetros em ferramentas, fornecendo instruções gerais a um agente e fornecendo informações contextuais sobre o chamador e/ou o aplicativo em que o agente está incorporado.

Aqui está um cenário simplificado em que estamos construindo um agente de suporte ao cliente. O agente de suporte ao cliente é integrado em um site de varejo. Quando um usuário faz login no site de varejo, as informações sobre esse usuário são capturadas pelo aplicativo cliente (userID, nome de usuário, localização geográfica, dispositivo usado, carrinho de compras, etc.) e essas informações podem ser usadas pelo agente de suporte downstream. Vejamos um exemplo de como esses parâmetros de sessão podem ser usados no campo de instruções do agente no AIDP:

You are a customer support agent for the retail website belts-and-buckles.com, specializing in the sales of belts and buckles. Your objective is to answer questions that customers have about their current and past orders, answer questions about items they put in their shopping cart, and answer general questions about belts-and-buckles.com.  
A few guidelines before your start:  
    You are interacting with user {{sessionVariable.userName}}. Always start with a welcome message: Hello {{sessionVariable.preferredSalutation}} {{sessionVariable.userName}}! What’s the weather like today in {{sessionVariable.currentUserGeo}}?

Três variáveis de sessão são usadas no exemplo acima:

userName
Saudação preferida
atualUserGeo

O agente não tem conhecimento prévio do usuário que interage com o site de varejo, não sabe o que é a localização do usuário ou não tem contexto sobre o que está no carrinho de compras do usuário. Em princípio, o aplicativo cliente poderia conhecer todos ou um subconjunto desses valores e passar esses valores em uma solicitação para o agente. Veja um exemplo de como poderia ser uma solicitação ao agente, incluindo os parâmetros da sessão.

Observação:

Este exemplo ilustra a aparência dessa solicitação. Não representa uma decisão de implementação.

"input": [  
{ "role": "user", 
         "content": [  
{ "type": "input_text”,  
	  "text": "What material is the belt Mr Outcast made of?", 
	  “variables”: [“userName”: “Paul”, “preferredSalutation”: “Hon”, “cartID”: NULL, “currentUserGeo”: “Cancun, MX”]  
} 
  ]  
} 
]

O agente responderia: "Olá, Sr. Paul, como está o tempo hoje em Cancún, Mx?"

Outro uso desses parâmetros de sessão é na definição de valores de parâmetro em ferramentas. Por exemplo, uma consulta SQL pode recuperar o conteúdo de um carrinho de compras usando o parâmetro de sessão {{sessionParam.CartID}} :

Select productID, productName, productDescription, 
productPrice from cartTable where cartID == 
{{sessionVariable.cartID}}

As variáveis de sessão são definidas pelo desenvolvedor do agente quando ele cria seus agentes e os valores desses atributos são definidos pelo aplicativo cliente quando uma sessão é criada ou retomada.

Você pode configurar as seguintes configurações ao criar uma nova variável de sessão:

Definição	Descrição
Variável obrigatória	Ative para tornar esta variável de sessão obrigatória para cada chamada de chamada do agente. A desativação torna a variável de sessão opcional para cada chamada de chamada.
Variável de log	Ative para capturar o valor da variável de sessão em logs e rastreamentos. A desativação impede que a variável apareça nos logs. Recomendamos desativar essa definição para variáveis com dados confidenciais.
Nome	Nome da variável de sessão. Use um nome descritivo para facilitar a determinação da finalidade da variável por você e outros usuários.
Valor padrão	Se definido, o valor padrão será atribuído à variável de sessão se outro valor não for definido na chamada de chamada. Se deixado em branco, um valor deverá ser atribuído como parte da chamada de chamada.
Descrição	Descrição da variável de sessão. Forneça uma descrição útil para que você e outros usuários possam entender a função da variável de sessão.

Exemplo: Usando Variáveis de Sessão na Configuração de Ferramentas

Você pode usar uma variável de sessão em uma configuração de ferramenta SQL como parte da própria consulta SQL.

Neste exemplo, a variável de sessão geo é usada para filtrar o resultado da consulta SQL:

A janela da ferramenta SQL para uma ferramenta de agente é exibida. A guia de parâmetros é selecionada e o usuário está digitando {{sessionvariables.ge para selecionar sessionvariables.geo.

Você pode usar variáveis de sessão e parâmetros de ferramenta dentro da mesma consulta. No exemplo abaixo, o parâmetro titleID é definido pelo agente enquanto a variável de sessão geo é fornecida pelo aplicativo de chamada.

$A janela da ferramenta SQL para um agente é exibida. A guia de parâmetros é aberta. No campo de consulta, o usuário definiu 'onde market_code= {{sessionvariables.geo}} e title = {{titleID}}'.$

Variáveis de Sessão Geradas pelo Sistema

As variáveis de sessão são geradas automaticamente quando um servidor MCP remoto está conectado a um agente e esse servidor MCP requer autenticação, como um token de portador.

A caixa de diálogo Adicionar servidor MCP personalizado é exibida. A mensagem de aviso

A variável de sessão contém o valor do token do portador. O nome desta variável de sessão gerada pelo sistema não pode ser alterado e é uma variável obrigatória. A variável do sistema é excluída quando o nó MCP é removido da tela.

A guia Variáveis de um agente é exibida. Os detalhes de sessionvariables.cred.mcp.GitHub.bearer são destacados.

No Playground, você fornece um valor para a variável de sessão gerada pelo sistema. Nesse caso, você precisa fornecer um token ao portador para usar o servidor MCP. Você pode selecionar o mesmo (ou outro) token que usou durante a configuração do nó MCP.

A caixa de diálogo Variáveis de sessão é exibida. sessionvariables.cred.mcp.GitHub.bearer é destacada e uma lista suspensa de tokens de autenticação é exibida.

O mesmo se aplica se você implantar o agente. Você precisará fornecer o token de autorização. Para obter mais informações, consulte Designar Valores a Variáveis de Sessão do Playground.

Exemplo: Designando Valores a Variáveis de Sessão ao Chamar um Ponto Final Implantado

Neste exemplo, você tem duas variáveis de sessão: userLocation e UserName, o aplicativo cliente está transmitindo valores de variáveis de sessão por meio do campo metadata do body. Demonstraremos como você pode designar valores por meio do Python e da CLI do OCI.

Se você usar a biblioteca de solicitações Python, o payload será o seguinte:

body = { 

            "isStreamEnabled" : False, 

            "trace" : False, 
            "input" :[{ 
                "role":"User", 
                "content":[{ 
                    "type" : "INPUT_TEXT", 
                    "text" : “Hello how can you help me?”                  
                }] 
            }], 

            "metadata": { 
            "sessionvariables.userLocation": "Canada",  
            "sessionvariables.UserName": "George" 
        } 
        } 

response = requests.post( 
url = <insert-chat-url>,  
params = None,  
auth = <insert-oci-signer>, 
json = body, 
headers={“x-session-id": <insert-a-session-key>,} 
)

Como alternativa, se você usar a CLI do OCI, o payload será o seguinte:

oci raw-request \ 
  --http-method POST \ 
  --auth security_token \ 
  --request-body '{ 
    "isStreamEnabled": false, 
    "input": [ 
      { 
        "role": "user", 
        "content": [ 
          { 
            "type": "INPUT_TEXT", 
            "text": "Hello how can you help me?" 
          } 
        ] 
      } 
    ], 
    "metadata": { 
      "sessionvariables.userName": "George", 
      "sessionvariables.userLocation": "Canada"}" 
    } 
  }' \ 
  --request-headers '{ 
    "x-session-id": "george-session-may11" 
  }' \ 
  --target-uri "<insert-your-agent-flow-uri>"

Criar uma Variável de Sessão na Guia Variáveis do Agente

Você pode criar uma nova variável de sessão e adicioná-la ao seu agente na guia Variáveis.

Navegue até o agente ao qual você deseja adicionar uma variável de sessão.
Clique na guia Variáveis.
Clique em Adicionar variável de sessão.
Selecione esta opção se a variável de sessão for obrigatória.
Selecione se o valor da sua variável de sessão deve ser registrado em logs e rastreamentos. Deixe esta configuração desativada para dados confidenciais.
Forneça um nome e descrição significativos para sua variável de sessão.
Forneça um valor padrão para sua variável de sessão. O valor padrão será atribuído à variável de sessão se nenhum outro valor for atribuído como parte da chamada.
Clique em Criar.

Consulte Variáveis de Sessão nas Instruções de Fluxo do Agente

Você pode consultar variáveis de sessão nas instruções do agente e nas configurações da ferramenta, incluindo a consulta da ferramenta SQL e Prompt.

Navegue até o fluxo do agente.
Clique no nó da ferramenta SQL ou Prompt no Playground.
No campo Consulta, comece a digitar {{sessionvariables.
Selecione a variável de sessão na lista de variáveis de sessão existentes.

Exibir Agentes e Ferramentas usando uma Variável de Sessão

Você pode exibir uma lista de agentes e ferramentas usando uma variável de sessão específica na guia Variável do fluxo do agente.

Navegue até um fluxo de agente usando a variável de sessão para a qual deseja exibir agentes e ferramentas relacionados.
Clique na guia Variável.
Ao lado de Usado em: para sua variável de sessão, clique no menu suspenso. Uma lista de agentes e ferramentas que usam a variável de sessão é exibida.

Atribuir Valores a Variáveis de Sessão do Playground

Você pode atribuir valores a variáveis de sessão a qualquer momento na guia Playground.

Navegue até o fluxo do agente.
Na parte superior do Playground, clique em Parâmetros de Sessão. Uma lista de todas as variáveis de sessão no fluxo do agente é exibida.
Modifique suas variáveis de sessão. Depois de retomar a sessão do Playground, os últimos valores de variáveis de sessão atribuídos são usados.

Guardrails de proteção

Guardrails são mecanismos de segurança para orientar e controlar o comportamento dos agentes de IA.

No Oracle AI Data Platform Workbench, as grades de proteção são configuradas para evitar a geração ou o consumo de conteúdo tóxico e malicioso por fluxos de agentes. Guardrails também impedem o vazamento de informações de identificação pessoal (PII) pelo fluxo do agente. Os guardrails específicos disponíveis no seu AI Data Platform Workbench se aplicam à moderação de conteúdo, injeção de prompt e PII.

Observação:

Os corrimãos oferecidos pelo Oracle AI Data Platform Workbench só estão disponíveis em inglês.

Os Guardrails oferecidos no AI Data Platform Workbench são implementados pela equipe de serviço da OCI Generative AI. Consulte Guardrails for OCI Generative AI. Com base na configuração dos seus guardrails, o serviço AI Data Platform Workbench chama a API Aplicar Guardrails na sua tenancy do OCI.

Guardrails em Visual Flow Canvas

Por padrão, nenhum corrimão é aplicado ao seu sistema além dos controles de segurança nativos do provedor do modelo. Para adicionar guardrails, você deve arrastar um nó de guardrails para o criador de fluxo visual do agente e conectá-lo ao agente.

Um nó de guardrails pode filtrar o tráfego entre um acionador de chat e um nó de agente, entre um supervisor e agentes executores ou entre nós de agente e ferramenta. Para a maioria dos cenários, recomendamos um único nó de guardrails entre o trigger de chat e o nó do agente. Isso garantirá que todas as mensagens do usuário de entrada e as mensagens geradas pelo agente serão filtradas pelos guardrails.

Um agente aberto ao criador visual. O nó de guardrails é destacado na paleta.

O nó de guardrails só pode ser inserido entre:

Um nó de trigger de chat e um agente (supervisor ou executor)

Quais Guardrails estão disponíveis?

O diagrama abaixo mostra uma interação simples entre um usuário final e um agente. Neste cenário, todos os guadrails são aplicados (moderação de conteúdo – CM, prevenção de injeção imediata – PI e detecção de PII – PII). O PI só é aplicado à consulta do usuário.

Após a segunda mensagem emitida pelo usuário final, uma tentativa de PI foi detectada e a mensagem do usuário foi bloqueada após a ação selecionada do desenvolvedor do agente na detecção de PI (bloco).

Diagrama descrevendo um exemplo de corrimãos de fluxo do agente AI

Moderação do Conteúdo

A moderação de conteúdo é uma implementação comum de guardrails na maioria das IA generativa. Sem controle, os LLMs podem gerar conteúdo prejudicial, promover conteúdo violento, racista e sexualmente explícito. É imperativo dar aos desenvolvedores do agente total visibilidade e controle sobre como as interações do usuário com os agentes são monitoradas e verificadas em busca de conteúdo potencialmente prejudicial. A moderação de conteúdo impede que conteúdos odiosos, sexuais, violentos, tóxicos, depreciativos ou baseados em assédio sejam considerados ou gerados pelo fluxo do agente. Nosso modelo de guardrails classifica o conteúdo ao longo dessas seis categorias e sinaliza o conteúdo que pertence a uma dessas categorias.

Você pode optar por executar uma ação na consulta de entrada do usuário ou na resposta do modelo:

Bloqueio: Você impede que o agente processe a entrada do usuário e gere uma resposta. Os usuários recebem uma resposta de erro do fluxo do agente.
Informar: Você permite que o fluxo do agente processe a entrada do usuário e gere uma resposta. O agente notifica o usuário de que a entrada ou a resposta continha conteúdo que atendia aos critérios de guardrail.
Permitir: Você permite o processamento e/ou a geração de conteúdo potencialmente prejudicial pelo fluxo do agente.

A ação Bloquear é selecionada para moderação de conteúdo quando você cria um fluxo de agentes. A Oracle recomenda manter o Bloqueio como sua seleção de guardrail para moderação de conteúdo.

Injeção de Prompt

Os guardrails de injeção imediata para agentes de IA são um mecanismo de proteção que detecta, evita e mitiga instruções maliciosas ou não intencionais incorporadas nas entradas do usuário. Os ataques de injeção de prompt tentam substituir ou subverter as instruções, políticas ou metas originais do agente inserindo texto oculto que diz ao modelo para ignorar regras anteriores, exfiltrar segredos ou executar ações não autorizadas.

Você pode escolher as mesmas ações que podem ser tomadas para a moderação de conteúdo: bloquear, informar ou permitir. Os guardrails de injeção de prompt só se aplicam à consulta de entrada do usuário.

Bloco: Você impede que o agente processe a entrada do usuário. Os usuários recebem uma resposta de erro do fluxo do agente.
Informar: Você permite que o fluxo do agente processe a entrada do usuário. O agente notifica o usuário de que a entrada continha conteúdo que atendia aos critérios de guardrail.
Permitir: Você permite o processamento de conteúdo potencialmente prejudicial pelo fluxo do agente.

A ação Bloquear é selecionada quando você cria um fluxo de agentes. A Oracle recomenda manter o Bloco como sua seleção de corrimão para injeção imediata.

Informações de Identificação Individual (PII)

Os guardrails de PII detectam, bloqueiam ou mascaram automaticamente PII das consultas de entrada do usuário ou das respostas dos agentes. Esse guardrail impede que o agente exponha informações confidenciais do usuário de maneiras que violem regulamentos de privacidade ou políticas organizacionais.

As grades de proteção PII suportam quatro tipos de entidade:

E-mail
Número de telefone
Endereço físico
Nome da pessoa

Para cada uma dessas quatro entidades, você opta por aplicar quais das seguintes ações seu agente executa na consulta de usuário de entrada ou na resposta do agente:

Bloco: Você impede que o agente processe a entrada do usuário e gere uma resposta. Os usuários recebem uma resposta de erro do fluxo do agente.
Informar: Você permite que o fluxo do agente processe a entrada do usuário e gere uma resposta. O agente notifica o usuário de que a entrada ou a resposta continha PII.
Mascaramento: Você permite que o fluxo do agente processe a entrada e gere uma resposta mascarada. Qualquer PII usado é redigido para evitar a exposição.
Permitir: Você permite o processamento e/ou a geração de dados de PII pelo fluxo do agente.

Em um novo fluxo de agente, o PII é permitido na entrada e na resposta do usuário por padrão. A Oracle recomenda que você selecione cuidadosamente o guardrail para PII com base em suas necessidades de segurança.

Ativar Guardrails Específicos em um Nó

Você pode escolher quais guardrails ativar e como cada um é configurado ao adicionar um nó de guardrail à sua tela visual.

Navegue até o fluxo do agente em seu espaço de trabalho.
Arraste um nó Guardrails da paleta para a tela.
Forneça um nome e descrição significativos para o nó.
Alterne um corrimão para ativá-lo e comece a configurar. Pressionar o botão de alternância novamente desativa o corrimão e suas configurações.
Selecione a configuração de corrimão necessária para cada categoria.

Criar um Cluster de IA para um Agente

Você pode criar um novo cluster de IA diretamente na interface do agente e anexá-lo imediatamente.

Para obter mais informações, consulte IA Compute.

Na página inicial, navegue até o agente.
Clique em Compute e, em seguida, clique em Criar uma nova computação AI.
Forneça um nome e uma descrição para o cluster de computação de IA.
Selecione o número de OCPUs e o tamanho da memória do seu cluster de computação AI.
Clique em Criar.

Anexar um Cluster de IA Existente a um Agente

Você pode anexar um cluster de IA criado anteriormente a um agente no qual você tenha pelo menos permissões de USO.

Na página inicial, navegue até o agente.
Clique em Compute e, em seguida, clique em Anexar ao AI Compute.
Clique no cluster que deseja usar na lista.
Seu agente mostra a AIcompute: (ClusterName) em execução quando ela foi anexada com sucesso. Isso pode levar alguns minutos.

Desanexar um Agente do AI Compute

Você pode desanexar um agente de uma computação AI. A desanexação da computação AI remove o código do agente em execução na computação anexada e impede o teste.

Observação:

Desanexar um agente da computação AI não exclui o agente. Você pode retomar a criação e o teste do agente anexando-o à mesma computação de IA ou a uma computação diferente.

Na página inicial, navegue até o agente.
Clique em Compute e clique em Desanexar do AI Compute.

Implantação do Agente A2A

O protocolo Agent2Agent (A2A) é um padrão aberto para comunicação entre agentes independentes de IA, incluindo agentes criados com diferentes estruturas, hospedados por diferentes fornecedores ou executados como sistemas remotos opacos.

Seu objetivo é dar a esses agentes um modelo de interação compartilhada para que eles possam descobrir os recursos uns dos outros, negociar formatos de entrada/saída suportados, delegar ou colaborar em tarefas e trocar informações com segurança sem expor memória interna, ferramentas ou detalhes de implementação. Para obter mais informações, consulte Protocolo A2A (Agent2Agent).

A2A destina-se a resolver a interoperabilidade do agente: em vez de cada integração de agente ser personalizada, um cliente ou outro agente pode interagir com qualquer agente remoto compatível com A2A usando um conjunto comum de conceitos e operações. As especificações se concentram em mensagens, tarefas, peças, artefatos, atualizações de streaming e notificações push; ele oferece suporte a respostas síncronas, trabalho assíncrono de longa execução, streaming e padrões de segurança/autorização de estilo empresarial.

Na Oracle AI Data Platform, todos os agentes implantados recebem um caminho de chamada /A2A que pode ser chamado por aplicativos clientes A2A.

O que é um cartão de agente?

Um Cartão de Agente é um documento de metadados JSON publicado por um servidor A2A. No AIDP, o servidor A2A é a computação AI que hospeda a implantação do seu agente.

O cartão descreve a identidade do agente, o ponto final de serviço, protocolos/transportes suportados, recursos, habilidades, modos de entrada/saída suportados e requisitos de autenticação; os clientes o usam para descobrir se o agente é adequado e como chamá-lo. Um cartão de agente devidamente documentado é um requisito do protocolo A2A.

Os cartões de agente no AI Data Platform Workbench estão no estado Preliminar, o que significa que o agente não foi implantado ou Publicado, o que significa que o cartão foi implantado ao lado do agente.

Ações do Cartão do Agente

Durante o desenvolvimento de um agente, o cartão está disponível no menu Ações do agente.

Dois cartões de agente estão acessíveis:

O rascunho do cartão reflete o estado atual do agente em desenvolvimento.
O cartão publicado corresponde a um snapshot do cartão obtido quando o agente foi implantado. O cartão publicado reflete o estado do agente implantado.

Campos do cartão do agente

O AI Data Platform Workbench suporta um subconjunto dos campos atuais de cartão do agente de protocolo A2A, disponíveis aqui: Protocolo A2A - Cartão do Agente.

Campo	Obrigatório	Descrição
`name`	Sim	Um nome legível para o agente. Exemplo: "Agente de Receita"
`description`	Sim	Uma descrição legível do agente, auxiliando os usuários e outros agentes na compreensão de seu propósito. Exemplo: "Agente que ajuda os usuários com receitas e culinária".
`Agent Version`	Sim	A versão do agente. Exemplo: "1.0.0" de
`Documentation URL`	No	Um URL que fornece documentação adicional sobre o agente.
`Provider - Organization`	No	O provedor de serviços do agente.
`Provider - URL`	No	O URL do provedor de serviços.
`Capabilities`	Sim	Conjunto de recursos A2A suportado pelo agente. Somente `streaming` pode ser configurado (Verdadeiro/Falso)
`Skills`	Sim	Habilidades representam as habilidades de um agente. É em grande parte um conceito descritivo, mas representa um conjunto mais focado de comportamentos que o agente provavelmente terá sucesso. As habilidades representam uma matriz de AgentSkill.

Cada AgentSkill é feito de vários campos que documentam os recursos do agente. Definir as habilidades do agente no cartão do agente é a operação mais demorada e é um processo iterativo. As habilidades podem ser editadas (juntamente com o restante do cartão de agente) no cartão de agente preliminar antes da implantação.

Observação:

inputModes, outputModes e securityRequirements são fornecidos pelo AI Data Platform Workbench e não podem ser modificados.

Campo	Obrigatório	Descrição
`Skill ID`	Sim	Um identificador exclusivo para a habilidade do agente.
`Skill Name`	Sim	Um nome legível para a habilidade.
`Description`	Sim	Uma descrição detalhada da habilidade.
`Tags`	Sim	Um conjunto de palavras-chave que descreve os recursos da habilidade.
`Examples`	No	Exemplos de prompts ou cenários que essa habilidade pode tratar.

Caminho A2A do Ponto Final de Implantação do Agente

Um caminho /a2a é exposto no URL de um agente implantado, além de /chat.

Por exemplo, um agente exporá esses caminhos para clientes externos:

https://gateway.aidp.{oci-region}.oci.oraclecloud.com/agentendpoint/{agentId}/chat
https://gateway.aidp.{oci-region}.oci.oraclecloud.com/agentendpoint/{agentId}/a2a

Ambos os caminhos (/chat, /a2a) podem ser consumidos por clientes separados.

Variáveis de Sessão no A2A

Os valores de variáveis de sessão podem ser passados para um agente A2A no campo metadata da mensagem. O trecho de código JSON abaixo mostra o payload de uma mensagem do usuário emitida para o agente a2a com três variáveis de sessão: userName, geoLocation e os:

{
  "jsonrpc": "2.0",
  "method": "message/send",
  "params": {
    "contextId": "session_12345",
    "taskId": "task_67890",
    "message": {
      "role": "user",
      "parts": [
        {
          "text": "What is the current status of my order?",
        }
      ],
      "metadata": {
        "sessionvariables.userName": "George",
        "sessionvariables.geoLocation": “Dallas, TX”,
        "sessionvariables.os": "mobile_ios"
      }
    }
  },
  "id": "rpc-99821"
}

Exemplo: Chamando um Agente A2A com a CLI do OCI (Não Streaming)

oci raw-request \
  --http-method POST \
  --auth security_token \
  --request-body '{
    "id": "<your-request-id>",
    "jsonrpc": "2.0",
    "method": "message/send",
    "params": {
      "configuration": {
        "acceptedOutputModes": [
          "text/plain",
          "text"
        ]
      },
      "message": {
        "contextId": "<your-context-id>",
        "kind": "message",
        "messageId": "<your-message-id>",
        "parts": [
          {
            "kind": "text",
            "text": "What is the capital of India?"
          }
        ],
        "role": "user"
      }
    }
  }' \
  --request-headers '{
    "x-session-id": "<your-session-id>",
    "dh-user-principal": "<your-user-principal>"
  }' \
  --target-uri " <your-a2a-agent-endpoint-url>"

Exemplo: Chamando um Agente A2A com a CLI do OCI (Streaming)

oci raw-request \
  --http-method POST \
  --auth security_token \
  --request-body '{
    "id": "<your-request-id>",
    "jsonrpc": "2.0",
    "method": "message/stream",
    "params": {
      "configuration": {
        "acceptedOutputModes": [
          "text/plain",
          "text"
        ]
      },
      "message": {
        "contextId": "<your-context-id>",
        "kind": "message",
        "messageId": " <your-message-id>",
        "parts": [
          {
            "kind": "text",
            "text": "What is the capital of India?"
          }
        ],
        "role": "user"
      }
    }
  }' \
  --request-headers '{
    "x-session-id": "<your-session-id>",
    "dh-user-principal": "<user-principal>"
  }' \
  --target-uri "<your-a2a-agent-endpoint-url>"

Exemplo: A2A Client SDK

import asyncio
import json
import logging
import typing
from collections.abc import Iterator
import uuid
import httpx
import oci
from a2a.client import A2AClient, ClientFactory
from a2a.types import (
    AgentCard,
    Message,
    Part,
    Role,
    TextPart,
    SendMessageRequest,
    MessageSendParams,
    MessageSendConfiguration,
    Task, SendMessageSuccessResponse, SendStreamingMessageRequest,
)

class OCIAuth(httpx.Auth):
    """httpx auth implementation using OCI signer via requests auth adapter."""

    def __init__(self, signer: oci.signer.AbstractBaseSigner):
        self._requests_auth = _OCIRequestsAuth(signer)

    def auth_flow(self, request: httpx.Request) -> Iterator[httpx.Request]:
        req = RequestsRequest(
            method=request.method,
            url=str(request.url),
            headers=dict(request.headers),
            data=request.content,
        )
        prepared: RequestsPreparedRequest = req.prepare()
        prepared = self._requests_auth(prepared)
        request.headers.update(dict(prepared.headers))
        yield request



def getOCIAuth():
    conf = oci.config.from_file(profile_name="DEFAULT")
    token_file = conf['security_token_file']
    token = None
    with open(token_file, 'r') as f:
        token = f.read()
    private_key = oci.signer.load_private_key_from_file(conf['key_file'])
    signer = oci.auth.signers.SecurityTokenSigner(token, private_key)
    auth = OCIAuth(signer=signer)
    return auth


async def _call_agent_with_a2a(agent_url: str, query: str, context_id: str,auth:OCIAuth) -> str:
    """Call an agent using the A2A protocol."""
    try:
        # Initialize OCI signer
        #headers = {"dh-user-principal": "dh-user"}
        headers = {"Accept": "*/*",
                   "dh-user-principal": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."}

        async with httpx.AsyncClient(timeout=60.0, auth=auth,headers=headers) as hc:
            agent_card = await _get_agent_card(agent_url,auth)
            print(f"Agent card is {agent_card}")

            client =  A2AClient(httpx_client=hc, agent_card=agent_card)
            # Create message
            message = Message(
                message_id=str(uuid.uuid4()),
                context_id=context_id,
                role=Role.user,
                parts=[Part(root=TextPart(text=query))],
                metadata={"sessionvariables.cred.mcp.weatherReportMCP.bearer": "valid-123"}
            )
            request = SendMessageRequest(
                id=str(uuid.uuid4()),  # Add the required id field
                params=MessageSendParams(
                    message=message,
                    configuration=MessageSendConfiguration(acceptedOutputModes=["text/plain", "text"]),
                ),
            )
            #json_string = json.dumps(message, indent=4)
            print(f"Send request : {request}")

            response = await client.send_message(request)

            logging.info("Received response from A2A server: %s", response.root.result)
            # Extract response
            result = response.root.result
            # Handle different response types


            if isinstance(result, Task):
                # Task response
                if result.artifacts:
                    # Extract text from artifacts
                    texts = []
                    for artifact in result.artifacts:
                        for part in artifact.parts:
                            if hasattr(part, "root") and hasattr(part.root, "text"):
                                texts.append(part.root.text)
                    return "\n".join(texts) if texts else "Task completed with no text response"
                elif result.status and result.status.message:
                    logging.info(f"Received Task status {result.status.state} from A2A server and status message is {result.status.message}", result.status.message)
                    if  result.status.state== "failed":
                        print("Failure observed in Task invocation")
                        for m_part in result.status.message.parts:
                           print(f"Error message  { m_part.root.text}")

                    return get_message_text(result.status.message)
                else:
                    return f"Task {result.id} status: {result.status.state if result.status else 'unknown'}"

            elif isinstance(result, Message):
                return get_message_text(result)
            else:
                logging.warning(f"Unexpected response type: {type(result)}")
                return "Received response but unable to extract text"
    except Exception as ex:
        logging.error(f"Error calling agent at {agent_url}: {ex}", exc_info=True)
        return f"Error communicating with agent: {str(ex)}"


async def _call_agent_with_a2a_with_stream(agent_url: str, query: str, context_id: str, auth: OCIAuth) -> str:
    """Call an agent using the A2A protocol with streaming (SSE) and return the final artifact text."""
    try:
        async with httpx.AsyncClient(timeout=60.0, auth=auth) as hc:
            agent_card = await _get_agent_card(agent_url)
            if not agent_card:
                return "No Agent Card Found"
            print(f"Agent card is {agent_card}")

            client = A2AClient(httpx_client=hc, agent_card=agent_card)
            message = Message(
                message_id=str(uuid.uuid4()),
                context_id=context_id,
                role=Role.user,
                parts=[Part(root=TextPart(text=query))],
            )
            request = SendStreamingMessageRequest(
                id=str(uuid.uuid4()),
                params=MessageSendParams(
                    message=message,
                    configuration=MessageSendConfiguration(acceptedOutputModes=["text/plain", "text"]),
                ),
            )
            print("Invoking Remote Agent request (beautified JSON):")
            print(json.dumps(request.model_dump(), indent=2, ensure_ascii=False))
            # Expected event types:
            # - TaskStatusUpdateEvent (working/in-progress)
            # - TaskArtifactUpdateEvent (contains Artifact.parts[].root.text) -> final output
            final_artifact_text_parts: list[str] = []

            async for event in client.send_message_streaming(request):
                # Print each SSE event as-is (SDK object)
                print(f"[A2A stream event] {event}")

                try:
                    result = getattr(event.root, "result", None)
                    if not result:
                        continue

                    # TaskArtifactUpdateEvent and TaskStatusUpdateEvent are SDK types; to avoid tight coupling,
                    # extract by attribute presence.
                    artifact = getattr(result, "artifact", None)
                    if artifact and getattr(artifact, "parts", None):
                        for part in artifact.parts:
                            root = getattr(part, "root", None)
                            txt = getattr(root, "text", None)
                            if txt:
                                final_artifact_text_parts.append(txt)
                except Exception:
                    # Keep streaming even if an event can't be parsed
                    continue

            return "\n".join([t for t in final_artifact_text_parts if t]).strip() or "Stream completed (no artifact text)."
    except Exception as ex:
        logging.error(f"Error calling agent at {agent_url}: {ex}", exc_info=True)
        return f"Error communicating with agent: {str(ex)}"

Editar um Rascunho de Cartão de Agente

Você pode editar o cartão de agente para um agente que ainda não foi implantado.

Navegue até o seu agente.
Clique em Ações e, em seguida, clique em Exibir cartão do agente e Cartão do agente preliminar.
Clique emEditar.
Você pode alternar a exibição clicando em Formulário ou JSON no canto superior direito. A view JSON é mais completa, mas somente leitura. Você só pode editar campos na exibição Formulário.
Modifique os campos conforme necessário.
Clique em Adicionar uma habilidade para adicionar as habilidades que você deseja expor aos clientes A2A.
Clique em Salvar.

Editar um Cartão de Agente Publicado

Você pode modificar um cartão de agente publicado sem ter que cancelar a implantação ou reimplantar um agente.

O cartão publicado corresponde a um snapshot do cartão de rascunho no momento da implantação.

Observação:

As alterações feitas em um cartão publicado são imediatamente refletidas no arquivo agent-card.json acessível aos clientes A2A.

Navegue até o seu agente.
Clique em Ações e, em seguida, clique em Exibir cartão do agente e Cartão do agente publicado.
Você pode alternar a exibição clicando em Formulário ou JSON no canto superior direito. A view JSON é mais completa, mas somente leitura. Você só pode editar campos na exibição Formulário.
Clique emEditar.
Modifique os campos conforme necessário.
Clique em Adicionar uma habilidade para adicionar as habilidades que você deseja expor aos clientes A2A.
Clique em Publicar alterações.

Cartões de agente publicados não estão disponíveis publicamente. Um usuário precisa ser autenticado e ter a permissão certa (READ) para inspecionar o conteúdo do agent-card.json. Outros agentes podem descobrir seus recursos e metadados de agentes por meio de uma solicitação HTTP GET no caminho padrão:

https://gateway.aidp.{oci-region}.oci.oraclecloud.com/agentendpoint/{agentId}/a2a/agent-card.json

Implantação do Agente

A implantação de um agente transforma seu agente em um aplicativo hospedado.

Você pode implantar um agente na mesma computação de IA anexada ao playground ou a outra computação de IA. Quando você implanta as alterações mais recentes no seu agente na computação de IA anexada, o agente implantado representa um snapshot do agente no momento da implantação. Para atualizar o agente implantado para a versão mais recente, você precisa reimplantar o agente.

Cada agente tem um URL de implantação estável que depende da chave de agente exclusiva. A reimplantação do agente várias vezes substitui o agente por trás do URL de implantação.

A implantação de seus agentes tem as seguintes limitações:

Um agente só pode ser implantado em um cluster de computação de IA a qualquer momento.
A implantação do mesmo agente várias vezes no mesmo cluster de computação AI substitui a iteração implantada anteriormente do agente.

Depois de implantar um agente, você poderá recuperar o URI do chat para emitir consultas de forma programática e recuperar respostas do agente na guia Detalhes do seu agente.

A página Agente é aberta com a guia Detalhes aberta e destacada. Implantado no AI Compute e no URL do Ponto Final estão destacados

O URL do ponto final é estável e está vinculado a cada agente. O URL inclui o agentID exclusivo designado a cada agente. Em outras palavras, se você cancelar a implantação de um agente e implantá-lo novamente, o URL permanecerá o mesmo. O benefício é que você não precisa modificar o código do cliente que está chamando o ponto final. A desvantagem é que você pode substituir um agente na produção.

O URL tem a seguinte estrutura:

https://gateway.aidp.{oci-region}.oci.oraclecloud.com/agentendpoint/{agentId}/{protocol}

em que:

oci-region corresponde à região da instância da AI Data Platform;
agentId é o id exclusivo associado ao agente
protocol é o protocolo de comunicação: chat que segue o formato da API de Respostas do OpenAI e a2a que segue o protocolo de comunicação entre agentes. Ambos os protocolos estão disponíveis para cada ponto final do agente. Para obter mais informações, consulte Implantação do Agente A2A.

Observação:

Dois cálculos de IA são listados na guia Detalhes. O Anexado ao AI Compute é usado para testar o agente no playground. O serviço Implantado no AI Compute hospeda o agente implantado.

O campo URL do ponto final é preenchido depois que você implanta seu agente. Você pode chamar esse URL de ponto final do seu aplicativo de produção.

Implantar um Agente

Você implanta agentes que criou e configurou para que outros usuários possam vê-los e usá-los em sua instância da AI Data Platform.

Na Home page, navegue até a pasta que contém o agente que você deseja implantar.
Ao lado do agente, clique em Ações e clique em Implantar. Você também pode clicar no nome do agente e clicar em Implantar no canto superior direito.
Selecione a computação AI a ser anexada ao agente implantado.
Selecione Bancada AIDP para o tipo de autorização.
Selecione uma política de retenção de dados da sessão.
- Para Período de retenção, forneça o número de dias durante os quais os dados da sessão são retidos.
- Para Limite de tamanho de sessão, forneça o tamanho máximo que uma sessão pode atingir.
- Para Limite de contagem de threads, forneça o número máximo de threads de sessão retidos.
Clique em Disponibilizar.

Implantar um Agente com o OAuth2

Você pode implantar agentes que criou e configurou para usar a autenticação OAuth2 para estabelecer conexão com provedores de identidades externos.

Na Home page, navegue até a pasta que contém o agente que você deseja implantar.
Ao lado do agente, clique em Ações e clique em Implantar. Você também pode clicar no nome do agente e clicar em Implantar no canto superior direito.
Selecione a computação AI a ser anexada ao agente implantado.
Selecione OAuth2 para o tipo de autorização.
Forneça a reivindicação do público. O AI Data Platform Workbench preenche automaticamente esse campo, mas você pode substituí-lo por uma reivindicação de público do seu provedor de Identidade.
Forneça a reivindicação do emissor e o URI para recuperar JWKS. Essas informações são derivadas do seu provedor de Identidades.
Selecione uma política de retenção de dados da sessão.
Clique em Disponibilizar.

Chamar um Agente Implantado

Você pode chamar o URL do ponto final do seu agente no seu aplicativo de produção.

Independentemente da interface programática usada para chamar o ponto final do agente, você deve ser autenticado com o OCI e ter as permissões relevantes. No caso de pontos finais do Fluxo do Agente, o chamador precisa ter pelo menos a permissão USE no ponto final do agente.

O URI do ponto final é documentado na guia de detalhes da IU do agente. Você pode copiar esse URI de ponto final em seu código para chamar o agente.

Página de detalhes de um agente aberto com o campo URI do Ponto Final destacado

Métodos para Chamar URIs de Ponto Final

Você pode chamar o URI do ponto final do agente por meio de diferentes ferramentas, SDKs e CLIs.

Os métodos a seguir permitem que você chame o URI do ponto final nos agentes do Oracle AI Data Platform Workbench.

Chamar com a CLI do OCI

O exemplo fornecido demonstra como você usa a CLI do OCI e se autentica com um token de segurança. Substitua <your-agent-flow-endpoint-uri> pelo URI do ponto final do agente e <security_token> pelo seu token de segurança do OCI.

oci raw-request
--http-method POST
--target-uri <your-agent-flow-endpoint-uri>
--request-body '{"query":"Tell me about the Ryder Cup in 1985"}'
--auth <security_token>

Chamar com a Biblioteca de Solicitações Python

Você pode usar o OCI Python SDK para criar um signatário para autenticação com o OCI. A biblioteca de solicitações Python pode ser usada para postar uma solicitação no URI do ponto final do agente e retornar uma resposta. O exemplo a seguir demonstra como você pode usar seu principal de usuário por meio dos arquivos de configuração e chave privada do OCI:

import oci import requests import json import uuid from contextlib import closing from requests import Request, Response
class AuthHelper: """ AuthHelper allows creating an OCI signer with either API key or security_token (which are short term sessions) """ def init(self, oci_profile: str, use_security_token:bool = True): config = oci.config.from_file(file_location="/Volumes/jr/default/misc/config",profile_name=oci_profile) if use_security_token: with open(config["security_token_file"], 'r') as f: token = f.read() private_key = oci.signer.load_private_key_from_file(config["key_file"])
 self.signer = oci.auth.signers.SecurityTokenSigner(token, private_key) else: self.signer = oci.signer.Signer( tenancy=config["tenancy"], user=config["user"], fingerprint=config["fingerprint"], private_key_file_location=config["key_file"], #pass_phrase=config.get("pass_phrase"), #private_key_content=config.get("key_content") )
@property
def Signer(self):
    return self.signer
 
class MyRawJsonRpcClient: """ Simple class using requests lib to post JSON to chat endpoint using OCI signing """ def init(self, chat_url:str, oci_profile: str, sessionKey:str, use_security_token:bool = True): self.authhelper = AuthHelper(oci_profile=oci_profile, use_security_token=use_security_token) self.authsigner = self.authhelper.Signer self.chat_url = chat_url self.sessionKey = sessionKey
def send(self, input:str) -> Response:
    body = {
        "isStreamEnabled" : False,
        "sessionKey" : self.sessionKey,
        "trace" : False,
        "input" :[{
            "role":"User",
            "content":[{
                "type" : "INPUT_TEXT",
                "text" : input                   
            }]
        }]
    }

    response:Request = requests.post(
        url =self.chat_url,
        params = None,
        auth = self.authsigner,
        json=body,
        headers={}
    )
    return response

Você pode chamar o URI do ponto final do agente instanciando a classe MyRawJsonRPCClient e fornecendo um valor de perfil do OCI (encontrado no arquivo de configuração do OCI), o URI do ponto final do agente (chat_url) e uma sessionKey. Você pode fornecer qualquer sessionKey arbitrário. sessionKey é o identificador exclusivo da sessão do usuário com o agente. Se você continuar reutilizando o mesmo sessionKey, as mensagens do usuário e as respostas do agente serão anexadas à mesma conservação.

client = MyRawJsonRpcClient(chat_url="<your-agent-flow-endpoint-uri>",
   oci_profile = "DEFAULT",
   sessionKey= “<your-session-key>”,
   use_security_token = False )

Você também pode fornecer uma mensagem do usuário e usar o cliente para enviar a mensagem ao URI do ponto final do agente:

user_input = f"Hello, tell me a good dad joke."
r = client.send(input = user_input)
response_json = r.json()

Por meio do APEX

Você pode usar a amostra de código disponível no repositório Github de Amostras do AI Data Platform Workbench. A amostra orienta você pelo processo de chamar um ponto final de implantação do agente em um aplicativo APEX.

Por Streamlit

Você pode usar a amostra de código disponível no repositório Github de Amostras do AI Data Platform Workbench. A amostra orienta você pelo processo de chamar um ponto final de implantação do agente em um aplicativo Streamlit.

Melhores Práticas - Respostas Assíncronas e Não Assíncronas

Recomendamos que você escreva seu código de cliente assumindo respostas assíncronas. Por exemplo:

import httpx 
 
async def fetch_data(): 
    async with httpx.AsyncClient() as client: 
        response = await client.get(URL) 
        return response.json()

Cancelar Implantação de um Agente

Você pode optar por cancelar a implantação dos agentes para os quais tem permissões de GERENCIAMENTO, tornando-os indisponíveis para uso.

Na Home page, navegue até a pasta que contém o agente que você deseja cancelar a implantação.
Ao lado do agente, clique em Ações e clique em Cancelar Implantação.
Clique em Cancelar disponibilização.

Monitorar Agentes

Você pode monitorar detalhes relacionados às sessões e métricas de seus agentes para ver informações sobre como elas estão sendo usadas, os recursos que elas consomem e muito mais.

Você tem várias guias no agente para rastrear detalhes de uso, a guia Sessões, a guia Métricas e a guia Atividade. Você pode encontrá-los na parte superior da tela do agente.

Rastreamentos e Intervalos

Os rastreamentos fornecem observabilidade para seus agentes, capturando e exibindo o fluxo de solicitações do agente. Spans são os objetos que compõem um traço. Cada intervalo é uma etapa diferente no fluxo, como prompts de chat de um usuário, chamadas de agente e tarefas de workflow.

Você pode ver rastreamentos para a sessão atual, execução de teste ou sessões anteriores. Para ver o rastreamento da sessão atual, vá para a guia Fluxo e clique em Playground. O painel Detalhes na parte inferior da página exibe o rastreamento da sessão atual no painel esquerdo. Você pode clicar em objetos no rastreamento para expandi-los ou visualizar informações mais detalhadas. No painel direito, você pode clicar nas guias Informações, Detalhes ou Eventos para saber mais sobre o objeto de intervalo selecionado.

Você pode ver rastreamentos de sessões anteriores na guia Sessões clicando no nome da sessão.

Sessões

Na guia Sessões, você pode ver um histórico de sessões desse agente. Você pode ver se cada sessão foi bem-sucedida ou falhou, a origem do URI, quando a sessão foi iniciada, a duração da sessão e os tokens usados na sessão. Você pode clicar em ID da sessão para obter detalhes mais específicos sobre essa sessão e ver rastreamentos para essas sessões específicas.

Você pode filtrar as sessões exibidas usando a barra de pesquisa para filtrar por ID da sessão ou origem do URI, usando os filtros de data para mostrar apenas um intervalo de datas específico e o menu suspenso Status da sessão para filtrar se uma sessão foi bem-sucedida ou falhou.

Métricas

A guia Métricas mostra um resumo dos dados de uso de todas as sessões do agente. A lista suspensa Intervalo de datas filtra o período que você deseja ver resumido nos cartões exibidos. A seleção de URI filtra a origem de seleção de URI cujos detalhes você deseja ver. É possível modificar quais cartões são exibidos e se eles incluem ou não gráficos como representações visuais de uso.

Atividade

A guia Atividade mostra um resumo do status de implantação do agente. A coluna Operação especifica o tipo de operação de implantação (Implantar ou Cancelar Implantação) e a coluna Status especifica o resultado da operação (Sucesso, Erro, Advertência, Falha). Você pode ver quem iniciou a operação e quando, bem como a mensagem de status associada ao resultado da operação.

Exibir Sessões do Agente

Você pode exibir um histórico de sessões para seu agente e filtrar os resultados para ver tendências e ajudar na solução de problemas.

Na página inicial, navegue até o agente.
Clique na guia Sessões.
Use os filtros para alterar as sessões exibidas.

Exibir Métricas do Agente

Você pode exibir detalhes resumidos do agente usado, como uso de token, durações de sessão, latência e muito mais.

Na página inicial, navegue até o agente.
Clique na guia Métricas.
Selecione diferentes opções na lista drop-down Intervalo de datas para ver como a métrica difere entre as linhas de tempo.
Selecione diferentes opções na lista drop-down seleção de URI para filtrar origens de URI específicas.

Mover um Agente

Você pode mover agentes de sua propriedade ou ter permissões MANAGE.

Na Home page, navegue até a pasta que contém o agente que você deseja mover.
Ao lado do agente que você deseja modificar, clique em Ações e clique em Mover .
Selecione o novo local do espaço de trabalho para o agente. Clique em Mover.

Copiar um Agente

Você pode copiar um agente de sua propriedade ou ter permissões de GERENCIAMENTO para outro local em um espaço de trabalho disponível.

Você pode copiar agentes para a mesma pasta ou para uma pasta diferente. Os fluxos do agente podem ser copiados para pastas em diferentes espaços de trabalho aos quais você tem acesso. A configuração do agente, bem como as configurações da ferramenta e do corrimão, são copiadas. Os anexos do cluster de computação de IA não são copiados e você precisa anexar o agente a um novo cluster de computação de IA para retomar o desenvolvimento.

Na Home page, navegue até a pasta que contém o agente que você deseja mover.
Ao lado do agente que você deseja modificar, clique em Ações e clique em Copiar para espaço de trabalho.
Forneça um novo nome e uma descrição para o agente copiado, se necessário.
Clique em Procurar e selecione um novo local no espaço de trabalho para o qual copiar o agente. Clique em Selecionar.
Clique em Copiar.

Fazer Download dos Arquivos do Agente

Você pode fazer download de arquivos do agente e de seus arquivos de guardrail que contêm as definições desse agente.

Os arquivos do agente são arquivos JSON com a extensão de arquivo AFLOW e contêm as definições do seu agente. Os arquivos de corrimões são rotulados como _guardrails.JSON e contêm as definições de corrimão para o agente.

Navegue até a pasta do agente em seu espaço de trabalho.
Clique no nome do agente que deseja fazer download.
Ao lado do arquivo AFLOW do agente, clique em Ações e, em seguida, clique em Fazer Download. O arquivo é baixado para sua máquina local.
Ao lado do arquivo _guardrails.JSON, clique em Ações e depois clique em Fazer Download. O arquivo é baixado para sua máquina local.

22 Agentes de IA

Padrões de Sistemas e Supervisor de Vários Agentes

Sobre o Visual Flow Canvas

Criar um Agente

Adicionar Trigger de Chat e Agente à Tela do Visual Builder

Configurar um Agente Supervisor

Instruções de Supervisor Sugeridas

Configurar Memória do Agente Supervisor e Isolamento de Estado

Guia Parâmetro de Modelos

Adicionar Guardrails a um Agente

Adicionar Agentes e Ferramentas do Executor a um Agente

Configuração do Agente do Executor

Lista de Verificação para Agentes por meio do Visual Builder

Fluxo do Agente Através do Código

Criar um Agente Através do Código por Upload

Criar um Agente Através do Código Criando um Novo Código

Definir um Arquivo de Entrada para Agentes por meio de Código

Definir um Arquivo de Dependência para Agentes por meio de Código

Código do Agente de Teste

Habilidades do agente na experiência de codificação

Adicionar uma Nova Habilidade

Adicionar um Novo Recurso Executável a uma Habilidade Existente

Diagnóstico e Solução de Problemas de Habilidades do Agente

Exemplo: Concluir Habilidade do Agente

Teste do Agente

Teste seus Agentes no Playground

Criar uma Sessão de Teste do Agente

Retomar uma Sessão de Teste do Agente

Excluir uma Sessão de Teste do Agente

Sobre Ferramentas do Agente

Ferramenta de Build

Adicionar uma Ferramenta Personalizada a um Agente

Ferramenta remota do servidor MCP

Conectar um Agente a um Servidor MCP Remoto no Visual Builder

Ferramenta de solicitação HTTP

Adicionar uma Ferramenta de Solicitação HTTP a um Fluxo de Agente

Ferramenta de Prompt

Adicionar uma ferramenta de prompt a um agente

Ferramenta RAG

Adicionar uma Ferramenta RAG a um Agente

Ferramenta SQL

Adicionar uma Ferramenta SQL a um Agente

Memória do Agente

Variáveis de Sessão

Criar uma Variável de Sessão na Guia Variáveis do Agente

Consulte Variáveis de Sessão nas Instruções de Fluxo do Agente

Exibir Agentes e Ferramentas usando uma Variável de Sessão

Atribuir Valores a Variáveis de Sessão do Playground

Guardrails de proteção

Ativar Guardrails Específicos em um Nó

Criar um Cluster de IA para um Agente

Anexar um Cluster de IA Existente a um Agente

Desanexar um Agente do AI Compute

Implantação do Agente A2A

Editar um Rascunho de Cartão de Agente

Editar um Cartão de Agente Publicado

Implantação do Agente

Implantar um Agente

Implantar um Agente com o OAuth2

Chamar um Agente Implantado

Métodos para Chamar URIs de Ponto Final

Cancelar Implantação de um Agente

Monitorar Agentes

Exibir Sessões do Agente

Exibir Métricas do Agente

Mover um Agente

Copiar um Agente

Fazer Download dos Arquivos do Agente