Início rápido: Configure e execute o agente de exemplo do framework Python Agent

Neste Quickstart, explique como configurar um agente framework Python Agent funcional usando o Agent 365 para ferramentas, notificações, observabilidade e testar o agente usando Agents Playground e Teams.

Pré-requisitos

Se você pretende usar o Visual Studio Code, precisa ter o .NET instalado. (.NET 8.0 é recomendado.)
Python 3.11+ instalado
Gerenciador de pacotes UV instalado. Instale isso em um terminal usando pip install uv.
Dependências do Microsoft Agents Toolkit / Agent Framework

O exemplo usado no guia depende das bibliotecas do Agent Framework fornecidas pelo Microsoft 365 Agents Toolkit ou ATK. Você vai instalar esses dispositivos automaticamente ao usar a extensão Agents Toolkit no VS Code para andar o exemplo, ou pode instalar o pacote manualmente usando este comando:
```
uv pip install -e . --find-links ../dist --pre
```
Acesso ao GitHub
Um projeto existente de agente de IA. Este quick start utiliza um agente de exemplo Agent 365 do Microsoft 365 agent toolkit , também conhecido como ATK no VS Code.
A365 CLI
Autenticação da Identidade do Agente

Configure o framework Agent + exemplo Python a partir do Microsoft 365 Agents Toolkit

Para deixar tudo pronto, você instala o Microsoft 365 Agents Toolkit no VS Code, abre a galeria de exemplos e instala localmente o framework Agent + o sample em Python para poder configurá-lo e rodar depois. As capturas de tela a seguir mostram o que você deve esperar ver ao longo do caminho.

Abra o Visual Studio Code, depois abra o painel de Extensões Ctrl++X.
Na barra de busca, digite "Agents Toolkit".
Você deve ver o resultado mostrado na captura de tela aqui:
Kit de Ferramentas de Agentes do Microsoft 365
Selecione Instalar.

O VS Code mostra a visualização de detalhes da extensão de forma semelhante a:
Uma vez instalado, o ícone do M365 Agents Toolkit aparece na barra de navegação à esquerda.
Selecione o experimento para abri-lo.

Agora você deve ver opções como Construir um Agente Declarativo, Criar um Novo Agente/App e Visualizar Exemplos, como mostrado aqui:
Selecione Ver Amostras.
Na lista de exemplos, role para encontrar o framework de agente + exemplo de agente em Python .
Selecione-o.

Você verá duas opções: Create (scaffold localmente) ou View no GitHub.
Escolha Criar.
Quando solicitado, selecione uma pasta na sua máquina onde a amostra deve ser gerada. Por exemplo: C:\A365-python-sample

O toolkit estrutura o framework Agent + sample Python em uma subpasta (como sample_agent) e então a abre automaticamente no VS Code.

Uma vez que o andaime seja concluído, você agora terá um projeto Agent framework + Python totalmente funcional na sua máquina
Instalação dos pacotes necessários

Antes de rodar o exemplo, abra o package.json no seu projeto e confirme que todas as dependências necessárias do Agent 365 e do framework Agent estão listadas. O exemplo gerado pelo Microsoft 365 Agents Toolkit já inclui essas entradas.

Depois de revisar o package.json, instale tudo executando este comando:
```
uv pip install -e
```
Isso puxa todas as bibliotecas do SDK do Agente 365, dependências do framework do Agente, componentes de hospedagem e quaisquer outras dependências definidas no exemplo.
Após a instalação, verifique se o projeto é construído e executado iniciando o servidor de desenvolvimento usando este comando:
```
uv run python start_with_generic_host.py
```

Adicionar ferramentas do Microsoft 365 (servidores MCP)

Você pode explorar e gerenciar servidores MCP usando os comandos de desenvolvimento do a365 na linha de sinal.

Ao trabalhar com servidores MCP, você pode:

Descubra quais servidores MCP estão disponíveis para uso
Adicione um ou mais servidores MCP à configuração do seu agente
Revise os servidores MCP atualmente configurados
Remova os servidores MCP que você não precisa mais

Após a adição dos servidores MCP, o manifesto de ferramentas do seu agente se expande para incluir entradas semelhantes a:

{
   "mcpServers": [
      {
         "mcpServerName": "mcp_MailTools",
         "mcpServerUniqueName": "mcp_MailTools",
         "scope": "McpServers.Mail.All",
         "audience": "api://00001111-aaaa-2222-bbbb-3333cccc4444"
      }
   ]
}

Aprenda a adicionar e gerenciar ferramentas

Assinatura e gerenciamento de notificações

O agente de exemplo assina todas as notificações do SDK do Agente 365 usando onAgentNotification("*") e as roteia para um único handler. Esse handler permite que o agente reaja a eventos em segundo plano ou do sistema, não apenas mensagens diretas do usuário.

Aprenda como notificar os agentes

O código a seguir mostra como a notificação é configurada no agent.py arquivo.

if notification_type == NotificationTypes.EMAIL_NOTIFICATION: 
if not hasattr(notification_activity, "email") or not notification_activity.email: return "I could not find the email notification details."
email = notification_activity.email
email_body = getattr(email, "html_body", "") or getattr(email, "body", "")

message = (
    "You have received the following email. "
    "Please follow any instructions in it. "
    f"{email_body}"
)

result = await self.agent.run(message)
return self._extract_result(result) or "Email notification processed."

Observabilidade

Este trecho mostra as mudanças mínimas necessárias para possibilitar a observabilidade na amostra. Ele inicializa o SDK de Observabilidade do Agente 365 e envolve cada invocação do agente em um InferenceScope modo para que entradas, saídas e metadados possam ser capturados automaticamente.

O código a seguir mostra um exemplo de observabilidade simplificada no agent.py arquivo.

def _enable_agentframework_instrumentation(self): 
"""Enable Agent Framework instrumentation.""" 
try: 
AgentFrameworkInstrumentor().instrument() 
logger.info("✅ Instrumentation enabled")
 except Exception as e: 
logger.warning(f"⚠️ Instrumentation failed: {e}")

Esse código é a configuração completa de observabilidade necessária para o exemplo do framework Python + Agent. Saiba mais sobre observabilidade

Testar o seu agente

Defina as variáveis de ambiente necessárias, selecione um modo de autenticação e inicie o agente localmente. Você pode testar tudo de ponta a ponta com o Agents Playground sem precisar de um tenant do Microsoft 365, a menos que queira publicar o agente e usá-lo em apps como Teams ou Outlook.

Visão geral das etapas do teste

Adicione suas chaves de API e configurações de modelo a um .env arquivo para que o sample possa se comunicar com um LLM.
Escolha seu método de autenticação Para desenvolvimento local, o exemplo suporta Autenticação Agential usando valores criados a partir do seu Agente Blueprint.
Comece o agente localmente, o que o expõe a ferramentas como o Agents Playground.
Use o Agents Playground para testar mensagens, ferramentas e notificações sem configurar um tenant ou implantar nada.
Quando estiver pronto para o comportamento real, publique um tenant do Microsoft 365 e teste o agente dentro do Teams, Outlook ou outras superfícies do Microsoft 365.

Saiba mais sobre testes

Publicar seu agente

Quando seu agente estiver pronto para experiências reais do Microsoft 365, como chats no Teams, mensagens do Outlook, Word @mentions, você publica isso em um locatário do Microsoft 365. O publish CLI do Agente 365 cuida da embalagem: atualiza seu manifesto, agrupa tudo e envia o agente para o Centro de Administração da Microsoft.

Durante a publicação, revise e personalize o nome, descrição, ícones e versão do agente antes de concluir o upload. Uma vez publicado, seu agente se torna detectável e instalável dentro do inquilino.

Importante

Após publicar seu agente, você deve configurar o blueprint do agente no Portal de Desenvolvedores antes de criar instâncias. Veja Configurar o blueprint do agente no Portal do Desenvolvedor.

Você pode ver agentes publicados aqui: https://admin.cloud.microsoft/#/agents/all

Saiba mais sobre o fluxo de trabalho completo e as instruções passo a passo

Comentários

Esta página foi útil?

Last updated on 2025-12-19