17 Creación de Agente
En esta sección se trata la creación de agentes de IA mediante el creador de flujos visuales o mediante código.
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
- 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.
- Haga clic en
Crear agente o en Crear en la parte superior derecha.
- En Modo de creación de flujo de agente, seleccione Creador visual.
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.
- Haga clic y arrastre un agente de supervisor al lienzo.
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.
| 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. |
- Vaya al agente en el espacio de trabajo.
- Haga clic en el nodo Agente de supervisor del lienzo.
- Proporcione un nombre y una descripción minuciosos para su agente supervisor.
- Introduzca la región y el modelo para el modelo de servicio de OCI Generative AI que utiliza el supervisor.
- 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.
| 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:
|
| 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.
|
- Vaya al agente en el espacio de trabajo.
- Haga clic en el nodo Agente de supervisor del lienzo.
- Haga clic en el separador Memoria.
- Seleccione si desea activar Limitar el historial de conversaciones. Seleccione una configuración de truncamiento y defina los límites, si está activada.
- 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.
| Límite | Options | Cuándo se Utiliza |
|---|---|---|
| Información de Identificación Personal (PII) |
|
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. |
- 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.
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.
- Vaya al agente en el espacio de trabajo.
- Arrastrar un nodo de agente de la paleta al lienzo. Los nodos de agente se deben colocar debajo de un agente superior.
- Arrastre Herramientas desde la paleta hasta el lienzo.
- Haga clic y arrastre el identificador de conector en el agente de supervisor para conectarse a los nodos del agente.
- 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 17-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:
|
| 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.
|
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 17-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. |
Agentes mediante código
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.
- 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())
- 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 conawaito 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.
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.- 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.
- Python (.py)
- JSON
- TXT
- CSV
- PSV
- RC
- Carpetas
- Haga clic en Agregar nuevo archivo.
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.
- 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.
- 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.
- Haga clic en el separador Playground.
- Haga clic en Reproducir para probar el archivo de código seleccionado.
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.
- El agente descubre que existe una aptitud.
- El agente activa la aptitud solo cuando es relevante.
- El agente carga archivos adicionales de la carpeta de aptitudes solo cuando es necesario.
- 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
- 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.
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 17-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")
- Esquemas de base de datos
- Ejemplos de API
- Plantillas de prompt
- Guías de estilo
- Glosarios de dominio
- Libros de estrategias paso a pasos
- 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.
- La aptitud debe incluir
run_skill_entrypointen las herramientas permitidas. - 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
- Ubicado en el directorio/scripts de la aptitud
- Declarado en los puntos de entrada de la aptitud
- Permitido por la configuración
allowed-toolsde 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.
description: Helps generate BigQuery SQL using the finance warehouse schema.description: Helps with data.Utilizar nombres de punto de entrada explícitos
entrypoints:
- name: validate_query
- name: summarize_numbers
- name: transform_csventrypoints:
- 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.
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.
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
- 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
- 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
- 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.
- 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.
- 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.
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.
- En el selector de sesiones, haga clic en Crear una sesión.
- 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.- En la lista desplegable Session, seleccione una sesión anterior.
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.
- Haga clic en el separador Sesiones.
- Junto a la sesión que desea suprimir, haga clic en
Acciones y, a continuación, en Suprimir.