Configurar e compartilhar seu agente

Cada agente do Microsoft Foundry possui um endpoint estável desde o momento em que é criado. Por trás de cada endpoint, um modelo do Foundry processa a entrada do usuário de acordo com as instruções e ferramentas do agente. Quando os usuários finais interagem com seu agente por meio de Microsoft 365 Copilot, Teams, seu aplicativo existente ou outras superfícies, eles interagem com o ponto de extremidade estável do agente. Antes de compartilhar seu agente, verifique estas configurações:

• Versão do agente ativo – confirme se a versão que recebe tráfego é aquela com a qual você deseja que os usuários finais interajam. Por padrão, o agente é atualizado automaticamente para a versão mais recente, o que significa que uma versão recém-criada é atendida imediatamente. Se não for isso que você deseja, direcione o tráfego para uma versão específica.
• Protocolos e esquemas de autorização – verifique se eles correspondem onde e como os usuários interagem com o agente. Por exemplo, um agente publicado no Microsoft 365 ou no Teams deve ter o protocolo de atividade habilitado e usar um esquema de autorização BotService ou BotServiceRbac.

Este artigo mostra como selecionar a versão ativa, habilitar protocolos, definir esquemas de autorização e adicionar um cartão de agente. Depois de configurar o ponto de extremidade, você pode:

• Publicar agentes para o Microsoft 365 Copilot e o Microsoft Teams
• Publicar um agente como trabalhador digital no Agent 365

Pré-requisitos

• Um projeto do Foundry com pelo menos uma versão do agente criada
• Função de Usuário de IA do Azure no escopo do projeto Foundry para criar, gerenciar e invocar agentes
• Familiaridade com controle de acesso baseado em função (RBAC) do Azure para configuração de permissão
• Familiaridade com os conceitos de identidade do Agente na Foundry
• Instale os runtimes de idioma necessários, as ferramentas globais e as extensões de Visual Studio Code conforme descrito em Prepare seu ambiente de desenvolvimento

Entender o modelo de objeto do agente

Antes de configurar o ponto de extremidade, entenda como projetos, agentes, versões do agente e o ponto de extremidade estável se relacionam entre si.

Foundry project: uma pasta que agrupa recursos relacionados, como agentes, arquivos e ferramentas.

Versão do agente: Uma captura imutável da configuração do agente. Qualquer alteração, até mesmo uma única edição de prompt, produz uma nova versão.

Agente: a representação estável voltada para o consumidor de um agente. A identidade, o ponto de extremidade e a superfície de autorização do agente permanecem consistentes à medida que suas versões subjacentes evoluem, para que os consumidores sempre interajam com a mesma entidade.

Ponto de extremidade do agente: a URL que os consumidores chamam para invocar o agente. Está ativo no momento em que você cria o agente, sem nenhuma etapa de publicação separada, e a URL não é alterada à medida que você lança novas versões. Configure qual versão ela serve, quais protocolos ela fala e como os chamadores se autenticam.

Para obter a lista completa de propriedades de objeto do agente, consulte a seção de referência no final deste artigo.

Roteamento de tráfego

O version_selector do agente determina como o tráfego é encaminhado às versões do agente. Duas políticas de roteamento estão disponíveis:

• Sempre use a versão mais recente (padrão): 100% de rotas de tráfego para a versão do agente criada mais recentemente. Quando o agente é publicado para o Teams ou para o Microsoft 365, a criação de uma nova versão atualiza automaticamente o conteúdo disponibilizado nesses canais.
• Fixado em uma versão específica: 100% do tráfego é roteado para a versão do agente selecionada, chamada versão ativa do agente. As novas versões não alteram o que é servido até que você atualize o seletor.

Fixe uma versão específica quando precisar de estabilidade em novas versões, como quando um agente estiver em produção ou publicado para usuários finais no Teams ou Microsoft 365.

Protocolos

Um agente pode expor vários protocolos simultaneamente:

Esquemas de autorização

Você pode configurar a autenticação de entrada no endpoint (ponto de extremidade) do agente.

Não há suporte para autenticação de chave de API. Utilize o Microsoft Entra ID (Azure RBAC) para autorizar os solicitantes.

Configurar as propriedades do agente

Por padrão, o seletor de versão roteia 100% de tráfego para a versão mais recente do agente, o protocolo Respostas está habilitado e a autorização é definida como Entra. Você pode alterar o roteamento de versão, habilitar mais protocolos, definir esquemas de autorização e adicionar um cartão de agente.

Selecione a versão do agente ativo

Por padrão, a política de roteamento é Sempre usar o mais recente. Para fixar o tráfego em uma versão específica, atualize o 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}")

Habilitar protocolos e esquemas de autorização

Um agente pode expor vários protocolos simultaneamente. Configurar protocolos e autorização de entrada no ponto de extremidade do 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}")

Adicionar um cartão de agente

Um cartão de agente apresenta detalhes e funcionalidades para os consumidores, inclusive para descoberta de agente para 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.

Obter as propriedades do agente

Para exibir as propriedades atuais do agente — identidade, protocolos, autorização e configuração de ponto de extremidade — execute:

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

Considerações sobre segurança e privacidade

• Use privilégio mínimo. Conceda aos usuários a função mínima necessária. Por exemplo, crie funções personalizadas que separam as permissões de criação do agente das permissões de invocação do agente.
• Não insira tokens de acesso no código-fonte, scripts ou aplicativos cliente. Use o fluxo de autenticação Microsoft Entra apropriado para seu aplicativo.

Limitações

Solucionando problemas

Referência: Propriedades do objeto Agent

Conteúdo relacionado

• Saiba mais sobre os conceitos de identidade do Agente na Foundry
• Saiba mais sobre agentes hospedados
• Publicar agentes para o Microsoft 365 Copilot e o Microsoft Teams
• Migrar de Aplicações de Agente para o novo modelo de agente