Disponibilidade de material de apoio

Este texto do catálogo contém as orientações inline abaixo, mas não inclui os seguintes caminhos de suporte. Eles são pré-requisitos externos, não arquivos incluídos:

• <support-root>/references/acceptance-criteria.md

Solicite o material de apoio original ou uma instalação existente antes de usar uma etapa que dependa desses caminhos; este catálogo não identifica uma fonte de download verificada para eles. Resolva cada caminho em relação a essa instalação, inspecione seu conteúdo e verifique quaisquer licenças e pré-requisitos de execução aplicáveis. Não execute um comando nem afirme que um procedimento referenciado foi seguido até que seu arquivo necessário exista. Não crie os scripts ausentes nem trate um arquivo não relacionado com o mesmo nome como equivalente. Etapas independentes totalmente documentadas aqui podem prosseguir dentro do escopo autorizado do usuário; relate qualquer etapa dependente como indisponível.

Microsoft 365 Agents SDK (Python)

Crie agentes corporativos para Microsoft 365, Teams e Copilot Studio usando o Microsoft Agents SDK com hospedagem aiohttp, roteamento AgentApplication, respostas em streaming e autenticação baseada em MSAL.

Antes da implementação

• Use o MCP do microsoft-docs para verificar as assinaturas de API mais recentes para AgentApplication, start_agent_process e opções de autenticação.
• Confirme as versões dos pacotes no PyPI para os pacotes microsoft-agents-* que você planeja usar.

Aviso Importante - Mudanças de Importação

⚠️ Mudança Quebradora: Atualizações recentes alteraram a estrutura de importação do Python de microsoft.agents para microsoft_agents (usando underscores em vez de pontos).

Instalação

pip install microsoft-agents-hosting-core
pip install microsoft-agents-hosting-aiohttp
pip install microsoft-agents-activity
pip install microsoft-agents-authentication-msal
pip install microsoft-agents-copilotstudio-client
pip install python-dotenv aiohttp

Variáveis de Ambiente (.env)

CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID=<client-id>
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET=<client-secret>
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID=<tenant-id>

# Optional: OAuth handlers for auto sign-in
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__GRAPH__SETTINGS__AZUREBOTOAUTHCONNECTIONNAME=<connection-name>

# Optional: Azure OpenAI for streaming
AZURE_OPENAI_ENDPOINT=<endpoint>
AZURE_OPENAI_API_VERSION=<version>
AZURE_OPENAI_API_KEY=<key>

# Optional: Copilot Studio client
COPILOTSTUDIOAGENT__ENVIRONMENTID=<environment-id>
COPILOTSTUDIOAGENT__SCHEMANAME=<schema-name>
COPILOTSTUDIOAGENT__TENANTID=<tenant-id>
COPILOTSTUDIOAGENT__AGENTAPPID=<app-id>

Fluxo de Trabalho Principal: AgentApplication hospedado em aiohttp

import logging
from os import environ

from dotenv import load_dotenv
from aiohttp.web import Request, Response, Application, run_app

from microsoft_agents.activity import load_configuration_from_env
from microsoft_agents.hosting.core import (
    Authorization,
    AgentApplication,
    TurnState,
    TurnContext,
    MemoryStorage,
)
from microsoft_agents.hosting.aiohttp import (
    CloudAdapter,
    start_agent_process,
    jwt_authorization_middleware,
)
from microsoft_agents.authentication.msal import MsalConnectionManager

# Habilita o logging
ms_agents_logger = logging.getLogger("microsoft_agents")
ms_agents_logger.addHandler(logging.StreamHandler())
ms_agents_logger.setLevel(logging.INFO)

# Carrega a configuração
load_dotenv()
agents_sdk_config = load_configuration_from_env(environ)

# Cria o armazenamento e o gerenciador de conexão
STORAGE = MemoryStorage()
CONNECTION_MANAGER = MsalConnectionManager(**agents_sdk_config)
ADAPTER = CloudAdapter(connection_manager=CONNECTION_MANAGER)
AUTHORIZATION = Authorization(STORAGE, CONNECTION_MANAGER, **agents_sdk_config)

# Cria o AgentApplication
AGENT_APP = AgentApplicationTurnState


@AGENT_APP.conversation_update("membersAdded")
async def on_members_added(context: TurnContext, _state: TurnState):
    await context.send_activity("Bem-vindo ao agente!")


@AGENT_APP.activity("message")
async def on_message(context: TurnContext, _state: TurnState):
    await context.send_activity(f"Você disse: {context.activity.text}")


@AGENT_APP.error
async def on_error(context: TurnContext, error: Exception):
    await context.send_activity("O agente encontrou um erro.")


# Configuração do servidor
async def entry_point(req: Request) -> Response:
    agent: AgentApplication = req.app["agent_app"]
    adapter: CloudAdapter = req.app["adapter"]

…