A2A le brinda a un agente de IA una forma estándar de presentarse a otro agente, aceptar un trabajo o tarea, informar el progreso, solicitar más información y devolver resultados útiles, incluso cuando el otro agente se ejecuta en un servicio de IA diferente, usa un lenguaje de programación o marco de agente diferente, o está implementado en otra nube. Ninguno de los agentes necesita entender cómo está construido el otro. Utilizan el estándar A2A para comunicarse y trabajar juntos.
Arquitectura de referencia ADK-Rust A2A
The network contract stays separate from the agent's model, tools, memory, and internal orchestration.
01
El agente o aplicación que solicita a otro agente que realice un trabajo.
Decide qué especialista remoto debe recibir la tarea.
Descubre la tarjeta, elige streaming y envía mensajes de protocolo.
02
El contrato público que todo cliente compatible puede entender.
Nombre, habilidades, punto final, versión del protocolo, seguridad y capacidades declaradas.
Versión, tipo de contenido, ID, partes del mensaje, metadatos, identidad y límites.
Distribuye operaciones JSON-RPC o REST a través de una implementación compartida.
03
El marco ejecuta la tarea y produce progreso escrito.
Crea el contexto de invocación y transmite eventos del agente.
LLM, lógica de flujo de trabajo, gráfica, personalizada o multiagente.
Herramientas Rust y MCP
Sesiones y memoria
04
Una máquina de estados validada hace que el trabajo de larga duración sea inspeccionable.
Estado, contexto, historial, artefactos, metadatos y configuración push.
Sólo se aceptan transiciones válidas; las tareas terminales permanecen terminales.
05
La persona que llama elige cómo quiere recibir el cambio.
Devuelve la tarea completa y sus artefactos.
Primero la tarea, luego las actualizaciones de estado y artefactos.
06
Las tareas largas pueden informarse más tarde sin mantener abierta una conexión.
Un cliente escucha las actualizaciones de una tarea existente.
Entrega autenticada con reintento y comprobaciones SSRF.
Empezar con la idea
Dentro de un proceso ADK-Rust, los agentes pueden compartir tipos, sesiones, herramientas y llamadas de función directas de Rust. Una vez que un agente pertenece a otro servicio (u otra organización), esos detalles de implementación privados ya no son un contrato seguro.
A2A define el idioma compartido en ese límite. La persona que llama descubre lo que ofrece el agente remoto, envía un mensaje estructurado, sigue una tarea a través de estados conocidos y recibe artefactos sin necesidad de saber qué modelo, marco o herramientas se ejecutan detrás del punto final.
ADK-Rust implementa A2A v1 en adk-server y conecta el protocolo directamente al Runner. El mismo agente que pruebe localmente puede convertirse en un servicio de red, mientras que RemoteA2aAgent permite que otro sistema ADK-Rust lo consuma a través de la interfaz normal del Agente.
Tarjeta de agente
Un pequeño documento público informa a las personas que llaman el nombre del agente, el punto final, las habilidades, la versión del protocolo, los requisitos de seguridad y si admite transmisión o notificaciones.
Mensaje
Un mensaje conlleva una función, una identificación única y una o más partes, como texto o datos estructurados. La identificación única hace posibles reintentos seguros.
Tarea
Una tarea le da al trabajo remoto una identificación, un contexto de conversación, un estado, un historial de mensajes, metadatos y cualquier artefacto producido a lo largo del camino.
artefacto
Un artefacto es un resultado con nombre adjunto a la tarea: un informe, decisión, plan, archivo generado u otro resultado estructurado que otro sistema puede utilizar.
Seguir un trabajo
Una persona que llama puede esperar una respuesta, abrir una transmisión de eventos en vivo, suscribirse a una tarea existente o registrar un webhook para actualizaciones posteriores. La identidad y el contexto de la tarea mantienen todos los modos de entrega adjuntos a la misma pieza de trabajo.
máquina de estado de tareas
A2A hace más que devolver texto. Le da al trabajo una identidad, un contexto de conversación, un estado actual, historia y artefactos. ADK-Rust valida cada transición antes de guardarla.
SUBMITTEDEl servidor aceptó la tarea.
WORKINGEl agente lo está ejecutando.
INPUT REQUIREDEl agente necesita más información.
AUTH REQUIREDLa persona que llama debe proporcionar autorización.
COMPLETEDEl trabajo y los artefactos están listos.
FAILEDLa ejecución finalizó con un error.
CANCELEDUna cancelación permitida puso fin a la tarea.
REJECTEDEl servidor rechazó la tarea.
INPUT_REQUIRED, la persona que llama envía otro mensaje con el mismo contextId. ADK-Rust encuentra la tarea, la devuelve a WORKING, agrega el mensaje y continúa con el mismo trabajo.Flujo lógico del mundo real
A customer tells the company's support agent that an order arrived damaged. The support agent remains responsible for the conversation: it understands the request, keeps the customer informed, collects any missing evidence, and presents the final decision. It does not have direct access to warehouse stock, delivery records, or replacement policy.
Esa información operativa pertenece a un agente de cumplimiento implementado por separado. A través de A2A, el agente de soporte puede descubrir qué hace el agente de cumplimiento, enviarle la investigación como una tarea, seguir su progreso, responder solicitudes de más información y recibir la decisión final de reemplazo. Cada servicio mantiene su propio código, datos, herramientas, proveedor de modelos y controles de seguridad; solo comparten los mensajes, el estado de la tarea y los artefactos definidos por el contrato A2A.
Un coordinador de soporte lee la tarjeta del agente de cumplimiento y confirma que maneja la investigación del pedido y transmite el progreso.
Envía el número de pedido, la solicitud del cliente, un ID de mensaje único y un nuevo contexto de conversación.
El agente remoto ADK-Rust verifica las herramientas de pedidos, el inventario, el historial de entregas y la política de la empresa sin exponer esos elementos internos a la persona que llama.
Si se requiere prueba de daño, la tarea se convierte en INPUT_REQUIRED en lugar de adivinar o fallar silenciosamente.
El coordinador proporciona la evidencia aprobada utilizando el mismo contextId; la historia y la identidad de la tarea permanecen intactas.
La tarea se completa con un historial de estado y un artefacto que contiene la decisión de reemplazo y los próximos pasos.
Sequence diagram
Read from top to bottom. The A2A service owns the network contract and task record. The fulfilment agent owns its reasoning and private tools.
Calling agent
Protocol boundary
ADK-Rust Runner
Orders · inventory · policy
GET /.well-known/agent-card.json
Discover skills and streaming
Agent Card
Fulfilment capability published
SendStreamingMessage
ORD-1042 · messageId msg-order-1042
Runner invocation
Create task and execute agent
order.lookup + policy.check
Use private business tools
Evidence required
Damage photo is missing
INPUT_REQUIRED
Persist state and context
SSE status update
Ask support for evidence
SendMessage · same contextId
Approved photo reference
Resume task
INPUT_REQUIRED → WORKING
inventory.reserve
Reserve replacement stock
Artifact + COMPLETED
Replacement decision
Final SSE events
Auditable result returned
Respuestas de código y cable
Estos ejemplos utilizan los mismos nombres de operación v1, campos de mensaje, estados de tarea y formas de respuesta SSE que la implementación de ADK-Rust. Las identificaciones y los detalles del pedido son fijos para que toda la conversación sea fácil de seguir.
let fulfilment = LlmAgentBuilder::new("fulfilment")
.description("Investigates orders and delivery")
.model(model)
.instruction(
"Use the approved order, inventory, and policy tools. Ask for evidence when the replacement policy requires it."
)
.build()?;
A2aServer::builder()
.agent(Arc::new(fulfilment))
.agent_card_name("Fulfilment Agent")
.streaming(true)
.build()?
.serve()
.await?;let fulfilment = RemoteA2aAgent::builder("fulfilment")
.description("Investigates orders and delivery")
.agent_url("https://agents.example.com/fulfilment")
.streaming(true)
.build()?;
let support = LlmAgentBuilder::new("support")
.model(model)
.instruction("Own the customer conversation.")
.sub_agent(Arc::new(fulfilment))
.build()?;{
"jsonrpc": "2.0",
"id": "replace-1",
"method": "SendStreamingMessage",
"params": {
"message": {
"messageId": "msg-order-1042",
"role": "ROLE_USER",
"parts": [{
"text": "Investigate damaged order ORD-1042 and prepare a replacement decision."
}]
}
}
}data: {
"jsonrpc":"2.0", "id":"replace-1",
"result":{"task":{
"id":"task-order-1042",
"contextId":"ctx-order-1042",
"status":{"state":"TASK_STATE_SUBMITTED"}
}}
}
data: {
"jsonrpc":"2.0", "id":"replace-1",
"result":{"statusUpdate":{
"taskId":"task-order-1042",
"contextId":"ctx-order-1042",
"status":{"state":"TASK_STATE_WORKING"}
}}
}{
"statusUpdate": {
"taskId": "task-order-1042",
"contextId": "ctx-order-1042",
"status": {
"state": "TASK_STATE_INPUT_REQUIRED",
"message": {
"role": "ROLE_AGENT",
"parts": [{
"text": "Please provide a photo showing the damaged item."
}]
}
}
}
}{
"jsonrpc": "2.0",
"id": "replace-2",
"method": "SendMessage",
"params": {
"message": {
"messageId": "msg-order-1042-photo",
"contextId": "ctx-order-1042",
"role": "ROLE_USER",
"parts": [{
"text": "Evidence received and approved: damage-photo-8841.jpg"
}]
}
}
}{
"artifactUpdate": {
"taskId": "task-order-1042",
"contextId": "ctx-order-1042",
"artifact": {
"artifactId": "replacement-decision-1042",
"name": "Replacement decision",
"parts": [{
"text": "Approved. Reserve SKU-RED-42 and dispatch with priority shipping."
}]
}
}
}
{
"statusUpdate": {
"taskId": "task-order-1042",
"contextId": "ctx-order-1042",
"status": { "state": "TASK_STATE_COMPLETED" }
}
}El A2A v1 API
ADK-Rust implementa las 11 operaciones en A2A v1. Para un trabajo breve, llame a SendMessage y espere el resultado de la tarea. Cuando el trabajo pueda tardar más, utilice SendStreamingMessage para recibir la tarea primero, seguido del estado en vivo y eventos de artefactos a través de SSE.
El ID de tarea devuelto permite a su cliente volver a conectarse sin volver a enviar el trabajo. Puede obtener el estado más reciente, enumerar tareas relacionadas, suscribirse a más actualizaciones o solicitar cancelación. Si el cliente no puede mantener una conexión abierta, puede registrar un webhook autenticado y permitir que el agente remoto entregue cambios posteriores.
Envíe un mensaje y reciba una tarea completa o una transmisión en vivo.
SendMessageSendStreamingMessageLea el trabajo actual, enumere las tareas coincidentes o cancele una tarea cuando su estado lo permita.
GetTaskListTasksCancelTaskAbra una suscripción SSE para obtener actualizaciones de una tarea que ya existe.
SubscribeToTaskCree, lea, enumere y elimine destinos de webhooks autenticados para una tarea.
CreatePushConfigGetPushConfigListPushConfigsDeletePushConfigSolicite la versión ampliada del perfil de servicio publicado de un agente.
GetExtendedAgentCardLas rutas JSON-RPC y REST se envían al mismo RequestHandler, por lo que el comportamiento de la tarea no varía entre transportes.
Los mensajes entrantes A2A se convierten en contenido ADK-Rust. El Runner ejecuta el agente seleccionado y convierte sus eventos en estado de tarea y artefactos.
Un ID de mensaje repetido devuelve la tarea existente en lugar de ejecutar el mismo trabajo dos veces. Las implementaciones de producción deben conservar esta asignación durante los reinicios.
El primer evento SSE es la tarea completa. Los eventos posteriores llevan actualizaciones de estado y artefactos, por lo que un cliente siempre sabe a qué pertenece la transmisión.
RemoteA2aAgent implementa el rasgo del Agente ADK-Rust. Un coordinador puede incluir un servicio de red en su jerarquía de agentes y recibir eventos de marco normales.
La negociación de versiones, la validación de mensajes, la autenticación del portador, la limitación de velocidad, los interceptores de auditoría, la autenticación de webhook y las comprobaciones SSRF pueden proteger el servicio.
Elige el límite correcto
A2A presenta una red, un contrato público, autenticación, manejo de fallas y estado de tareas remotas. Esos costos son valiosos cuando crean una independencia real; son innecesarios cuando cada agente ya vive en el mismo proceso.
Subagente local
Agente A2A remoto
Del agente Rust al servicio de red
El servidor de conveniencia crea una aplicación Axum con una tarjeta de agente, sesiones, rutas A2A y transmisión habilitada. El adaptador remoto descubre ese servicio y convierte las actualizaciones de sus tareas nuevamente en eventos ADK-Rust.
use adk_server::a2a::convenience::A2aServer;
let app = A2aServer::quick_start(agent);
let listener = tokio::net::TcpListener::bind(
"0.0.0.0:8080"
).await?;
axum::serve(listener, app).await?;use adk_server::a2a::RemoteA2aAgent;
let fulfilment = RemoteA2aAgent::builder("fulfilment")
.description("Investigates orders and delivery")
.agent_url("https://agents.example.com/fulfilment")
.build()?;
let coordinator = LlmAgentBuilder::new("support")
.model(model)
.sub_agent(Arc::new(fulfilment))
.build()?;RequestHandler::with_runner ruta para elegir explícitamente el almacén de tareas, el remitente de inserción, la tarjeta de agente, los servicios Runner, la ruta JSON-RPC, el enrutador REST y el middleware de negociación de versiones.Antes de la producción
ADK-Rust proporciona los tipos v1, controladores, ciclo de vida, clientes, validación, primitivas de entrega e integración con Runner. La preparación para la producción aún depende del almacenamiento, la identidad, la red, la observabilidad y las políticas operativas seleccionadas para su servicio.
Anuncie solo las habilidades, enlaces, transmisión, entrega push y esquemas de seguridad que la implementación realmente admite.
El InMemoryTaskStore incluido y el mapa de idempotencia en memoria son útiles para el desarrollo. El trabajo de producción de larga duración necesita un almacenamiento que sobreviva a los reinicios del proceso.
Autentique las llamadas entrantes y proteja la entrega push saliente. El remitente push HTTP admite credenciales de portador, tokens de notificación, reintentos y rechazo de direcciones privadas.
El trabajo remoto puede sobrevivir a una solicitud. Defina los tiempos de espera del cliente, la política de cancelación, el comportamiento de reintento y lo que sucede cuando cualquiera de los servicios deja de estar disponible.
Conecte el sistema del agente
Comience con una Tarjeta de Agente honesta y una tarea útil. Agregue transmisión, entrada de múltiples turnos, persistencia de tareas, suscripciones, envío autenticado y controles de límites a medida que el trabajo se vuelve más largo y el servicio se vuelve más importante.