18 Acerca de las Herramientas de Agente

El área de trabajo de Oracle AI Data Platform soporta plantillas de herramientas que se pueden configurar para acceder a los datos y adaptarse a los casos de uso.

Los agentes soportan configuraciones que constan de un único agente que puede interactuar con una o más herramientas. El área de trabajo de AI Data Platform ofrece tres plantillas de herramientas que se pueden configurar para su uso a través de flujos visuales o código:

• Código personalizado: la herramienta Código personalizado permite a los desarrolladores de IA implementar su herramienta con Python. Los desarrolladores empaquetan su herramienta en un ZIP, la cargan en su espacio de trabajo y la configuran como un nodo en su agente. Las herramientas de código personalizado están pensadas para casos en los que las herramientas incorporadas no proporcionan la integración que necesitan.
• Solicitud HTTP: las herramientas de solicitud HTTP permiten a los desarrolladores utilizar llamadas de API de REST soportadas en sus agentes, aprovechando las API del área de trabajo de AI Data Platform y las funciones que proporcionan. Los agentes pueden utilizar las API de REST para crear objetos de espacio de trabajo, comprobar detalles, extraer listas o modificar objetos existentes. Para obtener una lista completa de las API disponibles, consulte API de REST para el área de trabajo de plataforma de datos de Oracle AI.
• Petición de datos: la herramienta de petición de datos permite al desarrollador de IA definir una petición de datos parametrizada que se puede emitir a un LLM para su elección. Los casos de uso comunes para una herramienta de petición de datos incluyen tareas de redacción de correo electrónico, tareas de traducción, conversión de estilo, mensaje de confirmación de git y explicaciones de código.
• RAG: la herramienta RAG permite a los agentes extraer los conocimientos externos relevantes antes de generar una respuesta. En AI Data Platform Workbench, la herramienta RAG consulta una base de conocimientos (26ai Vector Search) y recupera fragmentos de documentos semánticamente relevantes. Estos fragmentos se transfieren al agente para la generación de respuestas.
• SQL: la herramienta SQL permite a los agentes ejecutar consultas SQL en orígenes de datos estructurados registrados a través de catálogos externos, como Oracle Autonomous AI Lakehouse, Oracle Autonomous AI Transaction Processing u Oracle Autonomous AI Database. La herramienta está diseñada para escenarios en los que las consultas SQL están predefinidas y se pueden parametrizar. El objetivo es permitir que un agente asigne valores a los parámetros. Esta herramienta no es una herramienta NL2SQL que genera una consulta SQL basada en una petición de datos en lenguaje natural.

  Note:

  La herramienta SQL solo realiza consultas en los datos de un catálogo externo. No soporta los datos almacenados en un catálogo estándar.

Herramientas de flujo de agente mediante flujo visual

Cuando agrega herramientas a los agentes a través del flujo visual, puede encontrar herramientas en Plantillas de herramientas en el agente. Para agregar una herramienta al agente, arrástrela y suéltela en el lienzo de flujo visual. Después de arrastrar el nodo de herramienta en el lienzo, el nodo se conecta automáticamente con el agente.

Cada herramienta se puede configurar en el separador Parámetros y probarse independientemente del agente haciendo clic en el separador Test.

Note:

Debe asociar un AI Compute a su agente antes de poder probar una herramienta del sistema. Si no hay ningún recurso informático asociado, el separador Test está desactivado.

Herramientas de agente mediante LangGraph Code

Agregue herramientas a los agentes codificados de LangGraph a través de una instancia de la clase AIDPToolConf().

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

Los parámetros reflejan la experiencia de flujo visual de las herramientas. Para cada herramienta, debe proporcionar:

• Nombre: nombre descriptivo que ayuda a los usuarios y al LLM a comprender el objetivo de la herramienta.
• Descripción: resumen exhaustivo que proporciona información suficiente para que los usuarios y los LLM comprendan lo que hace la herramienta.
• tool_class: tipo de herramienta admitida, PromptTool, SQLTool, RAGTool, HTTPTool y MCPTool.
• conf: configuración de la herramienta. Esta información está oculta para el LLM.
• params: los parámetros expuestos al LLM.

Herramienta personalizada

La herramienta Custom Code permite a los desarrolladores de agentes ampliar AI Data Platform con su propio código Python.

La implementación de la herramienta se empaqueta como un archivo ZIP, se carga en el espacio de trabajo y se configura como un nodo de herramienta de código personalizado en el agente. El agente llama al código como una herramienta, con parámetros proporcionados por el LLM en tiempo de ejecución.

La herramienta Código personalizado está diseñada para los casos en los que las herramientas incorporadas (HTTP, SQL, RAG, MCP) no cubren la integración que necesita, por ejemplo, cuando necesita realizar cálculos locales, analizar un formato específico del dominio o componer varios pasos que deben aparecer para el agente como una sola llamada de herramienta.

AI Data Platform Workbench tiene los siguientes límites al cargar un archivo ZIP con código Python para su herramienta de código personalizado:

Restricción	Límite
Tamaño máximo del ZIP	10 MB
Tamaño máximo de archivo dentro del ZIP	10 MB por archivo
Tamaño máximo total sin comprimir	500 MB
Recorrido por ruta	Bloqueado (../ rechazado)

Note:

Las herramientas de código personalizadas se ejecutan en el recurso informático AI asociado a su agente. El código tiene acceso al entorno informático y al acceso de red saliente sujeto a la configuración de red del espacio de trabajo. Solo carga código de fuentes de confianza.

Parámetros de Herramienta de códigos personalizada

En la ficha Parámetros, configure los valores estáticos para cada clase de herramienta del paquete. La lista desplegable Clase de herramienta le permite cambiar entre las herramientas detectadas en el paquete.

La ficha Parámetros de la herramienta de código personalizada incluye las siguientes secciones:

• Clase de herramienta: seleccione la clase de herramienta que desea configurar. La lista desplegable se rellena desde las clases registradas en tool_implementation.py.
• Descripción: descripción clara y concisa de lo que hace la herramienta. La descripción se proporciona al agente y ayuda al LLM a decidir cuándo llamar a la herramienta. La descripción por defecto se lee desde tool_config.json y se puede sustituir aquí.
• Configuración: configuración estática que necesita la herramienta en tiempo de ejecución. Estas son las claves definidas en el objeto conf de tool_config.json. Los ejemplos incluyen timeout, base_dir, max_output_lines y referencias de credenciales. Los valores de configuración soportan las referencias de parámetros de tiempo de ejecución {{variable}}. Las variables de sesión no se sustituyen actualmente en la configuración de la herramienta personalizada; si necesita un valor de sesión, transfiéralo como parámetro de tiempo de ejecución del agente.
• Definición de herramienta AI: esquema expuesto al agente, incluido el nombre de la herramienta, la descripción y los parámetros de tiempo de ejecución que puede transferir el agente. El esquema se presenta automáticamente desde la matriz de esquemas en tool_config.json.

Creación de Herramienta de códigos personalizada

Un paquete de herramientas de código personalizado es un archivo ZIP con la siguiente estructura:

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 clase de herramienta amplía CustomToolBase y está decorada con @BaseTool.register. La clase debe implementar el método de clase _execute_tool, que recibe la configuración de la herramienta, los parámetros de tiempo de ejecución del agente y las variables de contexto del sistema, y devuelve un valor, como dict, str o list.

A continuación se muestra una plantilla de ejemplo en blanco de 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

El archivo tool_config.json describe las herramientas del paquete: su nombre mostrado, descripción, versión, esquema de parámetros de tiempo de ejecución y valores de configuración por defecto. Cada herramienta registrada en tool_implementation.py debe tener una entrada correspondiente en la matriz de herramientas.

A continuación se muestra una plantilla de ejemplo en blanco de 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 campos de esquema

El separador Parámetros del creador visual acepta cadena, número y booleano. El tiempo de ejecución acepta un juego más amplio al crear tool_config.json manualmente: int, integer, float, double, number, numeric, bytes, list, array, sequence, dict, map, mapping, set, tuple, none, null, además de formularios genéricos como list[int]. Estos tipos más amplios se pueden utilizar desde JSON, pero no se muestran en la lista desplegable de la interfaz de usuario.

requirements.txt

El archivo requirements.txt muestra las dependencias de Python que necesita la herramienta. Se admite la sintaxis de pip estándar, incluidos los especificadores de versión y los comentarios. El archivo es opcional: si la herramienta solo utiliza la biblioteca estándar de Python o los paquetes preinstalados, no necesita requirements.txt.

A continuación se muestra un ejemplo en blanco de requirements.txt:

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

AI Data Platform Workbench filtra las dependencias en requirements.txt antes de instalarlas en los recursos informáticos de IA, para evitar conflictos de tiempo de ejecución con la propia plataforma. Las reglas de filtrado son las siguientes:

Categoría	Ejemplo	Acción
Paquetes de plataformas	langgraph, langchain-core, langchain-oci, langchain_mcp_adapters, pyyaml	Desechado (debería interrumpir el tiempo de ejecución del agente).
Paquetes preinstalados	oci, requests-toolbelt, websockets, criptografía, certifici, pyopenssl, urllib3, pydantic, pydantic-core, pydantic-settings, numpy, oracledb, sqlalchemy, aiohttp, httpx, httpx-sse, anyio, jsonschema, orjson	Omitido (ya disponible, no es necesario declarar).
Instalaciones de URL o VCS	git+https://..., -e ./local_pkg	Bloqueado (seguridad).
Todo lo contrario	humanizar, hermosa sopa4, jmespath	Instalado.

Note:

Las dependencias declaradas en requirements.txt se instalan durante el despliegue completo del agente. Las dependencias no se instalan durante una única ejecución de prueba desde el panel de configuración. Si la herramienta depende de paquetes de terceros, despliegue primero el agente y, a continuación, ejerza la herramienta desde Playground.

Para las herramientas que necesitan dependencias que no están preinstaladas y en las que la instalación fuera de línea determinista es importante, puede agrupar archivos .whl dentro de un directorio de ruedas/en la raíz del ZIP. La plataforma se instala desde el directorio de ruedas local en primer lugar y vuelve al índice de paquetes solo si es necesario. Este es el enfoque recomendado para las herramientas de producción.

Ruedas de agrupación para instalación fuera de línea

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

Ganchos del ciclo de vida de la herramienta

Las herramientas de código personalizadas admiten tres métodos de ciclo de vida. Solo se requiere _execute_tool.

Método	Cuando se llama	Finalidad
_validar_config	Antes de _execute_tool	Valida la configuración. Emita ValueError para abortar la llamada antes de que se ejecute.
_ejecución_herramienta	En cada llamada a la herramienta	Es obligatorio. Implementa el comportamiento de la herramienta. Devuelve cualquier valor (dict, str, list) y genera una excepción para indicar un fallo (ValueError → INVALID_CONFIG, cualquier otra excepción → TOOL_EXECUTION_ERROR). No utilice un {"error" devuelto": "..."} dict, ya que se trata como una carga útil normal.
_transform_response	Después de _execute_tool	Transforme la respuesta antes de que se ajuste en formato MCP y se devuelva al agente.
prompt_template	Cadena	Plantilla de petición de datos utilizada por el LLM, con variables en formato {{variable}} para inserción dinámica

Valores de configuración frente a parámetros de tiempo de ejecución

Las herramientas de código personalizado tienen dos fuentes de entrada distintas que son fáciles de confundir. Los valores de configuración proceden de la sección Configuration del separador Parameters y se incluyen en la herramienta cuando se despliega el agente. Los parámetros de tiempo de ejecución provienen del agente en el momento de la llamada y son diferentes en cada llamada.

• Se accede a los valores de configuración mediante conf.get("conf", conf). Utilícelos para cosas que no cambian entre llamadas: URL base, referencias de credenciales, timeouts, límites de salida.
• Se accede a los parámetros de tiempo de ejecución a través de runtime_params.get("name"). Utilícelos para los valores que el agente realmente decide en el momento de la llamada: la consulta, la ruta de archivo, el cuerpo de la solicitud.

Note:

Los valores de configuración pueden pasar por la sustitución de plantillas y pueden llegar como cadenas incluso cuando los ha definido como números. Coaccione siempre los valores de configuración numéricos de forma defensiva, por ejemplo: int(tool_conf.get("timeout", 30)).

Varias herramientas por paquete

Un solo ZIP puede contener varias clases de herramientas. Cada clase registrada con @CustomToolBase.register se convierte en una herramienta independiente en el agente. El panel Herramientas de la ficha Paquete muestra todas las herramientas detectadas y permite activar cada una de ellas de forma independiente. Cada herramienta se configura por separado en el separador Parámetros mediante el menú desplegable Clase de herramienta.

Herramienta de código mediante LangGraph Code

Desde el creador de código, una herramienta de código personalizado se registra a través de la biblioteca Python de helppUtils haciendo referencia al paquete cargado y seleccionando una de sus clases de herramientas.

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 debe ser el nombre de clase exacto registrado a través de @BaseTool.register en tool_implementation.py. El marco busca la clase en BaseTool.tool_class_registry[tool_class]. conf refleja el objeto conf de la entrada coincidente en tool_config.json.

Note:

No coloque package_path o tool_class_name dentro de conf, ya que no se consumen.

Herramientas de código personalizado de agente de prueba

El separador Prueba permite ejecutar la herramienta sin ejecutar el agente completo. Proporcione valores para cualquier parámetro de tiempo de ejecución y cualquier variable de sesión a la que se haga referencia en la configuración y, a continuación, haga clic en Run para llamar a la herramienta y ver la respuesta.

Note:

Si la herramienta depende de paquetes de terceros declarados en requirements.txt, las dependencias se instalan durante el despliegue completo del agente, no durante una única ejecución de prueba. Para probar el código que depende de paquetes adicionales, despliegue primero el agente y, a continuación, llame a la herramienta desde Playground.

Adición de una herramienta personalizada a un agente

Puede agregar una herramienta personalizada a sus agentes para permitirle utilizar su propio código Python para ampliar AI Data Platform.

Note:

Se debe asociar un recurso informático de IA a su agente antes de agregar una herramienta de código personalizada. Los recursos informáticos de AI son necesarios para instalar dependencias y ejecutar la herramienta.

1. Vaya a su agente.
2. En las plantillas de herramientas, arrastre y suelte una herramienta personalizada en el lienzo.
3. En el separador Paquete, haga clic para seleccionar el archivo ZIP con su código personalizado o arrástrelo y suéltelo en la pantalla. Espere a que se complete la carga.
   
   

   

   
   
4. Revise la lista de herramientas detectadas en la sección Herramientas del separador Paquete. Cada clase de herramienta encontrada en tool_implementation.py se muestra con su nombre de clase, descripción y versión.
   
   

   

   
   
5. Seleccione las herramientas que desea activar. Las herramientas desactivadas no están expuestas al agente.
6. Opcional: haga clic en el separador Prueba. Proporcione los parámetros de prueba y haga clic en Enviar. Consulte los resultados de prueba en el panel Resultados de prueba.

Herramienta de servidor MCP remoto

Los desarrolladores de flujos de agentes pueden conectar sus flujos de agentes a servidores de protocolo de contexto de modelo remoto (MCP) mediante la herramienta Servidor MCP remoto.

La herramienta MCP está disponible tanto en el creador visual como en las experiencias del creador de código. En la experiencia del creador de código, la conexión MCP se puede configurar a través de la biblioteca Python helppUtils. En esta sección, le mostraremos las experiencias del creador visual y del creador de código.

Note:

Esta función admite servidores MCP con transportes de flujo HTTP (servidores remotos). No se admiten servidores MCP locales de transporte de stdio.

Credenciales de MCP en el almacén de credenciales de Oracle AI Data Platform Workbench

Al configurar el servidor MCP, debe seleccionar si el servidor MCP remoto requiere Sin autenticación o un token de portador. Si el servidor MCP necesita un token de autenticación, dicho token debe agregarse al almacén de credenciales para que el servidor MCP pueda hacer referencia a él.

Al crear una credencial de servidor MCP, seleccione la opción Token secreto para Tipo de credencial y, a continuación, proporcione la clave de identificador, como una clave de API y el valor de token. Para obtener más información, consulte Creación de credenciales (vista previa).

Note:

Una sola credencial puede contener varias claves.

Los servidores MCP disponibles públicamente no requieren autenticación adicional. Por ejemplo, la conexión a https://mcp.deepwiki.com/mcp tendría el siguiente aspecto:

Cómo exponer herramientas MCP al agente

Una vez que se haya establecido una conexión correcta con el servidor MCP remoto, puede comenzar a configurar las herramientas alojadas en el servidor que desea exponer a su agente. El panel de configuración del servidor MCP se muestra a continuación en el caso del servidor DeepWiki MCP.

A la izquierda, la ficha Herramientas muestra una lista de herramientas disponibles en el servidor MCP. Debe agregar herramientas para exponerlas a su agente. Para ello, haga clic en la opción Agregar todo para mostrar todas las herramientas a la vez o haga clic en cada herramienta Agregar de forma individual para seleccionar un subjuego de las herramientas.

En el ejemplo siguiente, agregamos dos herramientas (read_wiki_structure, read_wiki_structure). Puede eliminar herramientas haciendo clic en Eliminar.

El panel derecho de la ficha Herramientas proporciona documentación sobre cada herramienta, incluido el nombre de la herramienta, la descripción de la herramienta y los parámetros de la herramienta. En la siguiente captura de pantalla, muestro un ejemplo para la herramienta de servidor MCP de GitHub add_comment_to_pending_review.

Oracle AI Data Platform Workbench proporciona un par de controles adicionales sobre cada herramienta. Puede ocultar parámetros del agente y asignar valores a esos parámetros. Por ejemplo, en GitHub, puede elegir que su agente solo comente un repositorio predeterminado, como oracle-aidp-samples. Para ello, desactive el parámetro repo y asigne un valor por defecto en el cuadro de texto:

En el campo Tool Instructions (Instrucciones de herramienta), también puede sustituir la descripción de la herramienta y proporcionar una descripción alternativa con instrucciones adicionales. Para la mayoría de los casos de uso, le recomendamos que adopte la descripción que proporciona el servidor MCP.

Herramienta de servidor MCP remoto mediante LangGraph Code

La biblioteca Python aidpUtils permite a los desarrolladores seleccionar un servidor MCP remoto y exponer un subjuego de sus herramientas a un agente creado con LangGraph. Para obtener información sobre la referencia de la API helpputils, consulte API de Aidp-utils para Oracle AI Data Platform Workbench.

Puede crear una recopilación de herramientas permitidas creando una instancia 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={} 
)

Dónde:

• <MCP_SERVER_NAME> es un nombre mostrado que desea asignar al servidor MCP. Esto se utiliza para fines de documentación y no está expuesto al agente.
• <MCP_ENDPOINT> es el punto final del servidor MCP (por ejemplo, https://api.githubcopilot.com/mcp/)
• <MCP_AUTH> es un diccionario con la clave "authType". Esta clave puede tomar dos valores: NO_AUTH o BEARER_TOKEN. En el caso de BEARER_TOKEN, se espera otra clave: "token" con el valor del token portador.
• <ALLOWED_MCP_TOOLS> es una lista de las herramientas, del servidor MCP, que desea exponer a su agente. Cada herramienta necesita una definición completa de la herramienta JSON siguiendo el protocolo MCP.

A continuación se incluye un ejemplo:

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,
)

El objeto TOOLS se puede utilizar al crear una instancia de un agente con langchain.agent create_agent en el método setup() de la definición del agente de clase:

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.")

También, si utiliza una variable de sesión para almacenar el valor de un token de portador, se puede asignar una referencia a una variable de sesión creada anteriormente a la clave de token del diccionario de configuración de autenticación. Por ejemplo:

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={}
)

Ejemplos de código para herramientas de servidor MCP remoto

Proporcionamos ejemplos de código integrales para varios escenarios de MCP en el repositorio de GitHub de muestras de AI Data Platform Workbench.

Prueba de herramientas de servidor MCP remoto

Una vez seleccionadas las herramientas, el siguiente paso suele ser probar las herramientas individuales para asegurarse de que se comportan como se esperaba. Esto se puede hacer a través del separador Test del nodo de herramienta MCP.

Seleccione una de las herramientas que ha agregado en el separador Tools, proporcione valores de parámetros y haga clic en el botón Test.

La salida de la herramienta se muestra en el panel derecho.

El separador Details proporciona información sobre el método de autenticación, la URL del servidor MCP y la descripción.

El botón Editar junto al método de autenticación le permite modificar la configuración del nodo de herramienta MCP remoto. Puede cambiar el nombre mostrado, la descripción y el token portador utilizado al establecer la conexión:

Conexión de un agente a un servidor MCP remoto desde Visual Builder

Puede agregar acceso a un servidor MCP remoto a su agente arrastrando el nodo de herramientas del servidor MCP personalizado al lienzo.

Si no ve la herramienta del servidor MCP personalizado disponible, es posible que deba reiniciar los recursos informáticos de AI existentes o crear uno nuevo.

Note:

El recurso informático de AI que aloja el agente hereda la configuración de red de su espacio de trabajo. Si activa el acceso de red privada para el espacio de trabajo que aloja los recursos informáticos de AI, el agente solo puede acceder a los servidores MCP alojados en la VCN y subred privadas seleccionadas. Es posible que su agente no pueda acceder a servidores HTTP remotos disponibles en la red pública de Internet.

1. Vaya a su agente.
2. En el separador Flujo, en Plantillas de herramientas, haga clic y arrastre el servidor MCP personalizado al lienzo.
3. Proporcione la URL de servidor para el servidor MCP.
4. Proporcione un nombre mostrado para el servidor MCP. Este es el nombre del nodo que se muestra en el lienzo del creador visual.
5. Opcional: proporcione una descripción para el servidor MCP. El campo de descripción no se proporciona al agente.
6. En el menú desplegable Autenticación, seleccione un método de autenticación.
   • Sin Autenticación: utilice esta opción si el servidor MCP remoto está disponible públicamente y no requiere autenticación.
   • Token de portador: utilice esta opción si el servidor MCP remoto requiere un token de autenticación. Debe almacenar la clave de API en el almacén de credenciales de Oracle AI Data Platform Workbench y proporcionar una referencia a la entrada del almacén de credenciales.
7. Haga clic en Conectar. AI Data Platform Workbench prueba la conexión e informa el resultado.

Herramienta de solicitud HTTP

La herramienta de solicitud HTTP permite a su agente llamar a cualquier API de REST HTTPS.

Puede configurar la solicitud, incluido el método, la URL, las cabeceras, los parámetros de consulta, el cuerpo de la solicitud, la autenticación y, opcionalmente, un paso de optimización de respuesta. Luego, el agente llama al punto final en tiempo de ejecución. La herramienta de solicitud HTTP está disponible tanto en el creador visual como en el creador de código. En el creador de código, la herramienta se configura a través de la biblioteca Python helppUtils.

Note:

La herramienta de solicitud HTTP solo admite solicitudes https:// y HTTP://. Las conexiones de WebSocket (ws/wss), las cargas de archivos binarios y los certificados autofirmados no están soportados.

Note:

El recurso informático de AI que aloja el agente hereda la configuración de red de su espacio de trabajo. Si activa el acceso de red privada para el espacio de trabajo que aloja los recursos informáticos de AI, su agente solo alcanzará los puntos finales HTTP en la VCN y subred privadas seleccionadas. Su agente no puede acceder a los puntos finales disponibles en la red pública de Internet.

Al configurar una herramienta de solicitud HTTP, se deben proporcionar los siguientes valores:

Configuración	Descripción
Método HTTP	Verbo HTTP que se va a utilizar. Los métodos admitidos son GET, POST, PUT, PATCH y DELETE.
URL	URL completa del punto final de destino. La URL soporta referencias de variables de sesión {{sessionVariables.variable_name}} y referencias de parámetros de tiempo de ejecución {{variable}}. Por ejemplo: https://api.example.com/users/{{user_id}}/orders.
Timeout	La cantidad máxima de tiempo que la herramienta esperará una respuesta desde el punto final remoto. El valor por defecto es 30 segundos y el máximo es 300 segundos.
Tipo de Autenticación	Método de autenticación que se debe utilizar al llamar al punto final. Consulte la sección Autenticación a continuación para obtener la lista de métodos de autenticación admitidos.

Note:

Las herramientas de código personalizadas se ejecutan en el recurso informático AI asociado a su agente. El código tiene acceso al entorno informático y al acceso de red saliente sujeto a la configuración de red del espacio de trabajo. Solo carga código de fuentes de confianza.

Cabeceras

Las cabeceras son pares clave-valor enviados con la solicitud HTTP. Puede agregar tantas cabeceras como sea necesario haciendo clic en el botón Agregar nuevo. Los valores de cabecera pueden hacer referencia a variables de sesión y parámetros de tiempo de ejecución mediante la sintaxis {{variable_name}}.

Note:

Para las cabeceras confidenciales, debe utilizar el campo Tipo de autenticación para asegurarse de que las credenciales se inyectan de forma segura desde el almacén de credenciales. La autorización, la cookie y la clave de la X-API son cabeceras confidenciales y no se pueden definir mediante la sección Cabeceras.

Parámetros de Consulta

Los parámetros de consulta se agregan a la URL como cadena de consulta. Puede agregar tantos parámetros de consulta como sea necesario haciendo clic en el botón Agregar nuevo. Al igual que las cabeceras, los valores de parámetros de consulta pueden hacer referencia a variables de sesión y parámetros de tiempo de ejecución.

Descripción

El campo de descripción describe lo que hace la herramienta, cuándo se debe utilizar y qué tipo de salidas o efectos produce. La descripción se proporciona al agente y ayuda al LLM a decidir cuándo llamar a la herramienta.

Al escribir la descripción, debe centrarse en:

• • Objetivo: explique para qué está diseñada la herramienta en una frase clara. Ejemplo: "Esta herramienta recupera tickets de soporte al cliente de una base de conocimientos y los resume por nivel de prioridad".
• Cuándo utilizarla: describa las condiciones en las que el agente debe llamar a esta herramienta en lugar de a otra.
• Entradas y salidas: describa brevemente los parámetros que necesita la herramienta y la forma de lo que devuelve.

Autenticación de solicitud HTTP

La herramienta de solicitud HTTP admite varios métodos de autenticación. Seleccione el método adecuado en la lista desplegable Tipo de autenticación.

Tipo de Autenticación	Descripción
Sin Autenticación	No se ha agregado ninguna autenticación a la solicitud. Utilícelo para puntos finales de acceso público.
Entidad de recursos de OCI	La solicitud se firma mediante la entidad de recurso de OCI de AI Compute. Utilícelo al llamar a servicios de OCI como Object Storage o al servicio OCI Generative AI. El acceso se rige por las políticas de OCI IAM.
Autenticación Básica	El nombre de usuario y la contraseña se codifican y se envían en el encabezado Autorización. Las credenciales se deben almacenar en el almacén de credenciales.
Token de portador	Se envía un token de portador en el encabezado Autorización. El token debe estar almacenado en el almacén de credenciales.
Cabecera de autenticación	Una clave de API se envía en una cabecera personalizada (como X-API-Key). El nombre de cabecera se puede configurar y el valor de clave se debe almacenar en el almacén de credenciales.

Cuando selecciona un método de autenticación que requiere un secreto, el panel de configuración muestra un selector de credenciales. Haga clic en el selector de credenciales para seleccionar una credencial almacenada anteriormente o cree una nueva desde el almacén de credenciales. Consulte el almacenamiento de una credencial en la sección Almacén de credenciales de la documentación del servidor MCP para conocer el procedimiento paso a paso.

Variables de Sesión y Parámetros de Tiempo de Ejecución

Se puede hacer referencia a las variables de sesión en la URL, los valores de cabecera, los valores de parámetros de consulta y el cuerpo de la solicitud mediante la sintaxis {{sessionVariables.variable_name}}. Los parámetros de tiempo de ejecución transferidos por el agente en el momento de la llamada se pueden hacer referencia mediante la sintaxis {{variable_name}}.

Por ejemplo, la siguiente URL combina una variable de sesión para la región con un parámetro de tiempo de ejecución para el nombre del cubo:

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

Cuando se ejecuta la herramienta, {{sessionVariables.region}} se sustituye por el valor de la variable de sesión de región para la sesión actual y {{bucket}} se sustituye por el valor que el agente ha transferido en el momento de la llamada.

Note:

Los valores de plantilla se codifican automáticamente mediante URL cuando se sustituyen en los parámetros de consulta o URL. No necesitas codificarlos por URL.

Definición de herramienta de IA

El lado derecho del panel de configuración muestra la definición de la herramienta AI. Esquema expuesto al agente que incluye el nombre de la herramienta, la descripción y la lista de parámetros de tiempo de ejecución que el agente puede transferir al llamar a la herramienta. La definición de la herramienta AI se genera automáticamente a partir del campo Descripción y de los marcadores de posición {{variable}} detectados en la URL, las cabeceras, los parámetros de consulta y el cuerpo.

El panel de definición de la herramienta AI es el panel de la derecha del panel de configuración de la herramienta HTTP que se muestra anteriormente en este documento. Hasta que proporcione una descripción y defina al menos un parámetro de tiempo de ejecución, el panel de definición de la herramienta AI muestra un mensaje de marcador de posición. Una vez que rellene la descripción y haga referencia al menos a un {{variable}} en la URL, las cabeceras, los parámetros de consulta o el cuerpo, el esquema se presentará en el panel.

Optimización de la respuesta para el agente

Muchas API devuelven respuestas grandes que incluyen campos que el agente no necesita. El envío de toda la respuesta al agente consume tokens y puede degradar la calidad del razonamiento del agente. La herramienta de solicitud HTTP proporciona una sección de optimización de respuesta que permite reducir la carga útil de respuesta antes de que se devuelva al agente.

Se admiten tres estrategias de optimización:

• Selección de campos JSON: seleccione un subjuego de campos de una respuesta JSON. Puede especificar una ruta de acceso a un objeto anidado mediante la notación de puntos (como data.results) y una lista de campos para incluir o excluir.
• Selector CSS HTML: extracción de un subjuego de una respuesta HTML mediante un selector CSS (como article.content). Opcionalmente, tira las etiquetas HTML para devolver solo texto.
• Truncamiento de texto: limita la respuesta a un número máximo de caracteres para evitar respuestas de texto demasiado grandes.

Gestión de errores y códigos de error

Cuando falla la solicitud HTTP, la herramienta devuelve una respuesta de error estructurada al agente. El error incluye un código de error, un mensaje legible por el usuario y detalles sobre el fallo. El agente puede utilizar esta información para decidir si reintentar, volver a una herramienta diferente o informar el fallo al usuario.

Código de error	Categoría	Significado	Reintentable
CONNECTION_TIMEOUT	Red	El punto final remoto no ha respondido dentro del timeout configurado.	Sí
FALLO DE DNS	Red	No se pudo resolver el nombre de host en la URL.	Sí
CONEXIÓN_RECHAZADA	Red	El punto final remoto rechazó la conexión.	Sí
ERROR_CERTIFICADO_SL	TLS	No se ha podido validar el certificado TLS del punto final remoto.	N.º
NO AUTORIZADO	HTTP 401	El punto final remoto ha rechazado las credenciales. Verifique que la referencia de credencial es válida y no ha caducado. Para la entidad de recurso de OCI, confirme que la entidad de recurso de AI tiene una entidad de recurso activa en este entorno.	N.º
PROHIBIDO	HTTP 403	Las credenciales se han autenticado correctamente, pero no tienen permiso para el recurso solicitado. Verifique los ámbitos de API, los permisos o la política de IAM asociada al recurso.	N.º
NO_ENCONTRADO	HTTP 404	El punto final remoto no ha encontrado el recurso solicitado.	N.º
VELOCIDAD_LIMITADA	HTTP 429	El punto final remoto limita el ratio del emisor de llamada. Vuelva a intentarlo después del retraso indicado por la cabecera Retry-After.	Sí
ERROR DE SERVIDOR	HTTP 5xx	El punto final remoto ha devuelto un error de servidor. A menudo un problema transitorio.	Sí
SERVICE_UNAVAILABLE (SERVICIO NO DISPONIBLE)	HTTP 503	El punto final remoto no está disponible temporalmente.	Sí
INVALID_TEMPLATE	Validación	No se ha podido resolver una referencia {{variable}}. Verifique que todas las variables de sesión a las que se hace referencia y los parámetros de tiempo de ejecución están definidos y tienen un valor en el momento de la llamada.	N.º
INVALID_URL	Validación	La URL tiene un formato incorrecto, utiliza un protocolo no soportado o se resuelve en una dirección bloqueada (por ejemplo, una dirección IP privada o un punto final de metadatos en la nube).	N.º
RESPUESTA_TOO_LARGE	Validación	La respuesta ha superado el tamaño máximo de respuesta de 10 MB.	N.º
RATE_LIMIT EXCEDIDO	Plataforma	El agente ha superado el límite de ratio de solicitudes por agente de la plataforma (60 solicitudes por minuto) o el límite de simultaneidad (10 solicitudes simultáneas).	Sí

Cada respuesta de error incluye un campo de orientación con un paso siguiente sugerido y un campo de detalles con el tiempo transcurrido y cualquier contexto específico del error, como el código de estado HTTP.

Herramienta de solicitud HTTP mediante código LangGraph

Desde el creador de código, la herramienta de solicitud HTTP se configura a través de la biblioteca Python helppUtils. Defina un valor AIDPToolConf con tool_class definido en HttpEndpointTool y transfiera el diccionario de configuración en el 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())

El diccionario de configuración admite los mismos campos que el creador visual: method, url, headers, params, body, auth_type, auth_config y response_optimization. La lista de parámetros define los parámetros de tiempo de ejecución que puede transferir el agente.

tipo_autorización	Campos auth_config
NO_AUTENTICACIÓN	{} (vacío)
RESOURCE_PRINCIPAL	{} (vacío)
AUTENTICACIÓN_BÁSICA	nombre de usuario, contraseña (o nombre de usuario_vault_id, contraseña_vault_id para credenciales en OCI Vault)
PORTADOR_AUTH	bearer_token (o bearer_token_vault_id)
API_KEY_AUTH	api_key (o api_key_vault_id), header_name (clave de API por defecto)
CREDENCIALES_CLIENTE_OAUTH2	token_endpoint, ámbito, client_id, client_secret (o client_id_vault_id, client_secret_vault_id)

Herramientas de código personalizado de agente de prueba

El separador Prueba permite ejecutar la herramienta sin ejecutar el agente completo. Proporcione valores para cualquier parámetro de tiempo de ejecución y cualquier variable de sesión a la que se haga referencia en la configuración y, a continuación, haga clic en Run para llamar a la herramienta y ver la respuesta.

El panel de respuesta muestra el código de estado HTTP, las cabeceras de respuesta, el cuerpo de respuesta y el tiempo transcurrido en milisegundos. Si la optimización de respuesta está activada, la respuesta optimizada también se muestra junto con la respuesta raw.

Adición de una herramienta de solicitud HTTP a un agente

Puede agregar una herramienta de solicitud HTTP a los agentes para que pueda llamar a las API de REST HTTPS.

Note:

Se debe asociar un recurso informático de IA a su agente antes de agregar una herramienta de código personalizada. Los recursos informáticos de AI son necesarios para instalar dependencias y ejecutar la herramienta.

1. Vaya a su agente.
2. Desde las plantillas de herramientas, arrastre y suelte una herramienta de solicitud HTTP en el lienzo.
   
   

   

   
   
3. En el separador Parámetros, proporcione el método HTTP. Los métodos de trabajo admitidos son GET, POST, PUT, PATCH y DELETE.
4. En URL, proporcione la URL completa del punto final de destino. Puede utilizar referencias de variables de sesión {{sessionVariables.variable_name}} y referencias de parámetros de tiempo de ejecución {{variable}}. Por ejemplo: https://api.example.com/users/{{user_id}}/orders.
5. En Timeout, proporcione la cantidad máxima de tiempo que la herramienta espera una respuesta desde un punto final remoto en segundos. El valor de timeout máximo es 300. Si no se proporciona ningún valor, el valor predeterminado es 30 segundos.
6. En el menú desplegable Autenticación, seleccione el tipo de autenticación adecuado.
7. Proporcione las cabeceras de la solicitud HTTP. Haga clic en Agregar nuevo para agregar cabeceras adicionales.
   
   

   

   
   
8. Proporcione cualquier parámetro de consulta para la solicitud HTTP. Haga clic en Agregar nuevo para agregar parámetros adicionales.
   
   

   

   
   
9. Opcional: haga clic en el separador Prueba. Proporcione los parámetros de prueba y haga clic en Enviar. Consulte los resultados de prueba en el panel Resultados de prueba.

Herramienta de mensajes

La herramienta de petición de datos le permite llamar a un LLM en un agente de IA con una petición de datos con plantilla y devuelve la respuesta del LLM al agente.

Las peticiones de datos que proporcione al LLM pueden incluir parámetros que se identifican con llaves dobles, por ejemplo {{PARAMETER_NAME}}. Los valores de parámetros los asigna el agente cuando se llama a la herramienta.

Cuándo utilizar las herramientas de petición de datos

En principio, las instrucciones escritas en una herramienta rápida pueden incluirse directamente en las instrucciones del agente o pueden ser proporcionadas directamente por el usuario final en un mensaje de usuario. Sin embargo, hay situaciones en las que la herramienta rápida es un mejor enfoque:

• Su petición de datos es larga y requiere instrucciones de formato detalladas que abarquen varios tokens de los años 100.
• La incorporación de la petición de datos en las instrucciones del agente aumentaría el uso del contexto y aumentaría significativamente los costos, especialmente si se adopta un LLM SOTA para su agente.
• Se desea minimizar el tamaño de las instrucciones dadas al agente para reducir el costo.
• La tarea definida por la herramienta de petición de datos puede ser manejada por un LLM más pequeño y rápido que el modelo de razonamiento utilizado por el agente. Los modelos más pequeños suelen ser rentables y, en algunos casos, pueden especializarse para generar datos en una modalidad o formato particular.
• Una herramienta de petición de datos permite que los parámetros de entrada estructurados controlen la generación de salida. Si su caso de uso podría ser parametrizado y la generación puede variar de una sesión a otra, encapsular la generación en una herramienta de petición de datos tiene sentido.

Además, la encapsulación de instrucciones de generación en una herramienta rápida sigue muchas prácticas recomendadas de arquitectura de agentes modernas, como la reutilización de herramientas, la capacidad de mantenimiento, la modalidad, la consistencia de salida, la escalabilidad y la gobernanza. Algunos ejemplos de casos de uso incluyen:

• Generación de correos electrónicos, informes, resúmenes, artículos, etc. siguiendo una estructura predefinida y aprobada que se puede utilizar como plantilla
• Generación de salidas JSON complejas
• Suma, extracción de frases clave, tareas de explicación en documentos
• Generación de consultas
• Generación de modalidades específicas (por ejemplo, imágenes, vídeos, audio, datos de nube de puntos, etc.) optimizadas para un modelo específico

Herramientas de petición de datos a través de Visual Flow

A continuación se muestra un ejemplo de una herramienta de petición de datos creada a través de un flujo visual que solicita a un LLM que genere títulos de publicaciones de blog basados en un tema asignado por el agente:

Eres un estratega de blogs maestro. Su tarea es hacer una lluvia de ideas de publicaciones de blog convincentes basadas en un tema determinado. Para el {{topic}}, genere 5 títulos únicos de publicaciones de blog. Para cada título, incluya una descripción de una frase del ángulo que tomaría el poste. Presente la salida como una lista numerada.

Para este ejemplo, debe configurar los siguientes parámetros para la herramienta de petición de datos:

• Nombre de la herramienta: utilice un nombre descriptivo para la herramienta que le ayude a guiar al agente. En este ejemplo, sugerimos blog_ideas. Evite usar nombres inútiles como tool123.
  
  
  
  
• Descripción de la herramienta: proporcione una descripción completa de lo que hace la herramienta. Si existen limitaciones para la herramienta o si existen escenarios en los que no se debe utilizar la herramienta, enumérelas en el campo de descripción.
  
  
  
  
• Región de OCI y LLM de servicio de GenAI: seleccione la región de OCI para rellenar la lista de LLM disponibles en esa región y, a continuación, seleccione su LLM.
  
  
  
  
• Parámetros LLM: los parámetros como tokens de salida máxima, temperatura y p superior se configuran en el separador Parámetros de modelo. Si no asigna ningún valor, se utilizan los valores por defecto del servicio OCI Generative AI.
  
  
  
  
• Consulta: la petición de datos utilizada para definir la finalidad de la herramienta se define en el campo Consulta.
  
  
  
  

Los parámetros que se definen en la petición de datos se rellenan automáticamente en el panel de definición de AI Tool. Proporcione a su agente una descripción de cada parámetro, así como el tipo de parámetro y el valor por defecto siempre que corresponda.

Herramienta de valores válidos a través del código LangGraph

Si está creando el agente a través del código, puede configurar la misma herramienta de petición de datos en el ejemplo de flujo visual de la siguiente manera:

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

A continuación, instancie AIDPToolConf de la siguiente 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 último, se crea una herramienta compatible con LangGraph con la función de utilidad create_langgraph_tool() desde Aidputils:

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

Puede agregar la herramienta recién creada a un agente ReAct. En LangGraph, el código se ve así:

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

Tabla 18-1 Propiedades de configuración de la herramienta de petición de datos

Propiedad	Tipo	Descripción
llm	objeto	Detalles y parámetros de conexión del LLM
model_id	Cadena	Identificador del modelo que se va a utilizar (por ejemplo, "xai.grok-4")
proveedor_modelo	Cadena	Nombre del proveedor para el modelo de LLM (por ejemplo, "genérico")
compartment_id	Cadena	OCID de compartimento de Oracle Cloud Infrastructure (OCI)
punto final	Cadena	URL de punto final para el modelo
prompt_template	Cadena	Plantilla de petición de datos utilizada por el LLM, con variables en formato {{variable}} para inserción dinámica

Herramientas de petición de datos de agente de prueba

Para probar la herramienta independientemente del agente, haga clic en el separador Probar y rellene el valor de cada parámetro. La petición de datos se envía al LLM seleccionado.

Asegúrese de que la herramienta de mensajes está bien definida y documentada para mejorar los resultados de su agente.

Adición de una herramienta de mensajes a un agente

Puede agregar una herramienta de petición de datos a los agentes para que pueda definir peticiones de datos parametrizadas que emita al LLM de su elección.

1. Vaya a su agente.
2. En las plantillas de herramienta, arrastre y suelte una herramienta de petición de datos en el lienzo.
3. En el separador Configuration, seleccione el LLM que desea utilizar y proporcione la petición de datos para el LLM. Haga clic en Código para proporcionar la configuración como código JSON.
4. Proporcione una temperatura para la respuesta como valor entre 0,0 y 1,0, donde 0,0 proporciona una respuesta estrictamente objetiva y 1,0 proporciona la respuesta más creativa.
5. Haga clic en Aplicar .
6. Proporcione las definiciones de los parámetros que haya establecido en la configuración. Haga clic en Código para proporcionar la configuración como código JSON.
7. Haga clic en Aplicar.
8. Opcional: haga clic en el separador Prueba. Proporcione los parámetros de prueba y haga clic en Enviar. Consulte los resultados de prueba en el panel Resultados de prueba.

Herramienta RAG

La herramienta RAG emite una consulta en lenguaje natural a un almacén de vectores y recupera documentos en función de la similitud semántica entre la consulta y los documentos almacenados.

Note:

Una base de conocimientos es un requisito previo para la creación de una herramienta RAG. Para obtener más información, consulte Bases de conocimiento.

Herramientas RAG a través de Visual Flow

La herramienta RAG requiere que, como desarrollador de agentes, proporcione valores para los siguientes parámetros:

• Orientado al agente:
  • Nombre de la herramienta: nombre descriptivo de la herramienta que le ayuda a usted y a otros usuarios a identificar su función.
  • Descripción de la herramienta: resumen breve que proporciona una visión general de la herramienta.
• Configuración de herramienta:
  • Base de conocimientos: base de conocimientos almacenada en uno de sus catálogos de Oracle AI Data Platform Workbench.
    
    
    
    

El agente definirá el valor del campo de consulta en función de su conversación con el usuario final. Este campo de consulta realiza una consulta en lenguaje natural.

El límite es el número de fragmentos de documento que desea que la herramienta recupere del almacén de vectores. Este valor lo define el desarrollador del agente, no el propio agente.

Puede simular una consulta emitida por el agente haciendo clic en el separador de prueba de la RAG también:

Herramientas RAG a través de LangGraph Code

La creación de una herramienta RAG en el agente a través del código requiere la configuración de los mismos valores y parámetros que el flujo visual. Por ejemplo, puede definir los parámetros RAG de la siguiente manera:

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

A continuación, configure la configuración de 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 último, se crea una herramienta compatible con LangGraph con la función de utilidad create_langgraph_tool() desde 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())

Tabla 18-2 Propiedades de configuración de la herramienta RAG

Propiedad	Tipo	Descripción
llm	objeto	Detalles de conexión de LLM
catalog	Cadena	Identificador de catálogo de datos
esquemas	Cadena	Esquema dentro del catálogo
base de conocimientos	Cadena	Nombre o clave de la base de conocimientos para buscar
principal_k	integer	Número de documentos coincidentes principales que recuperar

Herramientas de prueba de agente RAG

Puede probar la herramienta RAG desde el separador Probar después de asociar el agente a un cluster de recursos informáticos de AI. Para obtener más información, consulte Attach an Existing AI Cluster to an Agent.

Adición de una herramienta RAG a un agente

Puede agregar una herramienta de generación aumentada de recuperación (RAG) a los agentes para permitir que el agente extraiga los conocimientos externos relevantes al generar una respuesta.

1. Vaya a su agente.
2. Desde las plantillas de herramientas, arrastre y suelte una herramienta RAG en el lienzo.
3. En el separador Configuración, seleccione la base de conocimientos de la que la herramienta RAG extrae información y proporcione la petición de datos para definir la información que se va a extraer. Haga clic en Código para proporcionar la configuración como código JSON.
4. Haga clic en Aplicar .
5. Proporcione las definiciones de los parámetros que haya establecido en la configuración. Haga clic en Código para proporcionar la configuración como código JSON.
6. Haga clic en Aplicar.
7. Opcional: haga clic en el separador Prueba. Proporcione los parámetros de prueba y haga clic en Enviar. Consulte los resultados de prueba en el panel Resultados de prueba.

Herramienta SQL

La herramienta SQL permite a los desarrolladores de agentes ejecutar consultas SQL predefinidas en tablas registradas en un catálogo de Oracle AI Data Platform.

La consulta se escribe en tiempo de diseño y se definen las variables de tiempo de ejecución que necesita. El agente proporciona valores para esas variables cuando llama a la herramienta, y los resultados se devuelven como filas estructuradas que el agente puede resumir o transferir a un nodo descendente.

La herramienta SQL admite dos dialectos de consulta. Spark SQL se ejecuta en tablas de catálogo estándar almacenadas en AI Data Platform y necesita un cluster de Spark. Oracle SQL se ejecuta en una base de datos externa, como Oracle Autonomous AI Database. Usted elige el dialecto por herramienta, y el resto de la configuración es la misma para ambos.

Note:

La herramienta SQL está diseñada para consultas de lectura. Una herramienta típica ejecuta una sentencia SELECT y devuelve filas. El catálogo, el esquema y la consulta que configure son privados para la herramienta y no están expuestos al agente. Solo el agente puede ver el nombre de la herramienta, la descripción y la definición de la herramienta AI (las variables de tiempo de ejecución).

Note:

La herramienta de consulta SQL no inicia automáticamente los clusters parados. Como resultado, el cluster de Spark utilizado para la herramienta de consulta de Spark SQL debe tener una duración de Forever. Si el cluster puede girar hacia abajo en un timeout inactivo, las consultas SQL de Spark dejan de funcionar en producción una vez que el cluster se detiene.

Consultas estáticas y dinámicas

Una consulta estática devuelve exactamente lo que especifica, sin que el agente tome ninguna decisión en tiempo de ejecución. Una consulta dinámica incluye uno o más marcadores de posición {{variable}} que indican al agente que el valor se define en tiempo de ejecución. Para cada marcador de posición, debe proporcionar un nombre, un tipo, un valor por defecto opcional y una descripción que el agente utilice para elegir el valor.

Por ejemplo, la siguiente consulta estática devuelve un juego de resultados fijo:

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

La sustitución del literal por un marcador de posición {{year}} lo convierte en una consulta dinámica que el agente puede parametrizar:

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

A medida que agrega marcadores de posición, el panel de definición de la herramienta AI se rellena con cada variable para que pueda definir su tipo, valor predeterminado y descripción.

Los marcadores de posición pueden aparecer en cualquier lugar de la consulta, incluidas las funciones internas. La siguiente consulta SQL de Spark coincide con un valor de gravedad de forma no sensible a mayúsculas/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}}')

Proporcione a cada variable una descripción clara y un valor por defecto razonable. La descripción indica al agente qué valores son válidos y el valor por defecto se utiliza cuando el agente no proporciona uno.

Note:

Los nombre de los marcadores de posición distinguen entre mayúsculas/minúsculas. Un marcador de posición escrito como {{SEVERITY}} y uno escrito como {{severity}} se tratan como dos variables diferentes, a menos que utilice siempre minúsculas.

Edición de la configuración como JSON

Puede editar la configuración de la herramienta SQL directamente como JSON mediante el conmutador de la vista de código. Esto resulta útil para copiar una herramienta entre agentes o realizar ediciones masivas.

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

Límites de fila

Puede limitar el número de filas que devuelve la herramienta seleccionando Máximo de filas para devolver e introduciendo un valor límite. Los límites de fila protegen el rendimiento y controlan la cantidad de datos que se devuelven al agente.

Defina este valor en relación con el modelo que utiliza el agente. Los valores más grandes pueden provocar fallos de agente cuando las consultas devuelven filas o columnas amplias con valores de texto grandes. Si observa errores inesperados del agente, comience por reducir maxRows.

El límite de filas se aplica a la propia consulta SQL, antes de que se ejecute la consulta. La mayoría de los modelos detectan el límite y lo muestran al usuario final. Para una consulta estática, el límite devuelve las primeras n filas disponibles.

Note:

Si no desea que aparezcan los límites de fila para los usuarios finales, indique al agente en consecuencia en sus instrucciones.

Ejemplos de consulta

Puede ver ejemplos de consultas y una guía para escribir consultas de la herramienta SQL desde el botón Ver ejemplos de consultas y guía.

En la guía se muestran diferentes patrones de consulta y se proporcionan diferentes recomendaciones sobre los parámetros de consulta.

Herramientas SQL a través de LangGraph Code

Al igual que con el flujo visual, comienza a crear una herramienta SQL para su agente a través del código LangGraph creando una consulta:

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

Documente cada parámetro de la consulta SQL en el argumento de los parámetros con un nombre, un tipo, una descripción y, opcionalmente, un defaultValue.

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

Por último, se crea una herramienta compatible con LangGraph con la función de utilidad create_langgraph_tool() desde 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())

Tabla 18-3 Propiedades de configuración de la herramienta SQL

Propiedad	Tipo	Descripción
clave de catálogo	Cadena	Identificador para la conexión de catálogo o base de datos
clave de esquema	Cadena	Nombre de esquema dentro del catálogo/base de datos
consulta	Cadena	Cadena de consulta SQL, puede incluir marcadores de posición en {{}}

Probar herramientas SQL del agente

El separador Test ejecuta la herramienta por sí solo, sin ejecutar el agente completo. Las pruebas funcionan de la misma manera para ambos dialectos. Abra el separador Test, proporcione un valor para cada parámetro de tiempo de ejecución (o utilice los valores por defecto) y haga clic en Submit para ejecutar la consulta y ver la respuesta.

Note:

Para probar una herramienta, es necesario que el agente esté conectado a un recurso informático de IA. Se conecta un recurso informático de AI si la etiqueta de AI Compute está en verde con el recurso informático de AI seleccionado en un estado ACTIVO.

Referencia de comandos SQL

Las consultas de la herramienta SQL son consultas de lectura creadas a partir de las cláusulas SQL estándar. El dialecto SQL de Oracle sigue a Oracle SQL con respecto a la base de datos externa. El dialecto SQL de Spark tiene como destino las tablas de catálogo estándar, que son tablas Delta Lake; el catálogo estándar actualmente ejecuta Spark 3.5 con Delta Lake 3.2.0. La mayoría de las cláusulas se escriben de la misma manera en ambos dialectos, porque ambas siguen el SQL estándar. La diferencia principal es cómo cada dialecto limita el número de filas. En la siguiente tabla, se muestran las cláusulas y palabras clave que se utilizan con mayor frecuencia en las consultas de la herramienta SQL, con el formulario para cada dialecto.

Palabra clave o cláusula	Finalidad	SQL de Oracle	Spark SQL
SELECT	Seleccione las columnas que desea devolver	SELECT col1, col2
DISTINCT	Devolver solo filas únicas	SELECT DISTINCT col	SELECT DISTINCT col
FROM	Asignar un nombre a la tabla de origen	FROM table_name	FROM table_name
WHERE	Filtrar filas por una condición	WHERE col = value	WHERE col = value
Y O NO	Combinar o negar condiciones	a AND b OR NOT c	a AND b OR NOT c
IN	Coincidir con cualquier valor de una lista	col IN (a, b, c)	col IN (a, b, c)
BETWEEN	Coincidir con un rango inclusivo	col BETWEEN x AND y	col BETWEEN x AND y
LIKE	Hacer coincidir un patrón de texto	col LIKE 'A%'	col LIKE 'A%'
IS NULL	Prueba de valores que faltan	col IS NULL	col IS NULL
ORDER BY	Ordenar el resultado	ORDER BY col DESC	ORDER BY col DESC
AGRUPAR POR	Agrupar filas para agregación	GROUP BY col	GROUP BY col
HAVING	Filtrar filas agrupadas	HAVING COUNT(*) > 1	HAVING COUNT(*) > 1
UNIÓN EL	Combinar filas de dos tablas	a JOIN b ON a.id = b.id	a JOIN b ON a.id = b.id
AS	Alias de una columna o tabla	col AS name	col AS name
UNION ALL	Combinar dos juegos de resultados	q1 UNION ALL q2	q1 UNION ALL q2
CASE	Devolver un valor de forma condicional	CASE WHEN c THEN x END	CASE WHEN c THEN x END
Agregados	Resumir en filas	COUNT SUM AVG MIN MAX	COUNT SUM AVG MIN MAX
Límite de Fila	Capturar el número de filas	FETCH FIRST n ROWS ONLY	LIMIT n

Note:

Normalmente no escribe el límite de filas usted mismo. El valor de Máximo de filas para devolver se aplica por usted. Los formularios FETCH FIRST y LIMIT sólo son útiles cuando se desea un límite explícito dentro de la consulta.

Para obtener una gramática SQL completa y los motores de consulta detrás de cada dialecto, consulte las siguientes referencias:

SQL de plataforma de datos de Oracle AI

• Gramática SQL
  • Gramática SQL de catálogo
  • Gramática SQL de Esquema
  • Gramática de SQL de volumen
  • Gramática SQL de Tabla
  • Consultas DML

Spark SQL y Delta Lake (catálogo estándar)

Las tablas de catálogo estándar son tablas Delta Lake. El catálogo estándar actualmente ejecuta Spark 3.5 con Delta Lake 3.2.0.

• Sintaxis SQL de Apache Spark: sentencias DML sintaxis de consulta SQL de Spark y sentencia DML.
• Delta Lake: operaciones de supresión, actualización y fusión de tablas DELETE, UPDATE y MERGE en tablas Delta.
• Delta Lake: comandos de la utilidad Table: operaciones de la utilidad, como OPTIMIZE y VACUUM.
• Delta Lake: usar agrupación en clusters líquidos para tablas Delta agrupación en clusters líquidos para el diseño de tabla Delta.

Adición de una Herramienta SQL a un Agente

Puede agregar una herramienta SQL a los agentes para permitir que el agente ejecute consultas SQL en orígenes de datos estructurados en catálogos externos registrados.

1. Vaya a su agente.
2. En las plantillas de herramientas, arrastre y suelte una herramienta SQL en el lienzo.
3. Haga clic y arrastre el identificador del conector en el agente para conectarse al nodo de herramienta.
   
   

   

   
   
4. Haga doble clic en el nodo SQL para abrir el panel de configuración.
5. Proporcione un nombre y descripción para la herramienta. La descripción se proporciona al agente y le ayuda a decidir cuándo llamar a la herramienta.
6. Seleccione el dialecto de consulta:
   • Spark SQL escribe consultas en catálogos estándar de AI Data Platform.
   • Oracle SQL escribe consultas en catálogos externos de AI Data Platform.

   Note:

   Spark SQL necesita un cluster de Spark en ejecución en el espacio de trabajo del área de trabajo de AI Data Platform.
   
   

   

   
   
7. En la lista desplegable Cluster, seleccione un cluster de Spark en ejecución. Haga clic en Crear cluster para aprovisionar un nuevo cluster de Spark. Consulte Creación de un cluster personalizado para obtener orientación sobre la creación de un nuevo cluster.

   Note:

   La herramienta de consulta SQL no inicia automáticamente los clusters parados. Como resultado, el cluster de Spark utilizado para la herramienta de consulta de Spark SQL debe tener una duración de Forever. Si el cluster puede girar hacia abajo en un timeout inactivo, las consultas SQL de Spark dejan de funcionar en producción una vez que el cluster se detiene.

   
   

   

   
   
8. En Examinar catálogo, utilice el campo de búsqueda para buscar un catálogo por nombre o haga clic en el gestor de catálogos para buscar el catálogo.
   
   

   

   
   
9. En el campo Consulta, introduzca la consulta. Haga clic en Ver ejemplos de consultas y guía para abrir un panel que contenga patrones ya creados que puede copiar o adaptar.
   
   

   

   
   
10. Seleccione Máximo de filas que devolver para limitar el número de filas devueltas por los resultados de la consulta.

    Note:

    Si la consulta puede devolver más filas que este límite, considere agregar parámetros de búsqueda como {{customer_name}} o {{region}} para que el agente pueda encontrar datos más específicos.
11. En el panel Definición de herramienta AI, defina el tipo, el valor por defecto y la descripción de las variables definidas en la consulta.
    
    

    

    
    
12. Opcional: haga clic en el separador Prueba. Proporcione los parámetros de prueba y haga clic en Enviar. Consulte los resultados de prueba en el panel Resultados de prueba.