22 Agentes de IA

En este capítulo se proporciona información sobre la creación, prueba, despliegue y supervisión de agentes en el espacio de trabajo.

Los agentes son aplicaciones agentic de extremo a extremo. Los agentes se definen mediante un gráfico de pasos representados por nodos de diferentes tipos (disparadores, agentes, barandillas o herramientas). Los agentes se pueden definir a través de un creador de flujos visuales sin código y a través de código a través de bibliotecas de terceros, como LangGraph.

Oracle AI Data Platform Workbench ofrece varias plantillas de herramientas que se pueden configurar para acceder a sus datos y adaptarse a sus casos de uso. Las herramientas soportadas son:

• Herramienta personalizada: la herramienta de código personalizado 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. El agente llama al código como una herramienta, con parámetros proporcionados por el LLM en tiempo de ejecución.
• 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.
• 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.
• Servidor MCP Remoto: los desarrolladores de agentes pueden conectar sus agentes a servidores de protocolo de contexto de modelo remoto (MCP) mediante la herramienta Servidor MCP Remoto.
• 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 (23ai 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 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.

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.

La creación de agentes en AI Data Platform Workbench genera un archivo de artefacto de agente (.aflow) en la carpeta del espacio de trabajo que seleccione. Este archivo no se puede modificar.

Sistemas de varios agentes y patrones de supervisor

Un sistema multiagente es un diseño de aplicación de IA en el que varios agentes cooperantes manejan una solicitud de usuario en lugar de un agente grande y multifuncional.

Cada agente tiene su propio rol, instrucciones, configuración de modelo, política de memoria y herramientas permitidas. El flujo define cómo se mueve la solicitud entre esos agentes y cómo se produce la respuesta final.

Este diseño es útil cuando un flujo de trabajo se separa naturalmente en responsabilidades especializadas. Por ejemplo, un agente puede recuperar datos, otro puede llamar a una API, otro puede resumir conclusiones y un supervisor puede decidir qué especialista utilizar y combinar los resultados en una única respuesta.

Note:

Como principio de diseño, lo mejor es comenzar con el diseño de agente más pequeño que cumpla con los requisitos. Agregue múltiples agentes cuando la separación de preocupaciones mejore la fiabilidad, la seguridad, la capacidad de mantenimiento o la observabilidad más de lo que aumenta el costo y la complejidad.

Ventajas de los sistemas multiagentes

Los sistemas multiagentes son los más adecuados para:

• Especialización: asigne a cada agente un trabajo, una petición de datos y un juego de herramientas enfocados en lugar de un bloque de instrucciones abarrotado.
• Enrutamiento y descomposición: permite que un supervisor interprete la solicitud, la divida en subtareas y elija el especialista adecuado para cada subtarea.
• Aislamiento de herramientas y datos: exponga herramientas confidenciales o de alto impacto solo a los agentes responsables de utilizarlas.
• Gobernanza y solución de problemas: facilita la inspección de las transferencias, la propiedad de las herramientas, la configuración de la memoria y los puntos de fallo.

Cuándo elegir diseños de agente único o varios agentes

Un único agente con más herramientas suele ser el primer diseño correcto. Es más fácil de probar, más barato de ejecutar y más fácil de razonar sobre cuándo la tarea tiene un objetivo claro y un modelo de permiso. Utilice un diseño de varios agentes cuando el flujo de trabajo se beneficie de roles explícitos, acceso limitado a herramientas o un supervisor que pueda coordinar varios resultados de especialistas.

Pregunta de diseño	Utilizar agentes únicos cuando...	Utilice varios agentes cuando...
Unidad de tarea	La solicitud tiene un objetivo principal y un poste de respuesta.	La solicitud se debe descomponer, enrutar, verificar o sintetizar en todas las especialidades.
Herramientas y datos	El mismo conjunto de instrucciones y modelo de permiso puede gobernar con seguridad todas las herramientas	Los diferentes agentes necesitan diferentes herramientas, orígenes de datos o límites de acceso.
Instrucciones	La petición de datos permanece clara incluso con todas las reglas de negocio y la guía de herramientas en un solo lugar.	Las instrucciones son más fáciles de mantener como peticiones de datos más pequeñas y específicas del rol.
Costo y latencia	Desea que la ruta más corta del mensaje de usuario responda.	Las ventajas de fiabilidad, gobernanza o mantenimiento justifican una orquestación adicional.
Solución de problemas	Los fallos son fáciles de depurar en un solo rastreo.	Necesita transferencias explícitas, aislamiento de estado y una propiedad más clara para cada paso.

Patrón soportado: Orquestador/supervisor

La experiencia actual del lienzo admite el patrón de orquestador/supervisor. En este patrón, el disparador de chat recibe el mensaje de usuario, las barandillas opcionales evalúan la entrada y un agente supervisor actúa como el orquestador para el resto del flujo.

El supervisor debe centrarse en la planificación, el enrutamiento, la delegación y la síntesis de la respuesta final. Decide qué agente ejecutor debe manejar una tarea, envía a ese ejecutor una instrucción de ámbito, revisa el resultado y, a continuación, delega otro paso o devuelve la respuesta final. Los agentes de ejecución deben ser especialistas más estrechos: realizan el trabajo asignado, utilizan las herramientas adjuntas y devuelven resultados útiles al supervisor.

Acerca del lienzo de flujo visual

Un agente se ensambla arrastrando nodos y plantillas de herramientas de la paleta izquierda al lienzo y, a continuación, conectando los nodos en el orden en que debe viajar la solicitud.

Al seleccionar un nodo, se abre un panel de configuración en la parte inferior de la pantalla.

Elemento de lienzo	Finalidad
Disparador de chat	Punto de entrada para un mensaje de usuario. En la captura de pantalla, este nodo está etiquetado como Mensaje y normalmente se encuentra en la parte superior del flujo. Un nodo de disparador de chat se puede conectar a un agente, un agente de supervisor o un nodo de guías de protección. Solo se permite un disparador de chat por lienzo.
Límite	Capa de seguridad y política opcional colocada antes o después del trabajo del modelo. Las políticas de guías de protección incluyen PII, moderación de contenido y detección de inyección inmediata. Un nodo de guías de protección puede filtrar el tráfico entre un disparador de chat y un nodo de agente, entre un supervisor y un agente ejecutor, o entre nodos de agente y herramienta. Recomendamos un único nodo de guías de protección entre el disparador de chat y el nodo de agente.
Agente supervisor	El orquestador. Recibe la solicitud del usuario, decide qué agente ejecutor o herramienta debe manejar cada tarea y coordina la respuesta final. Solo se permite un agente supervisor en un lienzo.
Agente	Un agente ejecutor. Cada ejecutor debe tener una especialidad clara, como la recuperación de datos, la búsqueda de API, el resumen o la respuesta a preguntas de documentos. Utilizar un agente/agente ejecutor para un único sistema de agente.
Plantillas de herramientas	Capacidades reutilizables que se pueden asociar a un ejecutor individual o un agente de supervisor. Las plantillas de herramientas incluyen SQL, RAG, Petición de datos, HTTP, Servidor MCP remoto y Herramienta personalizada.
Desarrollo / Zona de juegos	Selector de modo sobre el lienzo. El desarrollo se utiliza al editar el sistema agentic; Playground se utiliza para iniciar sesiones de prueba e inspeccionar el comportamiento del agente. Playground requiere que un recurso informático de IA esté conectado a su agente.
Control de zoom	Selector de zoom de lienzo. Las capturas de pantalla muestran niveles de zoom del 60% y del 90%.

Crear un Agente

Puede crear un agente en un espacio de trabajo en el que tenga el permiso Manage.

1. En la página inicial, vaya al espacio de trabajo.
2. Haga clic en Flujos de agente en el panel de navegación de la izquierda.
3. Haga clic en Crear agente o en Crear en la parte superior derecha.
   
   

   

   
   
4. Proporcione un nombre y descripción para el agente.
5. En Modo de creación de flujo de agente, seleccione Creador visual.
   
   

   

   
   
6. Opcional: en el menú desplegable Recursos informáticos de AI, seleccione un recurso informático que utilizar para el agente.
7. Haga clic en Create. Para empezar a crear el agente, arrastre un nodo de la paleta al lienzo.

   Note:

   Inicie la creación de su primer agente de forma sencilla: un disparador de chat, un agente ejecutor. Añada complejidad después de una ejecución exitosa de su primera construcción, como rieles de protección, herramientas adicionales o incluso diseño de sistemas multiagente.

Agregar agente y disparador de chat al lienzo de Visual Builder

El primer paso después de crear un agente con Visual Builder debe ser agregar un disparador de chat y un agente supervisor.

El disparador recibe el mensaje de usuario. El supervisor interpreta la solicitud, planifica el trabajo y delega a agentes o herramientas ejecutoras. Puede arrastrar nodos en el lienzo, configurarlos y conectarlos más tarde.

1. Vaya a su agente en el espacio de trabajo.
2. Haga clic y arrastre un disparador de chat de la paleta al lienzo. El nodo aparece en el lienzo como un mensaje.
3. Haga clic y arrastre un agente de supervisor al lienzo.
   
   

   

   
   
4. Haga clic y arrastre el identificador de conector en el nodo Disparador de chat para conectarlo al nodo Agente.

La insignia Supervisor Agent muestra cuántas herramientas y agentes están conectados. En una nueva compilación, Supervisor Agent muestra: Agents (0) Tools (0).

Configuración de un agente de supervisor

Debe configurar un agente de supervisor agregado al lienzo de Visual Builder con instrucciones que describan el rol de supervisor.

Puede configurar un agente de supervisor con los siguientes campos.

Campo	Configuración
Nombre del Agente	Proporcione un nombre descriptivo para el agente supervisor. Un buen nombre descriptivo será beneficioso al depurar el comportamiento del sistema a través de rastreos y logs.
Descripción de agente	Proporcione una descripción de la finalidad, el rol y el comportamiento general del agente. Útil para fines de documentación.
Región	Seleccione la región en la que se aloja el modelo de OCI Generative AI utilizado por el agente de supervisor. Consulte Modelos de IA generativa por región.
Modelo	Seleccione el modelo de servicio de OCI Generative AI que utiliza el supervisor. En la lista desplegable se muestran los modelos disponibles en la región seleccionada.
Instrucciones del agente	Describir el rol de supervisor, las reglas de enrutamiento, la política de delegación, las expectativas de uso de herramientas y el formato de respuesta final.

1. Vaya al agente en el espacio de trabajo.
2. Haga clic en el nodo Agente de supervisor del lienzo.
3. Proporcione un nombre y una descripción minuciosos para su agente supervisor.
4. Introduzca la región y el modelo para el modelo de servicio de OCI Generative AI que utiliza el supervisor.
5. Proporcione las instrucciones del agente para su agente supervisor.

Instrucciones de supervisor sugeridas

Debe utilizar el campo Instrucciones de un agente de supervisor para que el supervisor sea responsable de la orquestación, no de realizar todas las tareas en sí.

Mantenga las instrucciones concretas para que las decisiones de enrutamiento sean predecibles. Consulte lo siguiente para ver un ejemplo de un conjunto de instrucciones de supervisor:

You are the supervisor for a multi-agent system.

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

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

Configuración del aislamiento de memoria y estado del agente del supervisor

El separador Memoria de un agente de supervisor controla la cantidad de conversaciones y el historial de salida de herramientas que están disponibles para el supervisor y la cantidad de contexto que se comparte con los agentes de ejecutor.

Configure el estado de aislamiento y memoria para el agente de supervisor con los siguientes campos.

Campo	Configuración
Activar memoria de agente	Permite activar cuando los usuarios necesitan continuidad de varias vueltas. Desactive las tareas aisladas de un solo uso. Este campo no se puede desactivar para los agentes de supervisor.
Limitar historial de conversaciones	Active esta opción para truncar la ventana de contexto del LLM después de que se alcance el límite especificado. Desactive esta opción para mostrar el historial completo.
Configuración de truncamiento	Si la opción Limitar historial de conversaciones está activada, utilice este campo para definir las condiciones para truncar la ventana de contexto. Las opciones son: Mantener últimos N mensajes Presupuesto de token Ambos
Máximo de límites de mensajes y presupuesto de token	Se muestra una o ambas opciones, según la opción que elija para Configuración de truncamiento. Los valores predeterminados son 20 mensajes y 5000 tokens. Recomendamos comenzar con valores moderados y ajustar según sea necesario.
Aislamiento de estado para agentes de ejecución	Seleccione Sin estado, Privado o Compartido. Sin estado: cada agente ejecutor solo ve la tarea asignada por el supervisor. No hay historial entre llamadas. Seleccione esta opción si desea el aislamiento más fuerte y el menor contexto entre agentes. Privado: cada agente ejecutor solo ve sus propias interacciones pasadas. No puede ver otros agentes ejecutor de la conversación de usuario original. Seleccione esta opción si el ejecutor necesita continuidad en sus propias tareas, pero no debe compartir el contexto con otros agentes. Compartido: los agentes ejecutor pueden ver el historial completo de conversaciones entre agentes y usuarios. Todos los agentes trabajan desde un contexto compartido. Seleccione esta opción si necesita compartir un contexto amplio y ha revisado los riesgos de privacidad e inyección inmediata.

1. Vaya al agente en el espacio de trabajo.
2. Haga clic en el nodo Agente de supervisor del lienzo.
3. Haga clic en el separador Memoria.
4. Seleccione si desea activar Limitar el historial de conversaciones. Seleccione una configuración de truncamiento y defina los límites, si está activada.
5. Seleccione una opción para Aislamiento de estado para agentes de ejecutor.

Separador Parámetros de Modelos

El separador Parámetros del modelo permite configurar parámetros específicos del modelo que están disponibles para el modelo seleccionado.

Los parámetros de modelo se pueden configurar por separado para los agentes de supervisor y ejecutor. Los parámetros que puede usar incluyen temperatura, K superior, P superior y penalización de frecuencia.

Note:

Solo un subjuego de modelos expone parámetros configurables. Además, los parámetros varían entre las familias de modelos.

Adición de guías de protección a un agente

Puede agregar capas adicionales de protección a los agentes agregando uno o más nodos de barrera al lienzo.

De forma predeterminada, no se aplican barandillas a los sistemas agénticos más allá de lo que el proveedor de modelos seleccionado ofrece listo para usar para sus modelos. Las guías de protección se pueden colocar entre el disparador de chat y el agente de supervisor para que se apliquen las políticas antes de que una solicitud llegue al agente de supervisor y antes de que el agente de supervisor devuelva una respuesta al emisor de la llamada.

Límite	Options	Cuándo se Utiliza
Información de Identificación Personal (PII)	Fichas Entrada y Salida Casillas de verificación de persona, dirección, número de teléfono, correo electrónico	Se utiliza cuando el flujo debe bloquear o enmascarar datos personales confidenciales antes o después del procesamiento del modelo.
Prevención de la moderación de contenido	Filas de entrada y salida con las opciones Bloquear, Informar y Permitir.	Se utiliza para definir cómo el flujo maneja el contenido de odio, sexual, violento, tóxico, despectivo o acosador.
Detección de inyección de petición de datos	Fila de entrada con las opciones Bloquear y Permitir.	Se utiliza para reducir la posibilidad de que las instrucciones maliciosas sustituyan a las instrucciones del sistema o del agente.

Para obtener más información sobre la configuración de la guía, consulte Guardrails.

1. Vaya al agente en el espacio de trabajo.
2. Arrastre un nodo Guardrails desde la paleta hasta el lienzo. Colóquelo entre el nodo Disparador de chat y el nodo Agente de supervisor.
3. Suprima la conexión entre el disparador de chat y el agente de supervisión. Para ello, pase el mouse sobre la conexión y haga clic en la X roja.
   
   

   

   
   
4. Haga clic y arrastre el identificador de conector del disparador de chat al nodo Guardrail. A continuación, haga clic y arrastre el identificador del conector desde el nodo Guardrail hasta el agente de supervisor.
5. Haga clic en el nodo Guardrail para abrir la página Configuration.
6. Configure las guías para seleccionar la acción deseada para las comprobaciones de entrada y salida.

Adición de Agentes y Herramientas de Ejecutor a un Agente

Puede agregar agentes de ejecutor a herramientas para realizar trabajos especializados para el agente de supervisor.

En el siguiente ejemplo, el agente supervisor delega a AGENT_1 y AGENT_2. AGENT_1 está conectado a las herramientas SQL_1 y HTTP_1.

1. Vaya al agente en el espacio de trabajo.
2. Arrastrar un nodo de agente de la paleta al lienzo. Los nodos de agente se deben colocar debajo de un agente superior.
3. Arrastre Herramientas desde la paleta hasta el lienzo.
4. Haga clic y arrastre el identificador de conector en el agente de supervisor para conectarse a los nodos del agente.
5. Haga clic y arrastre el identificador de conector en los agentes para conectarse a los nodos de la herramienta.

Configuración de Agente de Ejecutor

Los nodos de agente se pueden configurar modificando los valores de los separadores Configuration, Memory y Model para ayudarle a definir la finalidad de cada agente.

Los agentes se deben configurar de forma estrecha, teniendo en cuenta una función y un objetivo específicos, para que el agente supervisor pueda enrutar el trabajo de forma fiable.

Tabla 22-1 Separador Configuración de agente

Campo	Configuración
Nombre del Agente	La mejor práctica es asignar un nombre a cada agente ejecutor según su especialidad, como SQL_AGENT, DOCUMENT_AGENT, API_AGENT o SUMMARY_AGENT. El nombre de cada agente ejecutor es visible para el agente supervisor, por lo que debe utilizar nombres descriptivos.
Descripción de agente	Proporcione una descripción detallada de cada agente de ejecutor. La descripción de cada agente ejecutor es visible para el agente supervisor.
Región	Seleccione la región donde se aloja el modelo de IA generativa de OCI utilizado por el agente. Consulte Modelos de IA generativa por región.
Modelo	Seleccione el modelo de servicio de OCI Generative AI que utiliza el agente. El menú desplegable muestra los modelos disponibles en la región que ha seleccionado. Seleccione un modelo que se ajuste a la tarea del ejecutor. Los agentes de ejecutor no necesitan utilizar el mismo modelo que el agente de supervisor.
Instrucciones del agente	Describa exactamente qué debe hacer el ejecutor, qué herramientas puede utilizar y qué estructura de salida debe devolver.

Separador Memoria de Agente de Ejecutor

En el caso de los agentes de ejecutor conectados a un agente de supervisor, la memoria de los ejecutores se configura en el nodo de supervisor y se aplica a todos los agentes de ejecutor.

Campo	Configuración
Activar memoria de agente	Permite activar cuando los usuarios necesitan continuidad de varias vueltas. Desactive las tareas aisladas de un solo uso.
Limitar historial de conversaciones	Active esta opción para truncar la ventana de contexto del LLM después de que se alcance el límite especificado. Desactive esta opción para mostrar el historial completo.
Configuración de truncamiento	Si la opción Limitar historial de conversaciones está activada, utilice este campo para definir las condiciones para truncar la ventana de contexto. Las opciones son: Mantener últimos N mensajes Presupuesto de token Ambos
Máximo de límites de mensajes y presupuesto de token	Se muestra una o ambas opciones, según la opción que elija para Configuración de truncamiento. Los valores predeterminados son 20 mensajes y 5000 tokens. Recomendamos comenzar con valores moderados y ajustar según sea necesario.
Aislamiento de estado para agentes de ejecución	Seleccione Sin estado, Privado o Compartido. Sin estado: cada agente ejecutor solo ve la tarea asignada por el supervisor. No hay historial entre llamadas. Seleccione esta opción si desea el aislamiento más fuerte y el menor contexto entre agentes. Privado: cada agente ejecutor solo ve sus propias interacciones pasadas. No puede ver otros agentes ejecutor de la conversación de usuario original. Seleccione esta opción si el ejecutor necesita continuidad en sus propias tareas, pero no debe compartir el contexto con otros agentes. Compartido: los agentes ejecutor pueden ver el historial completo de conversaciones entre agentes y usuarios. Todos los agentes trabajan desde un contexto compartido. Seleccione esta opción si necesita compartir un contexto amplio y ha revisado los riesgos de privacidad e inyección inmediata.

Separador Parámetros de Modelo de Agente de Ejecutor

El separador Parámetros del modelo permite configurar parámetros específicos del modelo que están disponibles para el modelo seleccionado.

Note:

Solo un subjuego de modelos expone parámetros configurables. Los parámetros también varían según las familias de modelos.

Ejemplos de parámetros incluyen temperatura, K superior, P superior y penalización de frecuencia. Los parámetros de modelo se pueden configurar por separado para los agentes de supervisor y ejecutor.

Instrucciones de ejecutor sugeridas

You are the SQL executor agent.

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

Lista de comprobación de agentes mediante Visual Builder

Utilice esta lista como guía para asegurarse de que ha incluido y configurado todos los componentes necesarios para un agente creado con Visual Builder.

Crear lista de comprobación

• El agente tiene exactamente un punto de entrada esperado: Disparador de chat / Mensaje.
• Las barandillas se conectan en la posición deseada y se activan cuando es necesario. Recomendamos insertar barandillas entre el mensaje del disparador y el agente.
• El agente de supervisor tiene una región seleccionada, un modelo seleccionado e instrucciones de orquestación. Lo mismo para los agentes ejecutor.
• Configure la memoria del sistema de varios agentes en el separador Memory (Memoria) del agente del supervisor. Seleccione el aislamiento de estado de ejecutor que coincida con los requisitos de privacidad y continuidad.
• Cada agente ejecutor tiene una especialidad clara e instrucciones estrechas.
• Cada herramienta está conectada solo al agente que debe utilizarla.
• No hay ningún nodo desconectado.
• Un recurso informático de IA está conectado al sistema para probar herramientas individuales y para ejecutar la experiencia Playground.

Tabla 22-2 Problemas comunes

Problema	Causa probable	Acción sugerida
El supervisor no llama a un ejecutor	Las instrucciones del supervisor son demasiado vagas o no hay ningún ejecutor conectado.	Agregue reglas de enrutamiento explícitas y confirme que el nodo de ejecutor está conectado al supervisor.
El ejecutor devuelve respuestas amplias o fuera de tema	Las instrucciones del ejecutor son demasiado generales.	Reduzca el rol de ejecutor y defina la estructura de salida necesaria.
No se utiliza la herramienta	La herramienta está desconectada o conectada al agente incorrecto.	Compruebe la conexión de la herramienta y la tarjeta de identificación de recuento de herramientas de agente.
La barandilla no dispara	La sección de guía está configurada pero no activada.	Abra el nodo de guías y confirme que el conmutador de sección esté activado.
Fugas de contexto entre agentes	El aislamiento de estado se define en Compartido o la memoria es más amplia de lo previsto.	Utilice el aislamiento privado o sin estado para una separación más estricta.
Las preguntas de seguimiento pierden contexto	La memoria está desactivada o el truncamiento es demasiado agresivo.	Active la memoria y ajuste el límite máximo de mensajes.

Código de flujos de agente

Puedes llevar tu propia base de código LangGraph a los agentes de IA en Oracle AI Data Platform Workbench o crear un nuevo agente LangGraph directamente en la plataforma a través de la experiencia de codificación de agentes.

Puede utilizar la biblioteca aidputils de Python de la utilidad AI Data Platform Workbench para configurar su modelo básico e importar herramientas del sistema a su agente. Para obtener información sobre la referencia de la API helpputils, consulte API de Aidp-utils para Oracle AI Data Platform Workbench.

Puede crear un agente mediante código cargando un archivo de código existente o creando archivos de código directamente en su agente a través del editor en línea.

El editor de código en línea de los agentes soporta los siguientes tipos de archivos de código:

• Python (.py)
• JSON
• TXT
• CSV
• PSV
• RC
• Carpeta

Puede ver y navegar por los archivos de código disponibles haciendo clic en la lista desplegable del selector de archivos.

Archivos de Entrada y Dependencia

Los archivos de entrada son archivos de código que tienen la clase con métodos de configuración y llamada esperados para un agente definido como código. Oracle AI Data Platform Workbench requiere que defina un archivo de entrada para los agentes mediante código.

Los archivos de dependencia son archivos que incluyen bibliotecas de terceros requeridas por el agente definido como código. Los archivos de dependencia suelen ser archivos requirements.txt que contienen una lista de las bibliotecas de terceros necesarias.

Note:

Las bibliotecas de terceros se instalan cuando se prueba el código en el editor haciendo clic en el botón Play o cuando se prueba el agente a través del separador Test. Recomendamos instalar bibliotecas de terceros probando primero el código. Los errores durante la instalación de las bibliotecas se muestran en la celda de salida.

Clase de agente

AgentBasic es una clase de plantilla para configurar y llamar a un agente conversacional simple mediante un flujo de trabajo LangGraph con estado. Demuestra la estructura necesaria para el desarrollo mínimo de agentes con dos métodos principales:

• setup(): inicializa el flujo de trabajo del agente y define el gráfico.
• invoke(user_query, **kwargs): ejecuta el agente en un mensaje de usuario y devuelve la respuesta.

Se puede ejecutar y probar directamente mediante una función main() antes de la integración en un sistema más grande.

Definición

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

Invocación de prueba

Esta llamada de prueba es ideal para las pruebas funcionales iniciales.

Note:

Incluya un punto de entrada principal para las pruebas independientes.

import asyncio

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

Funcionamiento:

• El script crea un agente, lo configura y envía un mensaje de usuario de ejemplo.
• El agente responde ({"messages": [{"role": "ai", "content": "hello world"}]} en este ejemplo.

Guía de uso

Cree una clase Agent con los métodos de configuración y llamada.

setup()	Inicializa el flujo de trabajo del agente	agent.setup()
llamada()	Ejecuta el agente con un mensaje de usuario	await agent.invoke("Su pregunta")

• Asíncrono: invoke() es un método asíncrono; utilícelo con await o ejecútelo en un bucle asíncrono.
• Prueba: el protector main() incluido (if __name__ == "__main__":) facilita la prueba del agente antes del despliegue.

Creación de un agente a través de código por carga

Puede crear su aplicación de agente de extremo a extremo con código existente cargando su base de código LangGraph.

Oracle AI Data Platform Workbench soporta la versión 1.0.1 de LangGraph.

Note:

Puede cargar archivos y carpetas individuales hasta un máximo de 500 archivos, cada archivo puede tener un tamaño máximo de 500 MB. La carga está limitada a un tamaño total de 5 GB.

1. Vaya a su agente en el espacio de trabajo. Haga clic en el nombre del agente.
2. Haga clic en Cargar.
   
   

   

   
   
3. Arrastre y suelte un archivo en el panel o haga clic para examinar y seleccionar un archivo.
4. Haga clic en Cargar.

Creación de un agente a través de código mediante la creación de nuevo código

Puede crear su aplicación de agente completa con código existente creando código directamente en su agente a través del editor de código.

El editor de códigos admite los siguientes tipos de archivo:

• Python (.py)
• JSON
• TXT
• CSV
• PSV
• RC
• Carpetas

1. Vaya a su agente en el espacio de trabajo. Haga clic en el nombre del agente.
2. Haga clic en Agregar nuevo archivo.
   
   

   

   
   
3. Introduzca un nombre para el archivo de código.
4. Seleccione un Tipo de Archivo en la lista desplegable.
5. Haga clic en Create.

Definición de un archivo de entrada para agentes mediante código

Su agente AI mediante código requiere un archivo de entrada que tenga los métodos de clase, configuración y llamada necesarios esperados para su agente.

1. Vaya a su agente en el espacio de trabajo. Haga clic en el nombre del agente.
2. En el separador Code Editor, busque el archivo de entrada en el panel de navegación de la izquierda. Si el archivo no existe, puede cargarlo haciendo clic en Cargar o crearlo haciendo clic en Agregar nuevo archivo.
3. Haga clic con el botón derecho en el archivo de entrada y haga clic en Definir archivo de entrada. También puede seleccionar el archivo y hacer clic en el botón Definir archivo de entrada en la parte superior derecha del editor de códigos.
   
   

   

   
   

Definición de un archivo de dependencia para agentes mediante código

Debe definir un archivo de dependencia para los agentes que fluye a través del código que contiene cualquier biblioteca de terceros de la que dependa su código.

1. Vaya a su agente en el espacio de trabajo. Haga clic en el nombre del agente.
2. En el separador Code Editor, busque el archivo de dependencia en el panel de navegación de la izquierda, normalmente requirements.txt. Si el archivo no existe, puede cargarlo haciendo clic en Cargar o crearlo haciendo clic en Agregar nuevo archivo.
3. Haga clic con el botón derecho en el archivo de dependencia y haga clic en Definir dependencia. También puede seleccionar el archivo y hacer clic en el botón Definir archivo de dependencias en la parte superior derecha del editor de códigos.
   
   

   

   
   

Código de agente de prueba

Puede probar el código utilizado para el agente desde el separador Test para validar y depurar el código.

Debe tener un recurso informático de AI asociado a su agente para realizar la prueba.

1. Vaya a su agente en el espacio de trabajo. Haga clic en el nombre del agente.
2. Haga clic en el separador Playground.
   
   

   

   
   
3. Haga clic en Reproducir para probar el archivo de código seleccionado.
   
   

   

   
   

Una celda de salida en la mitad inferior de la ventana del editor de código muestra las salidas de las sentencias de impresión o registro en el código. Los errores también se muestran en la celda de salida.

Habilidades del agente en la experiencia de codificación

Las aptitudes del agente permiten a un agente detectar y utilizar instrucciones específicas de la tarea, archivos de referencia, plantillas, activos y scripts ejecutables opcionales sin codificar ese conocimiento del dominio en las instrucciones del agente.

Una aptitud se almacena como una carpeta en la base de código de agente. Cada aptitud tiene un archivo SKILL.md necesario que describe lo que hace la aptitud y cómo debe utilizarla el agente. Una aptitud también puede incluir archivos de soporte, como esquemas, ejemplos, peticiones de datos, plantillas, activos o scripts.

Para obtener más información, consulte Visión general de aptitudes del agente.

Las habilidades de los agentes respaldan un modelo de divulgación progresiva:

1. El agente descubre que existe una aptitud.
2. El agente activa la aptitud solo cuando es relevante.
3. El agente carga archivos adicionales de la carpeta de aptitudes solo cuando es necesario.
4. El agente puede ejecutar un punto de entrada de aptitud declarado explícitamente, si la aptitud lo permite.

Cuándo utilizar las aptitudes del agente

Debe utilizar Skills cuando desee empaquetar capacidades de agente reutilizables, como:

• Instrucciones específicas del dominio
• Flujos de trabajo de codificación o análisis de datos
• Orientación de generación de SQL
• Guías de procesos de negocio
• Plantillas de archivo
• Referencias del esquema
• Scripts reutilizables para cálculos, transformaciones o consultas seguros.

Las aptitudes son útiles cuando el agente debe tener acceso a conocimientos especializados y reutilizables, pero no desea colocar todos esos conocimientos directamente en la petición de datos del agente.

Cómo funcionan las aptitudes en tiempo de ejecución

En tiempo de ejecución, la aplicación host determina qué directorios de aptitudes están disponibles, como las carpetas de aptitudes de nivel de proyecto y de nivel de usuario. La plataforma carga los metadatos de cada aptitud desde SKILL.md y crea un catálogo con claves por nombre de aptitud.

A continuación, el agente puede utilizar herramientas relacionadas con aptitudes:

Herramienta	Finalidad
activate_skill(name)	Carga las instrucciones de aptitud desde SKILL.md.
list_skill_files(name, path)	Muestra los archivos disponibles dentro de una carpeta de aptitudes.
load_skill_file(name, path)	Carga un archivo de soporte desde la carpeta de aptitudes.
run_skill_entrypoint(name, entrypoint, args_json, timeout_seconds)	Ejecuta un punto de entrada de Python declarado explícitamente, si lo permite la aptitud.

Algunos entornos también pueden incorporar un resumen de las aptitudes disponibles directamente en la petición de datos del sistema. En esa configuración, el agente puede detectar las aptitudes disponibles en la petición de datos y, a continuación, utilizar activate_skill cuando necesite las instrucciones completas.

Estructura de carpetas de conocimientos

Una aptitud utiliza un diseño de carpeta de estilo Agent Skills:

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

Solo se necesita SKILL.md. Las otras carpetas son opcionales.

Carpeta o archivo	Obligatorio	Finalidad
SKILL.md	Sí	Metadatos e instrucciones de la aptitud principal.
references/	N.º	Documentación, esquemas, ejemplos o plantillas compatibles.
scripts/	N.º	Scripts de Python que se pueden ejecutar solo cuando se declaran explícitamente como puntos de entrada.
assets/	N.º	Activos estáticos utilizados por la aptitud.

Escribir SKILL.md

Cada aptitud debe incluir YAML frontmatter en la parte superior de SKILL.md, seguido de las instrucciones de rebaja.

Ejemplo básico

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

# SQL Helper

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

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

Tabla 22-3 Campos compatibles con Frontmatter

Campo	Obligatorio	Descripción
name	Sí	Nombre de aptitud único que utilizan el catálogo y las herramientas.
description	Sí	Descripción corta utilizada para detección y enrutamiento.
licencia	N.º	Política de licencia o uso de la aptitud.
compatibilidad	N.º	Nota de compatibilidad para entornos de ejecución o plataformas compatibles.
metadatos	N.º	Asignación de metadatos de cadena a cadena.
herramientas permitidas	N.º	Lista separada por espacios de herramientas que permite esta aptitud.
puntos de entrada	N.º	Lista de puntos de entrada ejecutables declarados por la aptitud.

Adición de archivos de soporte

Los archivos de soporte permiten a una aptitud mantener el contenido detallado fuera de las instrucciones principales. Esto mantiene a SKILL.md enfocado al tiempo que proporciona al agente acceso a un contexto más rico. Por ejemplo:

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

El agente puede inspeccionar estos archivos con:

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

Utilice archivos de soporte para contenido como:

• Esquemas de base de datos
• Ejemplos de API
• Plantillas de prompt
• Guías de estilo
• Glosarios de dominio
• Libros de estrategias paso a paso
• Casos de prueba o ejemplos

Creación de una aptitud ejecutable

De manera opcional, una aptitud puede exponer el comportamiento ejecutable reutilizable mediante run_skill_entrypoint. Está diseñado para operaciones controladas, como cálculos, transformaciones, validación o recuperación de datos estructurados.

Las aptitudes ejecutables deben cumplir dos requisitos:

1. La aptitud debe incluir run_skill_entrypoint en las herramientas permitidas.
2. El script se debe declarar explícitamente en la sección de puntos de entrada de SKILL.md.

Habilidad ejecutable de ejemplo

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

SKILL.md

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

# Statistics Helper

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

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

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

Reglas para puntos de entrada ejecutables

Los puntos de entrada ejecutables se restringen intencionadamente. La plataforma solo ejecuta archivos Python que son:

• Ubicado en el directorio/scripts de la aptitud
• Declarado en los puntos de entrada de la aptitud
• Permitido por la configuración allowed-tools de la aptitud

La plataforma no proporciona la ejecución arbitraria de script de propósito general. Los scripts que no se declaran en SKILL.md no se pueden ejecutar.

El ejecutor del script utiliza un timeout, el valor por defecto es 10 segundos, ejecuta Python con un comportamiento en modo aislado y aplica restricciones de ruta. Sin embargo, la ejecución basada en subprocesos no es un sandbox completo del sistema operativo. Para uso de producción, se debe considerar un mayor aislamiento, como contenedores, sistemas de archivos restringidos o controles de red.

Permisos de herramienta con allowed-tools

allowed-tools actúa como un gateway de permisos de nivel de aptitud. Para una aptitud solo de documentación, solo puede permitir herramientas de lectura de archivos:

allowed-tools: "load_skill_file list_skill_files"

Para una aptitud que puede ejecutar scripts declarados, incluya run_skill_entrypoint:

allowed-tools: "load_skill_file list_skill_files run_skill_entrypoint" 

No agregue run_skill_entrypoint a menos que la aptitud necesite realmente un comportamiento ejecutable.

Cómo dejar que tus agentes descubran y usen habilidades

Para complementar al agente con aptitudes, debe instanciar un catálogo de aptitudes, un middleware de aptitudes y convertir las aptitudes en herramientas mediante los siguientes objetos de la biblioteca helppUtils:

Herramienta	Finalidad
discover_skill_catalog	Determinar las ubicaciones de búsqueda de aptitudes por defecto (proyecto + usuario) Crear un catálogo de aptitudes a partir de directorios detectados
SkillMiddleware	Agregar resumen de aptitudes disponibles y reglas de enrutamiento a la petición de datos del sistema. Proporcionar asistentes de fábrica para la construcción de middleware basada en el espacio de trabajo.
make_skill_tools	Este método devuelve las herramientas de detección de aptitudes: activate_skill, list_skill_files, load_skill_file y run_skill_entrypoint. Estas herramientas las puede utilizar el agente para activar y ejecutar diferentes aptitudes.

A continuación, se muestra un ejemplo de lo que incluiría el archivo de entrada:

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

Puede depurar el catálogo de aptitudes agregando esta sentencia de registrador al código. De esta forma se imprimirán todas las aptitudes detectadas en el catálogo de aptitudes:

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

Prioridad de aptitudes

La plataforma puede cargar aptitudes desde varias ubicaciones, como directorios de nivel de proyecto y de usuario. El catálogo agrega esas ubicaciones en una única lista de aptitudes con clave de nombre.

Cuando varios almacenes contienen una aptitud con el mismo nombre, la prioridad determina cuál se utiliza. Las tiendas posteriores sustituyen a las anteriores, lo que permite a una aplicación host controlar si las aptitudes de nivel de usuario, las aptitudes de nivel de proyecto o las aptitudes de nivel de espacio de trabajo tienen prioridad.

Mejores prácticas de creación de aptitudes

Mantener SKILL.md enfocado

Utilice SKILL.md para las instrucciones básicas que el agente necesita inmediatamente después de la activación. Ponga esquemas largos, ejemplos y material de referencia en referencias/.

Escribir descripciones claras

El campo de descripción se utiliza para la detección. Haga que sea lo suficientemente específico para que el agente sepa cuándo activar la aptitud.

Adecuado:

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

Menos útil:

description: Helps with data.

Utilizar nombres de punto de entrada explícitos

Los nombres de los puntos de entrada deben describir claramente la operación:

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

Evite nombres vagos como:

entrypoints: 
   - name: run 
   - name: do_it 

Devolver resultados estructurados

Los scripts ejecutables deben devolver resultados serializables de JSON siempre que sea posible. Esto facilita que el agente inspeccione y utilice la salida.

Evitar la ejecución innecesaria

Preferir instrucciones y archivos de referencia cuando sea posible. Utilice puntos de entrada ejecutables solo para operaciones que realmente requieren código.

Agregar una nueva aptitud

Puede agregar nuevas aptitudes de agente creando una nueva carpeta dentro del directorio de aptitudes y agregando los archivos y carpetas necesarios.

1. Cree una carpeta en el directorio de aptitudes: .agents/skills/<skill-name>/.
2. Agregue un archivo SKILL.md con el frontmatter necesario.

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

3. Escriba las instrucciones de la aptitud en Markdown debajo de frontmatter.
4. Agregue archivos de soporte opcionales en:

   references/
   assets/
   scripts/
   

5. Si la aptitud es ejecutable, agregue run_skill_entrypoint a allowed-tools, declare entrypoints en SKILL.md y coloque la implantación de Python en scripts/.

Adición de una nueva capacidad ejecutable a una aptitud existente

Puede agregar una nueva operación ejecutable a una aptitud existente para ampliar las capacidades de SKILL.md.

1. 1. Agregue un archivo Python en el directorio scripts/ de la aptitud.

   .agents/skills/<skill-name>/scripts/my_operation.py 

2. 2. Implante una función run(...).

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

3. 3. Agregue un punto de entrada coincidente a SKILL.md.

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

4. 4. Pruebe el punto de entrada con un objeto JSON como argumentos.

   {
     "input_text": "hello"
   }
   

Solución de problemas de aptitudes de agente

Si tiene problemas con la implantación de aptitudes de agente, consulte esta lista para obtener ayuda para resolver el problema.

El agente no ve mi aptitud

Compruebe lo siguiente:

• La carpeta de aptitudes se encuentra en un directorio de aptitudes configurado.
• La carpeta contiene SKILL.md.
• SKILL.md tiene frontmatter YAML válido.
• El material frontal incluye tanto el nombre como la descripción.

El agente activa la aptitud incorrecta

Compruebe si hay nombres de aptitudes duplicados en los directorios de aptitudes. Si dos aptitudes tienen el mismo nombre, la prioridad del catálogo determina cuál se utiliza.

No se puede cargar un archivo de soporte

Compruebe lo siguiente:

• El archivo está dentro de la carpeta de aptitudes.
• La ruta no incluye traversales como ../.
• El archivo no está oculto.
• El archivo no se excluye, como __pycache__ o .pyc.

No se ejecutará un punto de entrada

Compruebe lo siguiente:

• run_skill_entrypoint está incluido en las herramientas permitidas.
• El punto de entrada se declara en SKILL.md.
• La ruta de acceso del script está en scripts/.
• El script es un archivo .py.
• El nombre de la función en func existe en el script.
• Los argumentos son un objeto JSON válido.

Timeout de punto de entrada

Aumente timeout_seconds solo si se espera que la operación tarde más tiempo. Para operaciones de larga ejecución o que requieren muchos recursos, considere mover la operación a un servicio dedicado o a un entorno de ejecución más aislado.

Ejemplo: Completar la aptitud del agente

En este ejemplo se muestra cómo sería una aptitud de agente completa después de la implantación.

Estructura de carpetas

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

SKILL.md

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

# Customer Support Reply

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

Workflow:

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

Prueba de agente

Puede probar los agentes para obtener una previsualización y depurar su salida. También puede crear y gestionar sesiones de prueba para explorar diferentes escenarios de prueba para los agentes.

El primer paso para probar un agente es asociar el agente a un recurso informático de AI. La acción de asociar un agente transfiere una copia de su agente a un recurso informático de AI. Siempre que su agente esté asociado a un recurso informático de AI, los cambios que haya realizado en su agente se propagarán al recurso informático asociado cada vez que haga clic en el botón Test.

Después de hacer clic en el botón Test, se le lleva al patio de pruebas.

El patio de pruebas tiene los siguientes componentes:

• Ventana de chat en la que puede iniciar una sesión y empezar a chatear con el agente o reanudar una sesión existente
• Representación basada en gráficos del agente
• Panel que muestra un árbol de rastreos y períodos generados durante la sesión
• Panel del explorador de rastreos e intervalos que muestra los atributos de rastreos e intervalos, entrada/salida. El separador Detalles incluye ID, hora de inicio y finalización, hora de ejecución, mientras que los separadores Eventos resaltan los errores durante la ejecución.

El Playground le permite interactuar y probar cada agente de forma independiente si desea hacerlo. Por defecto, el agente de supervisor está seleccionado, pero puede elegir chatear con cada agente de ejecutor y probarlo de forma independiente. Esto le permite simular el comportamiento de un agente supervisor que emite solicitudes a agentes ejecutores. Para ello, seleccione el agente que desea probar en el menú desplegable de la ventana de chat.

Los rastreos y los períodos se muestran en el panel central tan pronto como se crea el primer mensaje. Cada tarea corresponde a un mensaje de usuario diferente. Puede hacer clic en el cursor izquierdo para ampliar el rastreo e inspeccionar los intervalos.

Prueba a tus agentes en el patio

Puede probar el creador visual y los agentes basados en LangGraph desde el patio de juegos Test para validar y depurar los agentes.

Debe tener un recurso informático de AI asociado a su agente para realizar la prueba. Puede agregar un nuevo cluster de recursos informáticos de AI siguiendo Crear un cluster de AI para un agente o asociar un cluster de recursos informáticos de AI existente siguiendo Asociar un cluster de AI existente a un agente.

1. Vaya a su agente en el espacio de trabajo. Haga clic en el nombre del agente.
2. En la parte superior del lienzo, haga clic en Zona de reproducción. Puede tardar varios segundos en transferir el agente a los recursos informáticos asociados.
   
   

   

   
   

Su agente se muestra en el patio de pruebas.

Creación de una sesión de prueba de agente

Puede crear una sesión de prueba para iniciar una nueva conversación con el agente.

Todas las sesiones creadas en el destino del patio de pruebas en el que se aloja el agente en el recurso informático asociado. Una vez que se crea una sesión, se puede reanudar más tarde.

1. Vaya a su agente en el espacio de trabajo. Haga clic en el nombre del agente.
2. En la parte superior del lienzo, haga clic en Taller.
3. En el selector de sesiones, haga clic en Crear una sesión.
   
   

   

   
   
4. Inicie un cuadro de diálogo con el agente introduciendo una consulta en el cuadro de chat.
   
   

   

   
   

Reanudación de una sesión de prueba de agente

Puede reanudar las sesiones de prueba de agente que ha creado anteriormente.

Note:

Sólo puede reanudar las sesiones que haya creado.

1. Vaya a su agente en el espacio de trabajo. Haga clic en el nombre del agente.
2. En la parte superior del lienzo, haga clic en Playground.
3. En la lista desplegable Session, seleccione una sesión anterior.
   
   

   

   
   
4. Reanude el cuadro de diálogo con el agente introduciendo una consulta en el cuadro de chat.

Supresión de una sesión de prueba de agente

Puede suprimir sesiones de prueba para agentes alojados en los recursos informáticos y las sesiones de AI asociados que se han creado en un agente desplegado.

1. Vaya a su agente en el espacio de trabajo.
2. Haga clic en el separador Sesiones.
   
   

   

   
   
3. Junto a la sesión que desea suprimir, haga clic en Acciones y, a continuación, en Suprimir.
   
   

   

   
   
4. Haga clic en Suprimir.

Acerca de las herramientas de agente

Oracle AI Data Platform Workbench admite plantillas de herramientas que se pueden configurar para acceder a sus datos y adaptarse a sus casos de uso.

Los agentes soportan configuraciones que constan de un único agente que puede interactuar con una o más herramientas. Oracle AI Data Platform Workbench 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 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 flujo de agente mediante código LangGraph

Agregue herramientas RAG, SQL y Prompt 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 o RAGTool.
• 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 flujo de 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 22-4 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
ID_modelo	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 22-5 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 flujos 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 flujos 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 22-6 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 flujo completo del agente. 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.

Memoria del agente

La memoria del agente es la parte de un sistema de agente de AI que permite al agente retener y reutilizar información en turnos, tareas o sesiones.

A diferencia de la ventana de contexto del modelo, que es temporal y se limita a la petición de datos actual, la memoria puede persistir en hechos, preferencias, decisiones previas, salidas de herramientas, planes intermedios u observaciones sobre el entorno.

Memoria del agente en AI Data Platform

AI Data Platform proporciona memoria a corto plazo que se limita a la duración de una sesión. Puede configurar lo que se puede mantener en memoria en el separador Memory de su agente.

Configuración de memoria de un solo agente

La configuración de memoria de un único sistema de agente se puede encontrar en el separador Memoria del nodo de agente.

Configuración de Memoria	Descripción
Activar memoria de agente	Esta configuración activa la memoria del agente. Cuando se desactiva, el agente es esencialmente un sistema sin estado. Cada turno se trata de forma independiente, y no se puede hacer ninguna pregunta de seguimiento. Recomendamos que la memoria esté activada.
Limitar historial de conversaciones	Cuando esta selección está desactivada, las vueltas anteriores llenarán la memoria hasta que el modelo se quede sin contexto y se devuelva un error. Si se esperan sesiones cortas, se puede desactivar esta configuración. Sin embargo, en la mayoría de los casos de uso se recomienda limitar el historial de conversaciones.
Configuración de truncamiento	Si opta por limitar el historial de conversaciones, puede decidir truncar el historial: Mantener solo los últimos N mensajes (usuario + agente) Establecer un presupuesto de token general (primero en entrar, primero en salir) O ambos, cualquiera que sea el primero, disparan el truncamiento de la memoria del agente
Límites máximos de mensajes	Si decide mantener los últimos N mensajes, puede establecer un valor de N.
Presupuesto de token	También puede definir un presupuesto de token global. Los primeros tokens se eliminan para mantener los más recientes en memoria.

Configuración de memoria del sistema de varios agentes (patrón de supervisor)

La memoria de un sistema de varios agentes se configura en el separador Memoria del agente supervisor.

La memoria de un sistema de varios agentes se aplica y no se puede desactivar, y las opciones de truncamiento de memoria que se muestran en el nodo de agente de supervisor solo se aplican a la memoria del agente de supervisor. Cada política de truncamiento de memoria del agente de ejecutor se puede configurar en el separador Memoria del nodo de ejecutor según la política de aislamiento de estado seleccionada para todo el sistema.

La configuración de memoria del sistema de varios agentes también permite seleccionar la política de uso compartido de memoria de los agentes ejecutores. Tres opciones son posibles: sin estado, privado y compartido. Tenga en cuenta que la política se aplica a todos los agentes de ejecutor.

Aislamiento de estado para agentes de ejecución	Descripción
Sin Estado	Cada agente ejecutor solo ve la tarea asignada por el supervisor. No hay historial entre llamadas. El agente ejecutor no puede realizar ninguna solicitud de seguimiento al agente supervisor. Si se selecciona sin estado, la memoria de cada agente de ejecutor se desactiva.
Privada	Cada agente ejecutor solo ve sus propias interacciones pasadas. No puede ver otros agentes ejecutor ni la conversación de usuario original con el agente supervisor.
Compartidos	Los agentes ejecutor pueden ver el historial completo de conversaciones entre agentes y usuarios. Todos los agentes trabajan desde un contexto compartido. Si se selecciona Compartir, puede configurar la política de truncamiento de memoria por separado para cada agente ejecutor en cada separador Memoria de nodo de agente.

Variables de sesión

Puede utilizar variables de sesión personalizadas y definidas por el agente para proporcionar puntos de datos contextuales adicionales a los agentes durante una sesión de usuario.

¿Qué son las variables de sesión?

Las variables de sesión personalizadas y definidas por el agente proporcionan puntos de datos contextuales adicionales al agente durante una sesión de usuario. Las variables se pueden utilizar para una variedad de propósitos, incluyendo la configuración de valores de parámetros en herramientas, dando instrucciones generales a un agente, y proporcionando información contextual sobre el emisor de llamada y/o la aplicación donde el agente está embebido.

A continuación, se muestra un escenario simplificado en el que estamos creando un agente de soporte al cliente. El agente de soporte al cliente está integrado en un sitio web minorista. Cuando un usuario inicia sesión en el sitio web minorista, la información sobre ese usuario es capturada por la aplicación cliente (ID de usuario, nombre de usuario, ubicación geográfica, dispositivo utilizado, ID de carro de compra, etc.) y esa información podría ser utilizada por el agente de soporte descendente. Veamos un ejemplo de cómo se podrían utilizar estos parámetros de sesión en el campo de instrucciones de agente de AIDP:

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

En el ejemplo anterior se utilizan tres variables de sesión:

• userName
• Saludo preferido
• Grupo de usuarios actuales

El agente no tiene conocimiento previo del usuario que interactúa con el sitio web minorista, no sabe cuál es la ubicación del usuario o no tiene contexto sobre lo que hay en el carrito de la compra del usuario. En principio, la aplicación cliente podría conocer todos o un subconjunto de esos valores y transferir esos valores en una solicitud al agente. A continuación, se muestra un ejemplo del aspecto que podría tener una solicitud al agente, incluidos los parámetros de sesión.

Note:

Este ejemplo ilustra el aspecto que podría tener esta solicitud. No es representante de una decisión de implantación.

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

El agente respondería: "Hola señor Paul, ¿cómo es el clima hoy en Cancún, Mx?"

Otro uso de estos parámetros de sesión es la definición de valores de parámetros en las herramientas. Por ejemplo, una consulta SQL puede recuperar el contenido de un carro de compra mediante el parámetro de sesión {{sessionParam.CartID}} :

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

Las variables de sesión las define el desarrollador del agente cuando crea sus agentes y los valores de esos atributos los define la aplicación cliente cuando se crea o reanuda una sesión.

Puede configurar los siguientes valores al crear una nueva variable de sesión:

Valor	Descripción
Variable necesaria	Active esta opción para que esta variable de sesión sea necesaria para cada llamada de llamada del agente. La desactivación hace que la variable de sesión sea opcional para cada llamada de llamada.
Variable de log	Active esta opción para capturar el valor de la variable de sesión en logs y rastreos. La desactivación impide que la variable aparezca en los logs. Recomendamos desactivar este valor para variables con datos confidenciales.
Nombre	Nombre de la variable de sesión. Utilice un nombre descriptivo para que tanto usted como otros usuarios puedan determinar fácilmente la finalidad de la variable.
Valor por defecto	Si se define, el valor por defecto se asigna a la variable de sesión si no se define otro valor en la llamada de llamada. Si se deja en blanco, se debe asignar un valor como parte de la llamada de llamada.
Descripción	Descripción de la variable de sesión. Proporcione una descripción útil para que usted y otros usuarios puedan comprender la función de la variable de sesión.

Ejemplo: uso de variables de sesión en la configuración de herramientas

Puede utilizar una variable de sesión en una configuración de herramienta SQL como parte de la propia consulta SQL.

En este ejemplo, la variable de sesión geo se utiliza para filtrar el resultado de la consulta SQL:

Puede utilizar variables de sesión y parámetros de herramienta en la misma consulta. En el siguiente ejemplo, el agente define el parámetro titleID mientras que la variable de sesión geo la proporciona la aplicación que realiza la llamada.

Variables de sesión generadas por el sistema

Las variables de sesión se generan automáticamente cuando un servidor MCP remoto está conectado a un agente y ese servidor MCP requiere autenticación, como un token portador.

La variable de sesión contiene el valor del token portador. El nombre de esta variable de sesión generada por el sistema no se puede cambiar y es una variable necesaria. La variable del sistema se suprime cuando el nodo MCP se elimina del lienzo.

En Playground, se proporciona un valor para la variable de sesión generada por el sistema. En este caso, debe proporcionar un token de portador para utilizar el servidor MCP. Puede seleccionar el mismo token (o un token diferente) que utilizó durante la configuración del nodo MCP.

Lo mismo se aplica si despliega el agente. Deberá proporcionar un token de autorización. Para obtener más información, consulte Asignación de valores a variables de sesión desde el patio de recreo.

Ejemplo: asignación de valores a variables de sesión al llamar a un punto final desplegado

En este ejemplo, tiene dos variables de sesión: userLocation y UserName, la aplicación cliente está transfiriendo valores de variables de sesión mediante el campo metadata de body. Mostraremos cómo puede asignar valores a través de Python y de la CLI de OCI.

Si utiliza la biblioteca de solicitudes de Python, la carga útil es la siguiente:

body = { 

            "isStreamEnabled" : False, 

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

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

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

Como alternativa, si utiliza la CLI de OCI, la carga útil es la siguiente:

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

Creación de una variable de sesión en el separador Variables de agente

Puede crear una nueva variable de sesión y agregarla al agente desde el separador Variables.

1. Navegue hasta el agente al que desea agregar una variable de sesión.
2. Haga clic en el separador Variables.
   
   

   

   
   
3. Haga clic en Agregar variable de sesión.
   
   

   

   
   
4. Seleccione esta opción si la variable de sesión es obligatoria.
5. Seleccione si el valor de la variable de sesión se debe registrar en logs y rastreos. Deje esta configuración desactivada para los datos confidenciales.
6. Proporcione un nombre y descripción significativos para la variable de sesión.
7. Proporcione un valor por defecto para la variable de sesión. El valor por defecto se asigna a la variable de sesión si no se asigna ningún otro valor como parte de la llamada de llamada.
8. Haga clic en Create.

Consulte las variables de sesión en las instrucciones de flujo de agente

Puede consultar las variables de sesión en las instrucciones del agente y las configuraciones de la herramienta, incluida la consulta de la herramienta SQL y Prompt.

1. Navegue hasta el flujo de agentes.
2. Haga clic en el nodo de la herramienta SQL o Prompt en Playground.
   
   

   

   
   
3. En el campo Consulta, comience a escribir {{sessionvariables.
4. Seleccione la variable de sesión de la lista de variables de sesión existentes.

Visualización de Agentes y Herramientas mediante una Variable de Sesión

Puede ver una lista de agentes y herramientas mediante una variable de sesión específica en el separador Variable del flujo de agente.

1. Navegue a un flujo de agente mediante la variable de sesión para la que desea ver los agentes y las herramientas relacionados.
2. Haga clic en el separador Variable.
3. Junto a Utilizado en: para la variable de sesión, haga clic en el menú desplegable. Se muestra una lista de agentes y herramientas que utilizan la variable de sesión.

Asignación de Valores a Variables de Sesión desde el Área de Juego

Puede asignar valores a variables de sesión en cualquier momento desde el separador Playground.

1. Navegue hasta el flujo de agentes.
2. En la parte superior del área de juegos, haga clic en Parámetros de sesión. Se muestra una lista de todas las variables de sesión en el flujo de agente.
   
   

   

   
   
3. Modifique las variables de sesión. Después de reanudar la sesión de Playground, se utilizan los últimos valores de variables de sesión asignados.
   
   

   

   
   

Límite

Las barandillas son mecanismos de seguridad para guiar y controlar el comportamiento de los agentes de IA.

En Oracle AI Data Platform Workbench, las guías de protección se configuran para evitar la generación o el consumo de contenido tóxico y malicioso por flujos de agentes. Las barandillas también previenen la fuga de información de identificación personal (PII) por el flujo del agente. Las guías específicas disponibles en el área de trabajo de la plataforma de datos de IA se aplican a la moderación del contenido, la inyección de mensajes y la PII.

Note:

Las barandillas que ofrece Oracle AI Data Platform Workbench solo están disponibles en inglés.

Las barandillas que se ofrecen en AI Data Platform Workbench son implementadas por el equipo de servicio de OCI Generative AI. Consulte Guardrails for OCI Generative AI. En función de la configuración de las guías, el servicio AI Data Platform Workbench llama a la API de aplicaciones de guías en su arrendamiento de OCI.

Barandillas en lienzo de flujo visual

Por defecto, no se aplican barandillas al sistema más allá de los controles de seguridad nativos del proveedor del modelo. Para agregar barandillas, debe arrastrar un nodo de barandillas al creador de flujos visuales del agente y conectarlo al agente.

Un nodo de guías de protección puede filtrar el tráfico entre un disparador de chat y un nodo de agente, entre un supervisor y un agente ejecutor, o entre nodos de agente y herramienta. Para la mayoría de los escenarios, recomendamos un único nodo de guías de protección entre el disparador de chat y el nodo de agente. Esto garantizará que los mensajes del usuario entrante y los mensajes generados por el agente se filtren mediante las guías.

El nodo de guías de protección solo se puede insertar entre:

• Un nodo disparador de chat y un agente (supervisor o ejecutor)

¿Qué barandillas están disponibles?

En el diagrama siguiente se muestra una interacción sencilla entre un usuario final y un agente. En este escenario, se aplican todas las guías (moderación de contenido – CM, prevención de inyección inmediata – PI y detección de PII – PII). PI solo se aplica a la consulta del usuario.

Después del segundo mensaje emitido por el usuario final, se detectó un intento de PI y el mensaje de usuario se bloqueó después de la acción seleccionada por el desarrollador del agente en la detección de PI (bloque).

Moderación del Contenido

La moderación de contenido es una implementación común de barandillas en la mayoría de la IA generativa. Sin marcar, los LLM pueden generar contenido dañino, promover contenido violento, racista y sexualmente explícito. Es imprescindible proporcionar a los desarrolladores de agentes visibilidad y control completos sobre cómo se supervisan y exploran las interacciones de los usuarios con los agentes en busca de contenido potencialmente dañino. La moderación del contenido impide que el contenido de odio, sexual, violento, tóxico, despectivo o basado en el acoso sea considerado o generado por el flujo de agentes. Nuestro modelo de barandillas clasifica el contenido a lo largo de esas seis categorías y marca el contenido que pertenece a una de esas categorías.

Puede realizar una acción en la consulta de entrada de usuario o en la respuesta del modelo:

• Bloquear: evita que el agente procese la entrada del usuario y genere una respuesta. Los usuarios reciben una respuesta de error del flujo de agente.
• Informar: permite que el flujo de agente procese la entrada de usuario y genere una respuesta. El agente notifica al usuario que la entrada o la respuesta contienen contenido que cumple los criterios de la guía.
• Permitir: permite procesar y/o generar contenido potencialmente dañino por el flujo de agente.

La acción Bloquear se selecciona para moderación de contenido al crear un flujo de agente. Oracle recomienda mantener Block como selección de guía para la moderación de contenido.

Petición de datos de inyección

Las barandillas de inyección rápidas para agentes de IA son un mecanismo de protección que detecta, previene y mitiga las instrucciones maliciosas o no deseadas incrustadas en las entradas del usuario. Los ataques de inyección de petición de datos intentan anular o subvertir las instrucciones, políticas o objetivos originales del agente insertando texto oculto que indica al modelo que ignore las reglas anteriores, filtre secretos o ejecute acciones no autorizadas.

Puede elegir las mismas acciones que se pueden realizar para la moderación del contenido: bloquear, informar o permitir. Las guías de inyección de petición de datos solo se aplican a la consulta de entrada de usuario.

• Bloquear: impide que el agente procese la entrada del usuario. Los usuarios reciben una respuesta de error del flujo de agente.
• Informe: permite que el flujo de agente procese la entrada de usuario. El agente notifica al usuario que la entrada contiene contenido que cumple los criterios de la guía.
• Permitir: permite el procesamiento de contenido potencialmente dañino por el flujo de agente.

La acción Bloquear se selecciona como inyección de petición de datos al crear un flujo de agente. Oracle recomienda mantener Block como su selección de guía para la inyección de petición de datos.

Información de identificación individual (PII)

Las guías de protección de PII detectan, bloquean o enmascaran automáticamente la PII de las consultas de entrada del usuario o de las respuestas de los agentes. Esta barrera evita que el agente exponga información confidencial del usuario de formas que violen las regulaciones de privacidad o las políticas organizativas.

Las guías de protección de PII soportan cuatro tipos de entidad:

• Correo electrónico
• Número de teléfono
• Dirección Física
• Nombre persona

Para cada una de esas cuatro entidades, decide aplicar cuál de las siguientes acciones realiza su agente en la consulta de usuario de entrada o en la respuesta del agente:

• Bloquear: impide que el agente procese la entrada del usuario y genere una respuesta. Los usuarios reciben una respuesta de error del flujo de agente.
• Informar: permite que el flujo de agente procese la entrada de usuario y genere una respuesta. El agente notifica al usuario que la entrada o la respuesta contienen información de identificación personal.
• Máscara: permite que el flujo de agente procese la entrada y genere una respuesta enmascarada. Cualquier información de identificación personal utilizada se elimina para evitar la exposición.
• Permitir: permite procesar y/o generar datos de PII por el flujo de agente.

En un nuevo flujo de agente, la PII se permite tanto en la entrada de usuario como en la respuesta por defecto. Oracle recomienda seleccionar cuidadosamente la guía para la PII en función de sus necesidades de seguridad.

Activación de guías de protección específicas en un nodo

Puede elegir qué barandillas activar y cómo se configura cada una al agregar un nodo de barandilla al lienzo visual.

1. Navegue al flujo de agente en el espacio de trabajo.
2. Arrastre un nodo Guardrails de la paleta al lienzo.
3. Proporcione un nombre y descripción significativos para el nodo.
   
   

   

   
   
4. Conmute una guía para activarla y comenzar a configurarla. Al pulsar de nuevo el conmutador, se desactiva la guía y sus configuraciones.
   
   

   

   
   
5. Seleccione la configuración de barandilla necesaria para cada categoría.
   
   

   

   
   

Creación de un cluster de AI para un agente

Puede crear un nuevo cluster de AI directamente desde la interfaz del agente y asociarlo inmediatamente.

Para obtener más información, consulte AI Compute.

1. En la página inicial, vaya a su agente.
2. Haga clic en Recursos informáticos y, a continuación, en Crear un nuevo recurso informático de IA.
3. Proporcione un nombre y una descripción para el cluster de recursos informáticos de AI.
4. Seleccione el número de OCPU y el tamaño de memoria para el cluster de recursos informáticos de AI.
5. Haga clic en Create.

Asociación de un cluster de AI existente a un agente

Puede asociar un cluster de AI que haya creado anteriormente a un agente en el que tenga al menos permisos de uso.

1. En la página inicial, vaya a su agente.
2. Haga clic en Recursos informáticos y, a continuación, en Asociar a AI Compute.
3. Haga clic en el cluster que desea utilizar de la lista.
   El agente muestra AIcompute: (ClusterName) running cuando se ha asociado correctamente. Esto puede tardar hasta varios minutos.

Desasociación de un agente de AI Compute

Puede desasociar un agente de un recurso informático de AI. Al desasociar el recurso informático AI, se elimina el código del agente que se ejecuta en el recurso informático asociado y se evita la realización de pruebas.

Note:

Al desasociar un agente de AI Compute, no se suprime el agente. Puede reanudar la creación y la prueba del agente asociándolo al mismo recurso informático AI o a otro diferente.

1. En la página inicial, vaya a su agente.
2. Haga clic en Recursos informáticos y, a continuación, en Desasociar de AI Compute.
   
   

   

   
   

Despliegue de agente A2A

El protocolo Agent2Agent (A2A) es un estándar abierto para la comunicación entre agentes de IA independientes, incluidos los agentes creados con diferentes marcos, alojados por diferentes proveedores o que se ejecutan como sistemas remotos opacos.

Su objetivo es dar a esos agentes un modelo de interacción compartida para que puedan descubrir las capacidades de los demás, negociar formatos de entrada/salida soportados, delegar o colaborar en tareas e intercambiar información de forma segura sin exponer la memoria interna, las herramientas o los detalles de implementación. Para obtener más información, consulte Agent2Agent (A2A) Protocol.

A2A está diseñado para resolver la interoperabilidad de los agentes: en lugar de que cada integración de agentes sea personalizada, un cliente u otro agente pueden interactuar con cualquier agente remoto compatible con A2A mediante un conjunto común de conceptos y operaciones. La especificación se centra en mensajes, tareas, piezas, artefactos, actualizaciones de transmisión y notificaciones push; admite respuestas síncronas, trabajo asíncrono de larga ejecución, transmisión y patrones de seguridad y autenticación de estilo empresarial.

En Oracle AI Data Platform, todos los agentes desplegados reciben una ruta de acceso de llamada /A2A que pueden llamar las aplicaciones cliente A2A.

¿Qué es una tarjeta de agente?

Una tarjeta de agente es un documento de metadatos JSON publicado por un servidor A2A. En AIDP, el servidor A2A es el recurso informático AI que aloja el despliegue de su agente.

La tarjeta describe la identidad del agente, el punto final de servicio, los protocolos/transportes soportados, las capacidades, las aptitudes, los modos de entrada/salida soportados y los requisitos de autenticación; los clientes la utilizan para detectar si el agente es adecuado y cómo llamarlo. Una tarjeta de agente debidamente documentada es un requisito del protocolo A2A.

Las tarjetas de agente en AI Data Platform Workbench están en estado Borrador, lo que significa que el agente no se ha desplegado o Publicado, lo que significa que la tarjeta se ha desplegado junto con el agente.

Acciones de tarjeta de agente

Durante el desarrollo de un agente, la tarjeta está disponible en el menú Actions del agente.

Se puede acceder a dos tarjetas de agente:

• El borrador de la tarjeta refleja el estado actual del agente en desarrollo.
• La tarjeta publicada corresponde a una instantánea de la tarjeta tomada cuando se desplegó el agente. La tarjeta publicada refleja el estado del agente desplegado.

Campos de tarjeta de agente

AI Data Platform Workbench soporta un subjuego de los campos de tarjeta de agente de protocolo A2A actuales, disponibles aquí: A2A Protocol - Agent Card.

Campo	Obligatorio	Descripción
name	Sí	Nombre legible por el usuario para el agente. Ejemplo: "Recipe Agent"
description	Sí	Descripción del agente en lenguaje natural, que ayuda a los usuarios y otros agentes a entender su propósito. Ejemplo: "Agente que ayuda a los usuarios con recetas y cocina".
Agent Version	Sí	Versión del agente. Ejemplo: "1.0.0"
Documentation URL	N.º	URL que proporciona documentación adicional sobre el agente.
Provider - Organization	N.º	Proveedor de servicios del agente.
Provider - URL	N.º	URL del proveedor de servicios.
Capabilities	Sí	Juego de capacidades A2A soportado por el agente. Solo se puede configurar streaming (Verdadero/Falso)
Skills	Sí	Las habilidades representan las habilidades de un agente. Es en gran medida un concepto descriptivo, pero representa un conjunto más centrado de comportamientos en los que es probable que el agente tenga éxito. Las aptitudes representan una matriz de AgentSkill.

Cada AgentSkill está formado por varios campos que documentan las capacidades del agente. La definición de las aptitudes del agente en la tarjeta de agente es la operación que más tiempo requiere y es un proceso iterativo. Las aptitudes se pueden editar (junto con el resto de la tarjeta de agente) en la tarjeta de agente provisional antes del despliegue.

Note:

AI Data Platform Workbench proporciona inputModes, outputModes y securityRequirements y no se puede modificar.

Campo	Obligatorio	Descripción
Skill ID	Sí	Identificador único de la aptitud del agente.
Skill Name	Sí	Nombre legible por el usuario para la aptitud.
Description	Sí	Descripción detallada de la aptitud.
Tags	Sí	Conjunto de palabras clave que describen las capacidades de la aptitud.
Examples	N.º	Ejemplo de peticiones de datos o escenarios que puede manejar esta aptitud.

Ruta de punto final de despliegue de agente A2A

Una ruta /a2a se expone en la URL de un agente desplegado además de /chat.

Por ejemplo, un agente expondrá estas rutas a clientes externos:

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

Ambas rutas (/chat, /a2a) pueden ser consumidas por clientes independientes.

Variables de sesión en A2A

Los valores de las variables de sesión se pueden transferir a un agente A2A en el campo metadata del mensaje. El siguiente fragmento de JSON muestra la carga útil de un mensaje de usuario emitido al agente a2a con tres variables de sesión: userName, geoLocation y os:

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

Ejemplo: llamada a un agente A2A con la CLI de OCI (no streaming)

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

Ejemplo: llamada a un agente A2A con la CLI de OCI (streaming)

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

Ejemplo: SDK de cliente A2A

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

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

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

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



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


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

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

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

            response = await client.send_message(request)

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


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

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

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


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

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

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

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

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

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

Editar tarjeta de agente provisional

Puede editar la tarjeta de agente para un agente que aún no se ha desplegado.

1. Vaya a su agente.
2. Haga clic en Acciones y, a continuación, en Ver tarjeta de agente y Borrador de tarjeta de agente.
   
   

   

   
   
3. Haga clic en Editar.
   
   

   

   
   
4. Puede cambiar la vista haciendo clic en Formulario o JSON en la parte superior derecha. La vista JSON es más completa, pero de solo lectura. Solo puede editar campos en la vista Formulario.
   
   

   

   
   
5. Modifique los campos según sea necesario.
6. Haga clic en Agregar una aptitud para agregar las aptitudes que desea exponer a los clientes A2A.
   
   

   

   
   
7. Haga clic en Guardar.

Editar una tarjeta de agente publicada

Puede modificar una tarjeta de agente publicada sin tener que anular el despliegue o volver a desplegar un agente.

La tarjeta publicada corresponde a una instantánea de la tarjeta de borrador en el momento del despliegue.

Note:

Los cambios que realice en una tarjeta publicada se reflejan inmediatamente en el archivo agent-card.json accesible para los clientes A2A.

1. Vaya a su agente.
2. Haga clic en Acciones y, a continuación, en Ver tarjeta de agente y Tarjeta de agente publicada.
   
   

   

   
   
3. Puede cambiar la vista haciendo clic en Formulario o JSON en la parte superior derecha. La vista JSON es más completa, pero de solo lectura. Solo puede editar campos en la vista Formulario.
4. Haga clic en Editar.
   
   

   

   
   
5. Modifique los campos según sea necesario.
6. Haga clic en Agregar una aptitud para agregar las aptitudes que desea exponer a los clientes A2A.
   
   

   

   
   
7. Haga clic en Publicar cambios.

Las tarjetas de agente publicadas no están disponibles públicamente. Un usuario debe estar autenticado y tener el permiso adecuado (READ) para inspeccionar el contenido de agent-card.json. Otros agentes pueden detectar las capacidades y los metadatos de sus agentes mediante una solicitud HTTP GET en la ruta de acceso estándar:

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

Despliegue de Agente

Al desplegar un agente, éste se convierte en una aplicación alojada.

Puede desplegar un agente en el mismo recurso informático de IA conectado a su patio de recreo o a otro recurso informático de IA. Al desplegar los últimos cambios en el agente en los recursos informáticos de AI asociados, el agente desplegado representa una instantánea del agente en el momento del despliegue. Para actualizar el agente desplegado a la última versión, debe volver a desplegar el agente.

Cada agente tiene una URL de despliegue estable que depende de la clave de agente única. El nuevo despliegue del agente varias veces sobrescribe al agente detrás de la URL de despliegue.

El despliegue de los agentes tiene las siguientes limitaciones:

• Un agente solo se puede desplegar en un cluster de recursos informáticos de AI en un momento determinado.
• Al desplegar el mismo agente varias veces en el mismo cluster de recursos informáticos de AI, se sobrescribe la iteración desplegada anteriormente del agente.

Una vez desplegado un agente, puede recuperar el URI de chat para emitir consultas mediante programación y recuperar respuestas del agente desde el separador Detalles de su agente.

La URL de punto final es estable y está vinculada a cada agente. La URL incluye el ID de agente único asignado a cada agente. Es decir, si anula el despliegue de un agente y lo vuelve a desplegar, la URL sigue siendo la misma. La ventaja es que no tiene que modificar el código de cliente que llama al punto final, la desventaja es que puede sobrescribir un agente en producción.

La URL tiene la siguiente estructura:

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

donde:

• oci-region corresponde a la región de instancia de AI Data Platform;
• agentId es el ID único asociado al agente
• protocol es el protocolo de comunicación: chat, que sigue el formato de API de respuestas de OpenAI y a2a, que sigue el protocolo de comunicación de agente a agente. Ambos protocolos están disponibles para cada punto final de agente. Para obtener más información, consulte Despliegue de agente A2A.

Note:

En el separador Details se muestran dos cálculos de AI. El comando Asociado a AI Compute se utiliza para probar el agente en el patio de recreo. Desplegado en AI Compute aloja el agente desplegado.

El campo URL de punto final se rellena después de desplegar el agente. Puede llamar a esta URL de punto final desde la aplicación de producción.

Despliegue de un agente

Despliega los agentes que ha creado y configurado para que otros usuarios puedan verlos y utilizarlos en su instancia de AI Data Platform.

1. En la página inicial, vaya a la carpeta que contiene el agente que desea desplegar.
2. Junto al agente, haga clic en Acciones y en Desplegar. También puede hacer clic en el nombre del agente y en Desplegar en la parte superior derecha.
   
   

   

   
   
3. Seleccione los recursos informáticos de AI que desea asociar al agente desplegado.
4. Seleccione AIDP Workbench para el tipo de autorización.
5. Seleccione una política de retención de datos de sesión.
   • Para el período de retención, indique el número de días que se conservan los datos de la sesión.
   • Para Límite de tamaño de sesión, proporcione el tamaño máximo que puede alcanzar una sesión.
   • Para Límite de recuento de threads, proporcione el número máximo de threads de sesión que se retienen.
6. Haga clic en Desplegar.

Despliegue de un agente con OAuth2

Puede desplegar los agentes que ha creado y configurado para utilizar la autenticación de OAuth2 para conectarse a proveedores de identidad externos.

1. En la página inicial, vaya a la carpeta que contiene el agente que desea desplegar.
2. Junto al agente, haga clic en Acciones y en Desplegar. También puede hacer clic en el nombre del agente y en Desplegar en la parte superior derecha.
   
   

   

   
   
3. Seleccione los recursos informáticos de AI que desea asociar al agente desplegado.
4. Seleccione OAuth2 para el tipo de autorización.
5. Proporcione la reclamación de público. AI Data Platform Workbench rellena automáticamente este campo, pero puede sustituirlo por una reclamación de público de su proveedor de identidad.
6. Proporcione la reclamación de emisor y la URI para recuperar JWKS. Esta información se deriva del proveedor de identidad.
7. Seleccione una política de retención de datos de sesión.
8. Haga clic en Desplegar.

Llamada a un agente desplegado

Puede llamar a la URL de punto final de su agente desde la aplicación de producción.

Independientemente de la interfaz programática que se utilice para llamar al punto final del agente, debe estar autenticado con OCI y tener los permisos pertinentes. En el caso de los puntos finales de flujo de agente, el emisor de llamada debe tener al menos permiso USE en el punto final del agente.

El URI de punto final se documenta en el separador de detalles de la interfaz de usuario del agente. Puede copiar ese URI de punto final en el código para llamar al agente.

Métodos para Llamar a URI de Punto Final

Puede llamar al URI de punto final del agente a través de diferentes herramientas, SDK y CLI.

Los siguientes métodos le permiten llamar al URI de punto final en los agentes de Oracle AI Data Platform Workbench.

Llamar con la CLI de OCI

En el ejemplo proporcionado se muestra cómo utilizar la CLI de OCI y autenticarse con un token de seguridad. Sustituya <your-agent-flow-endpoint-uri> por el URI de punto final de agente y <security_token> por el token de seguridad de OCI.

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

Llamar con biblioteca de solicitudes de Python

Puede utilizar el SDK de Python de OCI para crear un firmante para autenticarse con OCI. La biblioteca de solicitudes de Python se puede utilizar para publicar una solicitud en el URI de punto final del agente y devolver una respuesta. En el siguiente ejemplo se muestra cómo puede utilizar el principal de usuario a través de los archivos de clave privada y configuración de OCI:

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

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

Puede llamar al URI de punto final de agente instanciando la clase MyRawJsonRPCClient y proporcionando un valor de perfil de OCI (que se encuentra en el archivo de configuración de OCI), el URI de punto final de agente (chat_url) y una sessionKey. Puede proporcionar cualquier sessionKey arbitrario. sessionKey es el identificador único de la sesión de usuario con el agente. Si sigue reutilizando el mismo sessionKey, los mensajes de usuario y las respuestas del agente se agregan a la misma conservación.

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

También puede proporcionar un mensaje de usuario y utilizar el cliente para enviar el mensaje al URI de punto final del agente:

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

A través de APEX

Puede utilizar el ejemplo de código disponible en el repositorio de muestras de Github de AI Data Platform Workbench. El ejemplo le guía por el proceso de llamada a un punto final de despliegue de agente desde una aplicación APEX.

A través de Streamlit

Puede utilizar el ejemplo de código disponible en el repositorio de muestras de Github de AI Data Platform Workbench. El ejemplo le guía por el proceso de llamada a un punto final de despliegue de agente desde una aplicación Streamlit.

Mejores Prácticas: Respuestas Asíncronas y No Asíncronas

Le recomendamos que escriba su código de cliente suponiendo respuestas asíncronas. Por ejemplo:

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

Anulación del despliegue de un agente

Puede anular el despliegue de los agentes para los que tiene permisos MANAGE, lo que hace que no estén disponibles para su uso.

1. En la página de inicio, desplácese a la carpeta que contiene el agente que desea anular el despliegue.
2. Junto al agente, haga clic en Acciones y en Anular despliegue.
   
   

   

   
   
3. Hga clic en Anular Despliegue.

Agentes de supervisión

Puede supervisar los detalles relacionados con las sesiones y métricas de los agentes para ver información sobre cómo se está utilizando, los recursos que consume y mucho más.

Tiene varios separadores en el agente para realizar un seguimiento de los detalles de uso, el separador Sesiones, el separador Métricas y el separador Actividad. Puedes encontrarlos en la parte superior del lienzo de tu agente.

Rastreos e intervalos

Los rastreos proporcionan observabilidad para los agentes mediante la captura y visualización del flujo de solicitudes de agentes. Los intervalos son los objetos que componen un rastreo. Cada intervalo es un paso diferente del flujo, como las peticiones de datos de chat de un usuario, las llamadas a agentes y las tareas de flujo de trabajo.

Puede ver los rastreos de la sesión actual, la ejecución de prueba o las sesiones anteriores. Para ver el rastreo de la sesión actual, vaya a la ficha Flow y haga clic en Playground. El panel Details de la parte inferior de la página muestra el rastreo de la sesión actual en el panel izquierdo. Puede hacer clic en los objetos del rastreo para ampliarlos o ver información más detallada. En el panel derecho, puede hacer clic en los separadores Info, Details o Events para obtener más información sobre el objeto de período seleccionado.

Puede ver los rastreos de sesiones anteriores en el separador Sesiones haciendo clic en el nombre de la sesión.

Sesiones

En el separador Sesiones, puede ver un historial de sesiones para este agente. Puede ver si cada sesión se ha realizado correctamente o ha fallado, el origen de URI, cuando se ha iniciado la sesión, la duración de la sesión y los tokens utilizados en la sesión. Puede hacer clic en el ID de sesión para obtener detalles más específicos sobre esa sesión y ver los rastreos de esas sesiones específicas.

Puede filtrar las sesiones mostradas mediante la barra de búsqueda para filtrar por ID de sesión u origen de URI, mediante los filtros de fecha para mostrar solo un rango de fechas específico, y el menú desplegable Estado de sesión para filtrar por si una sesión se ha realizado correctamente o ha fallado.

Métricas

El separador Métricas muestra un resumen de los datos de uso de todas las sesiones de agente. La lista desplegable Rango de fechas filtra el período de tiempo que desea ver resumido en las tarjetas que se muestran. La selección de URI filtra el origen de selección de URI para el que desea ver los detalles. Puede modificar las tarjetas que se muestran y si incluyen o no gráficos como representaciones visuales de uso.

Actividad

El separador Actividad muestra un resumen del estado de despliegue del agente. La columna Operación especifica el tipo de operación de despliegue (Desplegar o Anular Despliegue) y la columna Estado especifica el resultado de la operación (Correcto, Error, Advertencia, Fallo). Puede ver quién inició la operación y cuándo, así como el mensaje de estado asociado con el resultado de la operación.

Ver sesiones de agente

Puede ver un historial de sesiones para el agente y filtrar los resultados para ver las tendencias y ayudar con la resolución de problemas.

1. En la página inicial, vaya a su agente.
2. Haga clic en el separador Sesiones.
3. Utilice los filtros para cambiar las sesiones mostradas.

Ver métricas del agente

Puede ver los detalles resumidos del agente que se utiliza, como el uso de token, las duraciones de sesión, la latencia y mucho más.

1. En la página inicial, vaya a su agente.
2. Haga clic en el separador Métricas.
3. Seleccione diferentes opciones de la lista desplegable Rango de fechas para ver cómo difieren las métricas entre las líneas de tiempo.
4. Seleccione diferentes opciones de la lista desplegable Selección de URI para filtrar orígenes de URI específicos.

Mover un agente

Puede mover los agentes que posee o para los que tiene permisos MANAGE.

1. En la página de inicio, desplácese a la carpeta que contiene el agente que desea mover.
2. Junto al agente que desea modificar, haga clic en Acciones y en Mover.
3. Seleccione la nueva ubicación del espacio de trabajo para el agente. Haga clic en Mover.

Copiar un agente

Puede copiar un agente del que sea propietario o tener permisos MANAGE para otra ubicación en un espacio de trabajo disponible.

Puede copiar agentes en la misma carpeta o en otra diferente. Los flujos de agente se pueden copiar en carpetas de diferentes espacios de trabajo a los que tiene acceso. Se copia la configuración del agente, así como la configuración de la herramienta y la guía. Las asociaciones de cluster de recursos informáticos de IA no se copian y debe asociar el agente a un nuevo cluster de recursos informáticos de IA para reanudar el desarrollo.

1. En la página de inicio, desplácese a la carpeta que contiene el agente que desea mover.
2. Junto al agente que desea modificar, haga clic en Acciones y en Copiar en espacio de trabajo.
3. Si es necesario, proporcione un nuevo nombre y una descripción para el agente copiado.
4. Haga clic en Examinar y seleccione una nueva ubicación en el espacio de trabajo en la que copiar el agente. Haga clic en Seleccionar.
5. Haga clic en Copiar.

Descargar archivos de agente

Puede descargar los archivos de agente y sus archivos de guía que contienen las definiciones para ese agente.

Los archivos del agente son archivos JSON con la extensión de archivo AFLOW y contienen las definiciones para el agente. Los archivos de guías de protección están etiquetados como _guardrails.JSON y contienen las definiciones de guía de protección para el agente.

1. Desplácese a la carpeta del agente en el espacio de trabajo.
2. Haga clic en el nombre del agente que desee descargar.
   
   

   

   
   
3. Junto al archivo AFLOW del agente, haga clic en Acciones y, a continuación, en Descargar. El archivo se descarga en el equipo local.
4. Junto al archivo _guardrails.JSON, haga clic en Acciones y, a continuación, en Descargar. El archivo se descarga en el equipo local.