En esta guía, puedes aprender cómo convertir un documento OpenAPI 3.0 en herramientas de agente. Usa el comando agentengine agent create-tool para compilar el documento en archivos de conector. Cuando compilas tu agente, el Atlas Agent motor crea el conector a partir de esos archivos para que tu agente pueda llamar a las herramientas de agente de OpenAPI.
Nota
El comando agentengine agent create-tool es experimental. Las flags, el formato de salida y los formatos de archivo generados pueden cambiar sin previo aviso.
Acerca de esta tarea
El comando agentengine agent create-tool genera dos archivos en la carpeta que especifiques:
tool_defs.yaml: El catálogo de herramientas que el comando compila a partir del documento OpenAPI. El catálogo incluye nombres de herramientas, esquemas de entrada y el método y la ruta HTTP para cada operación.tool.yaml: El archivo de creación que vincula el catálogo con su endpoint de API y sus credenciales, y selecciona qué herramientas expone su agente. El comando crea este archivo. Cuando vuelve a generar el catálogo, el comando no sobrescribe las ediciones que realizó en el archivo.
Cuando el agente llama a una herramienta de conector, la herramienta se ejecuta en un Tool Pod aislado. La llamar pasa por la misma puerta de aprobación de Orchestration motor que otras herramientas. Los valores de las credenciales nunca se escriben en los archivo generados, y los archivo hacen referencia al nombre de un secreto del espacio de trabajo.
Debe pasar exactamente una de las siguientes entradas al comando:
--spec: Compila un documento OpenAPI 3.0 en un catálogo y crea un archivotool.yamlsi no existe. El valor puede ser un archivo local o una URL HTTPS.--tool-defs: Solo genera el archivotool.yamlpara un catálogo local existente. El comando no sobrescribe el catálogo.--config: Regenera un catálogo de propiedad local a partir del archivotool.yamlque declara el camposource.spec.
Para ver todas las opciones, consulte la documentación de la CLI de agentengine_create-tool.
Antes de comenzar
Antes de comenzar, asegúrese de tener los siguientes recursos:
La CLI de
agentengineinstalada y autenticada. Para aprender más, consulta Instalación y autenticación.Un Proyecto de agente válido con un archivo
agent.yaml. Para obtener más información, consulta Crear un proyecto.Docker ejecutándose localmente.
Un documento OpenAPI 3.0, ya sea un archivo local o una URL HTTPS, para la REST API que desea llamar.
Un Bearer token de autenticación para la REST API.
Pasos
Genera los archivo del conector.
Desde el directorio de su Proyecto de agente, ejecute el comando agentengine agent create-tool con el nombre del conector y la bandera --spec. El siguiente ejemplo compila una especificación en la carpeta connectors/orders y configura la autenticación con Bearer token:
agentengine agent create-tool orders \ --spec <openapi-document-url-or-path> \ --out-dir connectors/orders \ --auth bearerEl comando asigna al secreto del espacio de trabajo para el Bearer token el nombre del conector. Para el conector orders, el nombre del secreto es ORDERS_TOKEN. Si omite la marca --auth, el comando genera el bloque auth en el archivo tool.yaml a partir de los esquemas de seguridad que declara el documento.
El comando utiliza el primer servidor no plantillado del documento como URL base. Si el documento no declara un servidor, o si desea llamar a un endpoint diferente, agregue la bandera --base-url al comando.
Si el documento contiene operaciones que el generador no puede representar, el comando falla e imprime el nombre de la operación. Para excluir esas operaciones, agregue el indicador --skip-unsupported al comando. El comando imprime cada operación omitida y hace un registro en el catálogo.
Revise el archivo tool.yaml.
Abra el archivo connectors/orders/tool.yaml. El comentario en la parte superior del archivo indica el destino del endpoint y las credenciales secretas que su agente debe declarar.
Para limitar qué herramientas puede llamar su agente, enumere nombres de herramientas específicos en el campo expose.allow. Si omite esta lista, el agente puede llamar a todas las herramientas generadas. El siguiente ejemplo muestra un archivo tool.yaml que expone una herramienta:
name: orderstool_defs: tool_defs.yamlsource: type: openapi base_url: https://api.example.comexpose: allow: [orders_getOrder]auth: bearer: ORDERS_TOKENAlmacena las credenciales de la API como un secreto del espacio de trabajo.
Cree un secreto con el nombre al que hace referencia el bloque auth en el archivo tool.yaml. En este ejemplo, el nombre del secreto es ORDERS_TOKEN. Para aprender a almacenar secretos, consulte Provisionamineto de secretos en la nube.
Conceda al sandbox de la herramienta acceso al secreto y a la API.
El comentario en la parte superior del archivo tool.yaml solo informa los requisitos y no otorga ningún permiso. En su archivo agent.yaml, añada el secreto al campo sandboxes.tool.secrets y el nombre de host de la API al campo sandboxes.tool.network.egress. Conserve los secretos y destinos que ya utilizan sus otras herramientas. El siguiente ejemplo añade el secreto ORDERS_TOKEN y el host api.example.com:
sandboxes: tool: secrets: - ORDERS_TOKEN network: egress_mode: allow_list egress: - fqdn: api.example.com ports: [443]Reemplaza api.example.com y 443 con el nombre de host y el puerto de la URL base en tu archivo tool.yaml. Para aprender más, consulta el Esquema YAML del agente y Gestionar políticas de salida de red.
Compila e implementa tu agente.
Compile e implemente su agente como de costumbre. La compilación crea el conector a partir de sus archivos tool.yaml y tool_defs.yaml. Para aprender más, consulte Compilar la imagen del agente.
Comportamiento y limitaciones
Revisa el siguiente comportamiento y las limitaciones de las herramientas de conector generadas:
La URL base en el archivo
tool.yamlse aplica a cada operación. El generador ignora las entradasserversa nivel de ruta y de operación en el documento OpenAPI.El generador lee archivos locales. La CLI descargar documentos que especifiques por URL bajo la política de transporte de la plataforma.
El generador admite Bearer token, claves de API y autenticación HTTP básica. Lo siguiente está fuera del límite de generación:
Adquisición y actualización de tokens OAuth
Inicio de sesión interactivo o de sesión
Firma por solicitud
autenticación solo por mTLS
Cargas de archivos multipart
Un conector trunca las respuestas mayores que 200,000 bytes decodificados y las marca como truncadas.
Cada invocación de la herramienta se agota después de 30 segundos.
Obtén más información
Consulta la siguiente documentación para aprender más sobre las herramientas de OpenAPI:
agentengine_create-tool