En este artículo rehacemos y traducimos al español una implementación completa de un agente IA basado en Pydantic AI, integrado con FastAPI y usando el protocolo a2a para intercambio de mensajes. Un agente IA combina la potencia de un modelo de lenguaje grande con herramientas que le permiten interactuar con el mundo real, validando entradas con esquemas pydantic y exponiendo una API JSON RPC para integraciones.
Arquitectura general y responsabilidades del agente: el agente principal, aquí llamado GrammarAgent, se encarga de recibir mensajes A2A, extraer el texto de la última parte del mensaje, validar entradas con modelos Pydantic, invocar el modelo de lenguaje a través de un proveedor (por ejemplo GoogleProvider) y devolver un TaskResult estructurado con el resultado, el historial y el estado de la tarea.
Implementación resumida del agente: se crea un proveedor con la API key desde la variable de entorno GOOGLE_API_KEY, se instancia un modelo como gemini-2.0-flash mediante GoogleModel y se construye un Agent de pydantic_ai con un prompt de sistema orientado a corrección gramatical y un tipo de salida GrammarResponse. En el método asíncrono run se generan contextId y taskId si no existen, se extrae el texto del último MessagePart, se valida que exista contenido y se llama a await self.agent.run con user_prompt igual al texto del usuario. El resultado se empaqueta en una estructura A2AMessage con role agent y en un TaskResult con status completed y history que incluye el mensaje original y la respuesta del agente. En caso de error se captura la excepción y se devuelve un error 500.
Endpoint HTTP y ciclo de vida: se expone una ruta POST en /a2a/grammar-check usando FastAPI. En el arranque de la aplicación se inicializa el GrammarAgent mediante lifespan y se destruye al finalizar. La ruta valida que la petición cumpla el protocolo JSON RPC 2.0 y que exista id; soporta dos métodos principales: message/send para envío simple y execute para ejecución con contextId y taskId. Tras procesar la petición se devuelve un JSONRPCResponse con el resultado TaskResult o un error con código y mensaje apropiados.
Esquemas pydantic clave: se definen modelos que validan entrada y salida, entre ellos GrammarResponse con response y explanation, MessagePart para representar partes tipo text o data, A2AMessage con role user o agent y lista de parts, MessageConfiguration para opciones de envío, MessageParams y ExecuteParams para los parámetros de los métodos JSON RPC, JSONRPCRequest para validar la petición entrante, TaskStatus con estados working completed input-required failed, Artifact para posibles archivos generados y TaskResult que encapsula id contextId status artifacts history y kind task. Estos modelos facilitan una API robusta, autovalidada y documentable.
Variables de entorno y ejecución: se necesita configurar en el archivo .env la variable GOOGLE_API_KEY=TUAPIKEY. Para ejecutar localmente se puede iniciar con uvicorn main:app host 127.0.0.1 port 5000 reload True. Asegúrate de instalar las dependencias necesarias como pydantic-ai, google provider correspondiente, fastapi, uvicorn y python-dotenv.
Buenas prácticas y extensiones recomendadas: validar siempre las partes del mensaje y controlar los tipos kind text o data, manejar timeouts y límites de tokens del modelo, soportar pushNotificationConfig en MessageConfiguration para notificaciones asincrónicas, registrar el historial completo en TaskResult para auditoría, y añadir pruebas unitarias que comprueben tanto la validación de esquemas pydantic como las respuestas esperadas del agente IA. También es recomendable encapsular proveedores y modelos en capas independientes para facilitar el cambio entre proveedores o modelos LLM.
Casos de uso y beneficios para empresas: este tipo de agente es ideal para corrección gramatical, asistentes de redacción, preprocesamiento de texto para pipelines de datos, automatización de respuestas en workflows y escalado de soporte lingüístico. Integrado con soluciones de inteligencia de negocio y visualización como Power BI permite enriquecer datos textuales con insights y métricas de calidad de texto, y combinado con servicios cloud permite desplegar agentes escalables en AWS o Azure.
Acerca de Q2BSTUDIO: en Q2BSTUDIO somos una empresa de desarrollo de software y aplicaciones a medida especializada en inteligencia artificial, ciberseguridad, servicios cloud aws y azure y soluciones de inteligencia de negocio. Ofrecemos servicios integrales para llevar proyectos de agentes IA a producción, desde el diseño de software a medida hasta la seguridad y el despliegue en la nube. Con experiencia en automatización de procesos y análisis avanzado, ayudamos a empresas a transformar datos en valor.
Si buscas potenciar tu estrategia con IA para empresas o desarrollar soluciones de software a medida puedes conocer más sobre nuestros servicios de Inteligencia artificial y sobre desarrollo de aplicaciones a medida. También ofrecemos servicios de ciberseguridad, pentesting, migración y gestión de infraestructuras cloud y consultoría en inteligencia de negocio como Power BI para mejorar la toma de decisiones.
Palabras clave relevantes: aplicaciones a medida, software a medida, inteligencia artificial, ciberseguridad, servicios cloud aws y azure, servicios inteligencia de negocio, ia para empresas, agentes IA, power bi. Estas palabras reflejan nuestras áreas de especialización y están pensadas para mejorar posicionamiento y conexión con necesidades reales de negocio.
Resumen final: la combinación de FastAPI, Pydantic AI y un protocolo a2a bien definido permite construir agentes IA robustos, auditables y fáciles de integrar. Con una correcta definición de esquemas pydantic, control de errores y un ciclo de vida gestionado en FastAPI se obtiene una solución lista para producción que puede ampliarse con notificaciones, colas y cuadros de mando de inteligencia de negocio. Si necesitas apoyo para diseñar, implementar o desplegar agentes IA a medida, en Q2BSTUDIO te podemos ayudar a llevar tu proyecto de la idea al servicio en producción.