Conectarse a un agente disponible a través del protocolo Agent2Agent (A2A) (versión preliminar)

El protocolo Agent2Agent (A2A) es un estándar abierto para la comunicación y la colaboración entre agentes.

Puede conectar el agente personalizado a otro agente que admita el protocolo A2A. Copilot Studio usa el protocolo A2A para orquestar con este agente en respuesta a una solicitud de usuario o un desencadenador.

¿Qué es el protocolo Agent2Agent (A2A)?

El protocolo Agent-to-Agent (A2A) define un contrato estándar para la comunicación del agente. Permite que un orquestador o un agente:

• Enviar tareas a agentes externos.
• Proporcione metadatos enriquecidos y estructurados.
• Recibir respuestas del agente en un formato predecible.

Este es el modo en que el protocolo A2A se compara con una conexión HTTP tradicional para la comunicación entre agentes:

Característica	Protocolo A2A	Conector HTTP
Diseñado para flujos de trabajo de agente	✓	✗
Admite interacciones con múltiples turnos	✓	✗
Proporciona metadatos contextuales enriquecidos	✓	Limitado
Interoperable entre marcos	✓	Varía

Con A2A, Copilot Studio puede delegar tareas a otro agente, no solo llamar a las API.

Cuándo usar conexiones A2A

Use una conexión A2A cuando quiera integrar agentes que ya implementen el protocolo Agent-to-Agent. Este enfoque funciona bien para los agentes que son:

• Basado en marcos externos.
• Hospedado fuera de Copilot Studio.
• Equipados con su propio razonamiento o con flujos de trabajo específicos del dominio.

Use patrones de integración alternativos cuando corresponda:

Necesidad de integración	Enfoque recomendado
Conexión a API o servicios HTTP básicos	Conectores personalizados/herramientas HTTP
Uso de herramientas o recursos de MCP	Servidores MCP
Integración de agentes creados con Microsoft 365 Agents SDK	Protocolo de actividad

Puede combinar varios modelos de integración en el mismo agente de Copilot Studio.

Conexión del agente a otro agente a través del protocolo A2A

1. Vaya a la página Agentes del agente principal y seleccione Agregar un agente.

2. Seleccione Conectar a un agente> externoAgent2Agent.

3. Escriba la dirección URL del punto de conexión del agente de A2A. La dirección URL del punto de conexión debe ser el punto de conexión para la comunicación con el agente y no la dirección URL de la tarjeta del agente.

   Una vez que ingrese la dirección URL del punto de conexión, si el agente tiene una tarjeta de agente válida en la dirección URL estándar .well-known, Copilot Studio extrae automáticamente el nombre y la descripción del agente de la tarjeta y los completa en el formulario.

   Nota

   Si un nombre y una descripción no se rellenan automáticamente para el agente, es posible que el agente no tenga una tarjeta de agente, la tarjeta se encuentra en una dirección URL diferente de la esperada o hay un problema al comunicarse con la tarjeta. En primer lugar, compruebe que el punto de conexión del agente es correcto. Si es así, puede escribir manualmente un nombre y una descripción adecuados para el agente del SDK. La descripción debe describir el propósito del agente, de modo que el agente principal pueda comprender cuándo se debe usar el segundo agente. Obtenga más información sobre cómo escribir metadatos efectivos. También puede intentar navegar a la tarjeta del agente en el explorador (ubicado en el punto de conexión del agente + /.well-known/agent.json).

4. Seleccione el método de autenticación adecuado, en función de cómo esté configurado el agente del SDK, en la lista desplegable Autenticación . Las opciones son:

   • Ninguno: seleccione esta opción si el agente no requiere autenticación o si usa el agente de ejemplo proporcionado en esta documentación, que no tiene habilitada la autenticación.
   • Clave de API: seleccione esta opción si el agente requiere una clave de API para la autenticación. Debe proporcionar el nombre del encabezado donde se debe incluir la clave de API o el parámetro de consulta.
   • OAuth 2.0: seleccione esta opción si el agente usa OAuth 2.0 para la autenticación. Debe proporcionar el identificador de cliente, el secreto de cliente, la dirección URL de autorización, la dirección URL del token y la dirección URL de actualización.

   Si selecciona un tipo de autenticación distinto de Ninguno, también debe completar los demás detalles de autenticación.

5. Selecciona Crear.

6. Seleccione la conexión deseada en la lista de conexiones disponibles o cree una nueva conexión entre el agente de A2A y el agente de Copilot Studio.

7. Seleccione Agregar y configurar.

Nota

Es responsable de revisar y probar cuidadosamente los agentes conectados en el contexto de los casos de uso específicos y tomar todas las decisiones y personalizaciones adecuadas. Cuando te conectas a agentes fuera de Copilot Studio, eres responsable de cómo se utilizan esos agentes. Entre las consideraciones se incluye asegurar:

• Los flujos de datos, la gestión y el intercambio de datos entre agentes son apropiados para tu caso de uso y cumplen con los requisitos y leyes pertinentes
• Los agentes cumplen con los estándares adecuados de calidad, fiabilidad, seguridad y confiabilidad.
• Se aprovisionan los permisos, límites y aprobaciones adecuados, si es prudente para su caso de uso.
• Existen funciones adecuadas de observabilidad, identidad y trazabilidad, así como de supervisión humana

Ejemplo de conexión A2A

En este inicio rápido, configurará un agente habilitado para A2A y lo conectará a un agente de Copilot Studio. Cuando complete los pasos, podrá

• Ejecute un agente habilitado para A2A de ejemplo localmente o use un agente A2A existente que ya tenga.
• Exponga el agente de forma segura a través de HTTPS mediante túneles de desarrollo u otra opción de hospedaje.
• Conecte el agente externo a un agente de Copilot Studio a través de una conexión A2A.
• Valide la conexión invocando al agente de Copilot Studio con una tarea de lenguaje natural como: "Qué planta necesita más luz-una planta de tomate o una planta de fresa?"

Después de configurar la conexión, verá lo siguiente:

• Una conexión A2A exitosa establecida desde Copilot Studio.
• Registros de actividad del agente externo que confirma que recibió y procesó la tarea delegada.
• La carga completa de A2A, incluidos los demás metadatos que Copilot Studio envía con cada solicitud.

Prerrequisitos

Para seguir el escenario de ejemplo, necesita:

• Un recurso Azure OpenAI con:
  • Dirección URL del extremo
  • Nombre de implementación
  • API key
• .NET 10 SDK o superior
• Un entorno de Copilot Studio con permisos para:
  • Editar agentes
  • Configuración de conexiones
• Método para exponer el agente local públicamente:
  • Túneles de desarrollo (recomendado para el desarrollo)
  • O un entorno hospedado, como Azure App Service o contenedor

Si ya tiene un agente habilitado para A2A, vaya a Crear la conexión A2A en Copilot Studio.

Paso 1: Clonar y configurar el agente A2A de ejemplo

Clona el repositorio del agente A2A de ejemplo.

git clone https://github.com/microsoft/CopilotStudioSamples.git
cd CopilotStudioSamples/extensibility/a2a/Simple-A2A-Sample

Establezca la configuración necesaria de Azure OpenAI:

• AZURE_OPENAI_ENDPOINT: dirección URL del punto de conexión de OpenAI de Azure
• AZURE_OPENAI_DEPLOYMENT_NAME: nombre de la implementación de OpenAI de Azure
• AZURE_OPENAI_API_KEY: tu clave de API de Azure OpenAI

Puede configurar estas opciones como variables de entorno o guardándolas en appsettings.json o appsettings.Development.json.

Opción A: Configurar como variables de entorno

$env:AZURE_OPENAI_ENDPOINT="https://YOUR-RESOURCE.openai.azure.com"
$env:AZURE_OPENAI_DEPLOYMENT_NAME="YOUR-DEPLOYMENT"
$env:AZURE_OPENAI_API_KEY="YOUR-KEY"

Opción B: Configurar en appsettings.json

{  
    "AzureOpenAI": {    
        "Endpoint": "https://YOUR-RESOURCE.openai.azure.com",
        "DeploymentName": "YOUR-DEPLOYMENT",
        "ApiKey": "YOUR-KEY"  
    }
}

Paso 2: Compilación, ejecución y exposición del agente

Restaurar y compilar dependencias:

dotnet restore
dotnet build

Ejecute el agente:

dotnet run

La consola muestra la dirección URL del punto de conexión A2A local.

Exposición del punto de conexión

Nota

En escenarios de producción, implemente el agente como una aplicación web segura o un servicio en contenedor mediante la autenticación adecuada. Use túneles de desarrollo solo con fines de desarrollo y demostración locales.

Si usa Visual Studio Code y tiene previsto exponer el punto de conexión mediante túneles de desarrollo, exponga un puerto de túnel de desarrollo nuevo. Elija el puerto A2A que se muestra en la consola. Haga clic con el botón derecho y haga público el puerto; de lo contrario, no es visible en línea.

Los túneles de desarrollo proporcionan una dirección URL pública, como: https://xyz123-9000.dev.tunnels.ms/. Tome nota de esta dirección URL como punto de conexión base para que pueda usarla al configurar la conexión A2A en Copilot Studio.

Paso 3: Creación de la conexión A2A en Copilot Studio

Una vez que el agente A2A esté disponible públicamente, cree la conexión A2A dentro de Copilot Studio.

1. Abra Copilot Studio y seleccione el agente principal.
2. Seleccione Agentes.
3. Seleccione Agregar agente y, a continuación, elija Agente A2A.
4. Escriba los valores de configuración necesarios:
   • Nombre: nombre descriptivo, como agente botánico.
   • Dirección URL del punto de conexión: use la dirección URL pública del túnel de desarrollo, seguido del punto de conexión del mensaje A2A, por ejemplo: https://xyz123-5073.dev.tunnels.ms/a2a/botanical/v1/message:stream
   • Autenticación: seleccione Ninguno si usa el agente de ejemplo (no se aplica ninguna autenticación).
5. Seleccione Guardar para validar y establecer la conexión.

Cuando la configuración es válida, Copilot Studio confirma que el agente A2A está conectado correctamente.

Sugerencia

Dado que las conexiones A2A usan la infraestructura del conector personalizado, también puede usarlas para conectarse a agentes de A2A que se ejecutan de forma local o dentro de una red virtual.

Paso 4: Envío de una tarea desde Copilot Studio al agente de A2A

Después de crear la conexión, compruebe la integración mediante el envío de una tarea.

1. Abra su agente principal en Copilot Studio y vaya al lienzo Prueba.
2. Introduzca un indicador que se deba delegar al agente A2A. Por ejemplo: "¿Qué planta necesita más luz, una planta de tomate o una planta de fresa?"
3. El orquestador del agente evalúa la entrada del usuario y delega la tarea al agente de A2A.
4. El agente externo procesa la solicitud y devuelve una respuesta, que aparece en el chat de prueba.

En los registros del agente externo, verá:

• Una tarea A2A recibida.
• Mensaje de lenguaje natural.
• La respuesta generada se devolvió a Copilot Studio.

Paso 5: Inspeccionar la carga útil y los metadatos de A2A

Los mensajes A2A incluyen metadatos estructurados que proporcionan contexto adicional. Estos metadatos pueden ayudar al agente a adaptar las respuestas, administrar el enrutamiento o mantener la continuidad entre turnos de usuario.

Una carga típica de mensajes A2A incluye:

• Un único contextId
• Identificadores de mensaje
• Información de configuración regional
• Historial de chat completo, no solo la expresión de usuario más reciente
• Elementos de contenido del mensaje (texto, llamadas a herramientas u otros metadatos)

Fragmento de carga de ejemplo:

{
"method": "message/send",
"params": {
 "message": {
   "contextId": "ee1e68ee-75fc-42bb-83d7-25fd26e559c3",
   "metadata": {
     "copilotstudio.microsoft.com/a2a/chathistory": [
       {
         "From": "agent",
         "Locale": "en-US",
         "Text": "Hello, I'm A2A Agent Demo...",
         "Timestamp": "2025-11-26T23:19:28.764Z"
       },
       {
         "From": "user",
         "Locale": "en-US",
         "Text": "Which plant needs more sunlight...",
         "Timestamp": "2025-11-26T23:20:21.484Z"
       }
     ]
   }
 }
}
}

Puede usar estos metadatos para cualquier lógica posterior que implemente su agente A2A.

Pasos siguientes

Después de establecer la conexión A2A básica, puede hacer lo siguiente:

• Agregue nuevas aptitudes o conocimientos de dominio al agente de A2A.
• Use metadatos de la carga de A2A para implementar la lógica de enrutamiento y personalización.
• Agregue autenticación para proteger el punto de conexión de A2A y actualice la configuración de Copilot Studio en consecuencia.
• Conecte otros agentes habilitados para A2A mediante el mismo enfoque de configuración.

Conclusiones clave

• Copilot Studio puede organizar agentes externos mediante el protocolo A2A.
• A2A habilita flujos de trabajo de multiagente con metadatos contextuales enriquecidos.
• El agente de ejemplo muestra el recorrido de ida y vuelta completo: Copilot Studio -> agente A2A -> Copilot Studio.
• Los mensajes A2A incluyen metadatos detallados que respaldan el comportamiento del agente consciente del contexto.

Información relacionada

• Explora patrones de orquestación multiagente
• Diseño de soluciones de agentes: patrones multiagente