Configuración y uso compartido del agente

Cada agente de Microsoft Foundry tiene un punto de conexión estable desde el momento en que se crea. Detrás de cada punto de conexión, un modelo Foundry procesa la entrada del usuario de acuerdo con las instrucciones y herramientas del agente. Cuando los usuarios finales interactúan con el agente a través de Microsoft 365 Copilot, Teams, la aplicación existente u otras superficies, interactúan con el punto de conexión estable del agente. Antes de compartir el agente, compruebe esta configuración:

• Versión del agente activo : confirme la versión con la que recibe tráfico es la que desea que los usuarios finales interactúen. De forma predeterminada, el agente se actualiza automáticamente a la versión más reciente, lo que significa que se proporciona inmediatamente una versión recién creada. Si no es lo que desea, ancle el tráfico a una versión específica.
• Protocolos y esquemas de autorización : asegúrese de que coinciden con dónde y cómo interactúan los usuarios con el agente. Por ejemplo, un agente publicado en Microsoft 365 o Teams debe tener habilitado el protocolo de actividad y usar un esquema de autorización BotService o BotServiceRbac.

En este artículo se muestra cómo seleccionar la versión activa, habilitar protocolos, establecer esquemas de autorización y agregar una tarjeta de agente. Después de configurar el punto de conexión, puede hacer lo siguiente:

• Publicar agentes en Microsoft 365 Copilot y Microsoft Teams
• Publicación de un agente como trabajador digital en el Agente 365

Requisitos previos

• Un Proyecto Foundry con al menos creada una versión del agente
• Rol de usuario de Azure AI en el alcance del proyecto Foundry para crear, administrar e invocar agentes
• Familiaridad con el control de acceso basado en roles de Azure (RBAC) para la configuración de permisos
• Familiaridad con los conceptos de identidad del agente en Foundry
• Instale los entornos de ejecución de lenguaje necesarios, las herramientas globales y las extensiones de Visual Studio Code tal y como se describe en Prepare el entorno de desarrollo

Comprender el modelo de objetos del agente

Antes de configurar el punto de conexión, comprenda cómo se relacionan entre sí los proyectos, los agentes, las versiones del agente y el punto de conexión estable.

Proyecto foundry: carpeta que agrupa recursos relacionados, como agentes, archivos y herramientas.

Versión del agente: una instantánea inmutable de la configuración del agente. Cualquier cambio, incluso un solo ajuste, crea una nueva versión.

Agente: representación estable y orientada al consumidor de un agente. La superficie de identidad, punto de conexión y autorización del agente permanece coherente a medida que evolucionan sus versiones subyacentes, por lo que los consumidores siempre interactúan con la misma entidad.

Punto de conexión del agente: Los consumidores utilizan la URL para invocar al agente. Está activo en el momento en que creas el agente, sin necesidad de un paso independiente de publicación, y la dirección URL no cambia al implementar nuevas versiones. Configuras qué versión sirve, qué protocolos maneja y cómo se autentican los llamantes.

Para obtener la lista completa de propiedades del objeto de agente, consulte la sección de referencia al final de este artículo.

Enrutamiento de tráfico

El agente version_selector determina cómo se enruta el tráfico hacia las versiones del agente. Hay dos directivas de enrutamiento disponibles:

• Use siempre la versión más reciente (valor predeterminado): 100% de rutas de tráfico a la versión del agente creada más recientemente. Cuando el agente se publica en Teams o Microsoft 365, crear una nueva versión actualiza automáticamente el contenido que se ofrece en esos canales.
• Anclado a una versión específica: Se dirige el 100% del tráfico a la versión del agente que hayas seleccionado, denominada versión del agente activa. Las nuevas versiones no modificarán el contenido servido hasta que usted actualice el selector.

Ancle a una versión específica cuando necesite estabilidad en nuevas versiones, como cuando un agente está en producción o publicado para los usuarios finales de Teams o Microsoft 365.

Protocolos

Un agente puede exponer varios protocolos simultáneamente:

Esquemas de autorización

Puede configurar la autenticación de entrada en el punto de conexión del agente:

No se admite la autenticación de clave de API. Usa Microsoft Entra ID (Azure RBAC) para autorizar a los llamantes.

Configuración de las propiedades del agente

De forma predeterminada, el selector de versiones enruta 100% de tráfico a la versión más reciente del agente, el protocolo De respuestas está habilitado y la autorización se establece en Entra. Puede cambiar el enrutamiento de versiones, habilitar más protocolos, establecer esquemas de autorización y agregar una tarjeta de agente.

Seleccione la versión del agente activo

De forma predeterminada, la política de enrutamiento es usar siempre la última versión. Para anclar el tráfico a una versión específica, actualice el version_selector.

PATCH {{endpoint}}/agents/{{agent_name}}?api-version=v1
Authorization: Bearer {{token}}
Content-Type: application/merge-patch+json
Foundry-Features: AgentEndpoints=V1Preview

{
  "agent_endpoint": {
    "version_selector": {
      "version_selection_rules": [
        {
          "type": "FixedRatio",
          "agent_version": "2",
          "traffic_percentage": 100
        }
      ]
    }
  }
}

from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
    AgentEndpoint,
    AgentEndpointProtocol,
    FixedRatioVersionSelectionRule,
    VersionSelector,
)
from azure.identity import DefaultAzureCredential

PROJECT_ENDPOINT = "https://{account}.services.ai.azure.com/api/projects/{project}"

agent_name = "name-of-your-existing-agent"

project_client = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
    allow_preview=True,
)

with project_client:
    endpoint_config = AgentEndpoint(
        version_selector=VersionSelector(
            version_selection_rules=[
                FixedRatioVersionSelectionRule(agent_version="2", traffic_percentage=100),
            ]
        ),
    )

    patched_agent = project_client.beta.agents.patch_agent_details(
        agent_name=agent_name,
        agent_endpoint=endpoint_config,
    )
    print(f"Agent endpoint configured for agent: {patched_agent.name}")

Habilitación de protocolos y esquemas de autorización

Un agente puede exponer varios protocolos simultáneamente. Configure protocolos y autorización de entrada en el punto de conexión del agente.

PATCH {{endpoint}}/agents/{{agent_name}}?api-version=v1
Authorization: Bearer {{token}}
Content-Type: application/merge-patch+json
Foundry-Features: AgentEndpoints=V1Preview

{
  "agent_endpoint": {
    "protocols": ["activity", "responses", "invocations"],
    "authorization_schemes": [
      {
        "type": "Entra",
        "isolation_key_source": {
          "kind": "Entra"
        }
      },
      {
        "type": "BotServiceRbac"
      }
    ]
  }
}

from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
    AgentEndpoint,
    AgentEndpointProtocol,
    EntraAuthorizationScheme,
    BotServiceRbacAuthorizationScheme,
    EntraIsolationKeySource,
)
from azure.identity import DefaultAzureCredential

PROJECT_ENDPOINT = "https://{account}.services.ai.azure.com/api/projects/{project}"

agent_name = "name-of-your-existing-agent"

project_client = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
    allow_preview=True,
)

with project_client:
    endpoint_config = AgentEndpoint(
        protocols=[
            AgentEndpointProtocol.RESPONSES,
            AgentEndpointProtocol.ACTIVITY,
            AgentEndpointProtocol.INVOCATIONS,
        ],
        authorization_schemes=[
            EntraAuthorizationScheme(
                isolation_key_source=EntraIsolationKeySource(),
            ),
            BotServiceRbacAuthorizationScheme(),
        ],
    )

    patched_agent = project_client.beta.agents.patch_agent_details(
        agent_name=agent_name,
        agent_endpoint=endpoint_config,
    )
    print(f"Protocols and authorization updated for agent: {patched_agent.name}")

Agregar una tarjeta de agente

Una tarjeta de agente muestra detalles y funcionalidades para los consumidores, incluida la detección de agente a agente (A2A).

PATCH {{endpoint}}/agents/{{agent_name}}?api-version=v1
Authorization: Bearer {{token}}
Content-Type: application/merge-patch+json
Foundry-Features: AgentEndpoints=V1Preview

{
  "agent_card": {
    "version": "1.0.0",
    "description": "A competitive intelligence analyst that monitors market trends and competitor activity.",
    "skills": [
      {
        "id": "competitor-analysis",
        "name": "Competitor Analysis",
        "description": "Analyzes competitor products, pricing strategies, and market positioning across specified industry verticals.",
        "tags": ["research", "analysis", "market-intel"],
        "examples": [
          "Compare our Q3 pricing against Contoso's latest catalog",
          "Summarize recent product launches from our top 5 competitors",
          "Identify gaps in competitor coverage for the EMEA region"
        ]
      },
      {
        "id": "trend-monitoring",
        "name": "Trend Monitoring",
        "description": "Tracks emerging market trends and surfaces early signals from earnings calls, filings, and news.",
        "tags": ["trends", "monitoring"],
        "examples": [
          "What themes are emerging from this quarter's earnings calls?",
          "Flag any regulatory changes affecting our sector in the last 30 days"
        ]
      }
    ]
  }
}

# Agent card update via SDK is not yet supported. Use the REST API.

Obtén las propiedades de tu agente

Para ver las propiedades actuales del agente( identidad, protocolos, autorización y configuración del punto de conexión), ejecute:

GET {endpoint}/agents/{agent_name}?api-version=v1
Authorization: Bearer {{token}}
Content-Type: application/json
Foundry-Features: AgentEndpoints=V1Preview

Consideraciones de seguridad y privacidad

• Use privilegios mínimos. Conceda a los usuarios el rol mínimo que necesitan. Por ejemplo, cree roles personalizados que separan los permisos de creación de agentes de los permisos de invocación del agente.
• No inserte tokens de acceso en el código fuente, los scripts o las aplicaciones cliente. Use el flujo de autenticación Microsoft Entra adecuado para la aplicación.

Limitaciones

Solución de problemas

Referencia: Propiedades del objeto del agente

Contenido relacionado

• Más información sobre los conceptos de identidad del agente en Foundry
• Aprenda sobre los agentes hospedados
• Publicar agentes en Microsoft 365 Copilot y Microsoft Teams
• Migración de aplicaciones del agente al nuevo modelo de agente