Configure e partilhe o seu agente

Cada agente no Microsoft Foundry tem um endpoint estável desde o momento em que é criado. Por trás de cada endpoint, um modelo Foundry processa a entrada do utilizador de acordo com as instruções e ferramentas do agente. Quando os utilizadores finais interagem com o seu agente através do Microsoft 365 Copilot, Teams, da sua aplicação existente ou de outras superfícies, interagem com o endpoint estável do agente. Antes de partilhar o seu agente, verifique estas definições:

• Versão do agente ativo — Confirme que a versão que recebe tráfego é aquela com que quer que os utilizadores finais interajam. Por defeito, o agente atualiza automaticamente para a versão mais recente, o que significa que uma versão recém-criada é imediatamente servida. Se não for isso que queres, fixa o tráfego numa versão específica.
• Protocolos e esquemas de autorização — Certifique-se de que correspondem a onde e como os seus utilizadores interagem com o agente. Por exemplo, um agente publicado no Microsoft 365 ou Teams deve ter o protocolo Activity ativado e utilizar um esquema de autorização BotService ou BotServiceRbac.

Este artigo mostra-lhe como selecionar a versão ativa, ativar protocolos, definir esquemas de autorização e adicionar um cartão agente. Depois de configurar o endpoint, pode:

• Introduzir agentes no Microsoft 365 Copilot e Microsoft Teams
• Publique um agente como trabalhador digital no Agente 365

Pré-requisitos

• Um projeto Foundry com pelo menos uma versão agente criada
• Função de Utilizador de IA do Azure no escopo do projeto Foundry para criar, gerir e invocar agentes
• Familiaridade com Azure role-based access control (RBAC) para configuração de permissões
• Familiaridade com Conceitos de Identidade de Agente em Foundry
• Instale os runtimes de linguagem necessários, ferramentas globais e extensões Visual Studio Code conforme descrito em Prepare o seu ambiente de desenvolvimento

Compreender o modelo de objeto agente

Antes de configurar o endpoint, compreenda como projetos, agentes, versões dos agentes e o endpoint estável se relacionam entre si.

Projeto Foundry: Uma pasta que agrupa recursos relacionados, como agentes, ficheiros e ferramentas.

Versão do agente: Um instantâneo imutável da configuração do agente. Qualquer alteração, mesmo uma única edição de prompt, produz uma nova versão.

Agente: A representação estável e voltada para o consumidor de um agente. A identidade, o ponto final e a superfície de autorização do agente mantêm-se consistentes à medida que as suas versões subjacentes evoluem, pelo que os consumidores interagem sempre com a mesma entidade.

Endpoint do agente: A URL à qual os consumidores acedem para invocar o agente. Está ativo no momento em que crias o agente, sem uma etapa de publicação separada, e o URL não muda à medida que lanças novas versões. Configura a versão que serve, os protocolos que utiliza e como os utilizadores se autenticam.

Para a lista completa das propriedades do objeto agente, consulte a secção de referências no final deste artigo.

Encaminhamento do tráfego

É o agente version_selector que determina como o tráfego é dirigido para as versões do agente. Estão disponíveis duas políticas de encaminhamento:

• Use sempre a versão mais recente (por defeito): 100% do tráfego é encaminhado para a versão do agente mais recente. Quando o agente é publicado no Teams ou no Microsoft 365, ao criar uma nova versão, atualiza automaticamente o que é servido nesses canais.
• Fixado a uma versão específica: 100% do tráfego é encaminhado para a versão do agente que selecionar, chamada versão ativa do agente. As novas versões não alteram o que é servido até atualizares o seletor.

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

Protocolos

Um agente pode expor múltiplos protocolos simultaneamente:

Esquemas de autorização

Pode configurar a autenticação de entrada no endpoint do agente:

A autenticação por chave API não é suportada. Use o Microsoft Entra ID (Azure RBAC) para autorizar os chamadores.

Configurar as propriedades do agente

Por defeito, o seletor de versões encaminha 100% de tráfego para a versão mais recente do agente, o protocolo Respostas está ativado e a autorização é definida para Entra. Pode alterar o encaminhamento de versões, ativar mais protocolos, definir esquemas de autorização e adicionar um cartão agente.

Selecione a versão do agente ativo

Por defeito, a política de roteamento é Utilizar sempre a versão mais recente. Para direcionar o tráfego a 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}")

Permitir protocolos e esquemas de autorização

Um agente pode expor múltiplos protocolos simultaneamente. Configure protocolos e autorização de entrada no endpoint 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 revela detalhes e capacidades aos consumidores, incluindo para a 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.

Arranja propriedades para o teu agente

Para visualizar as propriedades atuais do seu agente — identidade, protocolos, autorização e configuração do endpoint — execute:

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

Considerações de segurança e privacidade

• Use o privilégio mínimo. Conceda aos utilizadores o papel mínimo de que precisam. Por exemplo, criar papéis personalizados que separem as permissões de criação de agentes das permissões de invocação de agentes.
• Não incorpores tokens de acesso no código-fonte, scripts ou aplicações clientes. Utilize o fluxo de autenticação Microsoft Entra apropriado para a sua aplicação.

Limitações

Resolução de problemas

Referência: Propriedades do objeto agente

Conteúdo relacionado

• Aprenda sobre conceitos de identidade de agente na Foundry
• Saiba mais sobre agentes alojados
• Introduzir agentes no Microsoft 365 Copilot e Microsoft Teams
• Migrar das Aplicações de Agente para o novo modelo de agente