18 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 Workbench da AI Data Platform 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 Workbench da AI Data Platform 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 catálogos externos, como Oracle Autonomous AI Lakehouse, Oracle Autonomous AI Transaction Processing ou Oracle Autonomous 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.
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 do Agente por meio do Código LangGraph
Você adiciona ferramentas aos seus 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)
- 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,RAGTool,HTTPTooleMCPTool. - 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.
- 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 responsetool_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.
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 norequirements.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 coloquepackage_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.
Observação:
Se sua ferramenta depender de pacotes de terceiros declarados emrequirements.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.- 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.
- 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:
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.
À 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.
No exemplo abaixo, adicionamos duas ferramentas (read_wiki_structure, read_wiki_structure). Você pode remover ferramentas clicando em Remover.
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.
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:
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.
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={}
)- <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_AUTHouBEARER_TOKEN. No caso deBEARER_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.
Selecione uma das ferramentas que você adicionou na guia Ferramentas, forneça valores de parâmetros e clique no botão Testar.
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.
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:
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.
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.
- • 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}}.
https://objectstorage.{{sessionVariables.region}}.oraclecloud.com/n/my-namespace/b/{{bucket}}/oQuando 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.
- 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 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.- Nos modelos de Ferramenta, arraste e solte uma ferramenta de Solicitação HTTP na tela.
- 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
- 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.
- 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 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 18-1 Propriedades de Configuração da Ferramenta de Prompt
| Property | Tipo | Descrição |
|---|---|---|
| llm | objeto | Detalhes e parâmetros da conexão LLM |
| model_id | 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.
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 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.
- 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:
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 18-2 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 do agente 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.
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.
SELECT customer_name, region, amount, category
FROM test_customers
WHERE period_year = 2025
ORDER BY customer_name {{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.
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.
Observação:
Nomes de marcador fazem distinção entre maiúsculas e 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
{
"catalogKey": "construction_data",
"schemaKey": "admin",
"query": "SELECT project_id, project_name, client_name, ...",
"isRowLimitEnabled": null,
"maxRows": null
}
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.
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.
O guia mostra diferentes padrões de consulta e fornece diferentes recomendações sobre parâmetros de consulta.
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 18-3 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 agente completo. 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:
Spark SQL e Delta Lake (Catálogo Padrão)
- 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.
- Clique e arraste a alça do conector no agente para estabelecer conexão com o nó da 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.
- 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.