Saltearse al contenido
Nappai Documentation

A2A Hoster

A2A Hoster es un componente que permite que cualquier agente creado en Nappai sea accesible desde cualquier plataforma mediante el protocolo A2A. Con él, tu agente se convierte en un servicio web que otras aplicaciones pueden consultar y usar.

¿Cómo funciona?

  1. Generación de la tarjeta de agente
    El componente envía una plantilla de texto al modelo de lenguaje (LLM) que has seleccionado.
    La plantilla incluye la descripción que le das al agente (nombre, descripción, entradas y salidas).
    El LLM devuelve un JSON que describe el agente de forma estructurada. Este JSON se guarda como la tarjeta de agente.

  2. Creación de los endpoints
    Se construyen dos URLs:

    • Un GET para obtener la tarjeta de agente (agent.json).
    • Un POST para enviar datos al agente y recibir su respuesta.
      Ambas URLs incluyen un parámetro x-api-key que debes reemplazar por tu clave de API de Nappai.

  3. Interacción con el agente
    Cuando se recibe una petición POST, el componente pasa el texto de entrada al agente que has conectado y devuelve la respuesta del agente.

En resumen, el componente actúa como un puente entre tu agente y el mundo exterior, generando la documentación necesaria y exponiendo los endpoints que otras aplicaciones pueden usar.

Entradas

Model

El modelo de lenguaje que se usará para generar la tarjeta de agente. Debes conectar un componente que provea un modelo de lenguaje compatible (por ejemplo, OpenAI, Cohere, etc.).

Agent

El agente que quieres exponer. Conecta el componente que contiene la lógica de tu agente (puede ser un Chain, AgentExecutor, Agent o cualquier Runnable).

Prompt

Texto que describe tu agente. Se utiliza para crear la tarjeta de agente.
Ejemplo de valor por defecto: javascript Name: HelloWorldAgent, Description: Siempre te dirá “Hello World”, Inputs: [Text], Outputs: [Text]

Salidas

Card Agent

Un diccionario (dict) con la tarjeta de agente generada por el LLM. Puedes usarlo para documentar tu agente o para integrarlo en otras partes de tu flujo.

Endpoint Path

Un texto con las URLs GET y POST que expone tu agente. Copia y pega estas URLs en tu aplicación externa, sustituyendo YOUR_NAPPAI_API_KEY por tu clave real.

Agent Response

La respuesta que devuelve tu agente cuando se envía una petición POST. Esta salida está oculta por defecto, pero puedes habilitarla si necesitas depurar la interacción.

Ejemplo de Uso

  1. Configura el componente

    • Conecta tu modelo de lenguaje en el campo Model.
    • Conecta tu agente en el campo Agent.
    • Ajusta el campo Prompt con la descripción de tu agente (puedes usar el valor por defecto).

  2. Ejecuta el flujo

    • El componente generará la tarjeta de agente y mostrará las URLs en la salida Endpoint Path.

  3. Prueba el endpoint

    • En una herramienta como Postman, envía una petición POST a la URL POST: https://app.nappai.ai/api/v2/a2a/<flow_id>?x-api-key=YOUR_NAPPAI_API_KEY con un cuerpo JSON que contenga el campo input.
    • Recibirás la respuesta de tu agente en la salida Agent Response.

Componentes Relacionados

  • Agent – Crea la lógica de tu agente.
  • LanguageModel – Provee el modelo de lenguaje que genera la tarjeta de agente.
  • Chain – Puedes usar una cadena de procesamiento como agente.

Consejos y Mejores Prácticas

  • Mantén tu clave de API segura: No la incluyas en el código fuente público.
  • Valida la tarjeta de agente: Revisa el JSON generado para asegurarte de que los campos Inputs y Outputs coinciden con lo que tu agente realmente acepta y devuelve.
  • Prueba localmente antes de publicar: Usa la salida Endpoint Path para probar el endpoint con herramientas de prueba de API.
  • Documenta tus endpoints: Añade la tarjeta de agente a la documentación de tu API para que otros desarrolladores la entiendan fácilmente.

Consideraciones de Seguridad

  • La URL incluye un parámetro x-api-key. Asegúrate de que solo usuarios autorizados tengan acceso a esta clave.
  • Si tu agente procesa datos sensibles, considera añadir autenticación adicional (por ejemplo, OAuth) en tu aplicación externa.
  • Revisa los logs de Nappai para detectar accesos no autorizados o patrones sospechosos.