Início Rápido: Configurar e executar o agente de exemplo do framework Python

Neste Guia de Início Rápido, percorra a configuração de um agente funcional do framework Python Agent utilizando o Agent 365 para ferramentas, notificações, observabilidade e testar o agente com o Agents Playground e o Teams.

Pré-requisitos

  • Se você planeja usar Visual Studio Code, deve ter .NET instalado. (é recomendável .NET 8.0.)

  • 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 passo a passo depende das bibliotecas do Agent Framework fornecidas por meio do Microsoft 365 Agents Toolkit ou ATK. Você instalará automaticamente estes pacotes ao usar a extensão Agents Toolkit no VS Code para criar a estrutura do exemplo, ou pode instalar o pacote manualmente usando este comando:

    uv pip install -e . --prerelease=allow

  • Acesso ao GitHub

  • Um projeto existente de agente de IA. Este início rápido usa um agente de amostra do Agent 365 do kit de ferramentas do agente do Microsoft 365 também conhecido como ATK no VS Code.

  • A365 CLI

  • Autenticação da Identidade do Agente

Configurar o framework do Agente + exemplo em Python do Microsoft 365 Agents Toolkit

Para preparar tudo, instale o kit de ferramentas do Microsoft 365 Agents no VS Code, abra a galeria de exemplos e estruture a estrutura do Agente e o exemplo em Python localmente, para que você possa configurá-lo e executá-lo mais tarde. As capturas de tela a seguir mostram o que você deve esperar ver ao longo do caminho.

  1. Abra Visual Studio Code em seguida, abra o painel ExtensionsCtrl+Shift+X.

  2. Na barra de busca, digite "Agents Toolkit".
    Você deve ver o resultado mostrado na captura de tela aqui:

    Captura de tela do Marketplace de Extensões para a busca de Agents Toolkit.

  3. Selecione Microsoft 365 Agents Toolkit.

  4. Selecione Instalar.

    O VS Code mostra a visualização de detalhes da extensão de forma semelhante a:

    Captura de tela da página de detalhes da extensão com os botões Instalar e Ativar.

  5. Uma vez instalado, o ícone do M365 Agents Toolkit aparece na barra de navegação à esquerda.

  6. Selecione para abrir a experiência de boas-vindas.

    Agora você deve ver opções como Construir um Agente Declarativo, Criar um Novo Agente/App e Visualizar Exemplos, como mostrado aqui:

    Captura de tela da Vista de Boas-Vindas do Toolkit com opções Construir um Agente Declarativo, Criar um Novo Agente ou App, e Visualizar Exemplos.

  7. Selecione Ver Amostras.

  8. Na lista de exemplos, role para localizar o exemplo de agente do framework Agent + Python.

  9. Selecione-o.

    Você verá duas opções: Create (scaffold local) ou View no GitHub.

  10. Escolha Criar.

    Captura de tela do Agent Framework com o Agent 365 SDK usando exemplo em Python.

  11. Quando solicitado, selecione uma pasta na sua máquina onde a amostra deve ser gerada. Por exemplo: C:\A365-python-sample

    O kit de ferramentas insere a estrutura do Agent e um exemplo em Python em uma subpasta (como sample_agent) e a abre automaticamente no VS Code.

    Depois que a estruturação for concluída, agora você terá uma estrutura de agente totalmente funcional + projeto de agente Python na sua máquina

  12. Instale os pacotes necessários do Agent 365

    Antes de rodar o exemplo, abra o pyproject.toml 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 kit de ferramentas do Microsoft 365 Agents já inclui essas entradas.

    Depois de revisar o pyproject.toml, instale tudo executando este comando:

    uv pip install -e . --prerelease=allow

    Isso baixa todas as bibliotecas do SDK do Agente 365, as dependências do framework do Agente, os componentes de hospedagem, e quaisquer outras dependências definidas no exemplo.

  13. 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 de Microsoft 365 (servidores MCP)

Você pode explorar e gerenciar servidores MCP usando os comandos a365 develop na linha de comando.

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."

Observability

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 encapsula cada invocação do agente com um InferenceScope para que as 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 de observabilidade completa necessária para o exemplo da estrutura Python + Agent. Saiba mais sobre observabilidade

Testar 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 locatário Microsoft 365, a menos que você queira publicar o agente e usá-lo em aplicativos como o 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 modelo de exemplo 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.
  • Inicie o agente localmente, expondo-o 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 tudo estiver pronto para o comportamento real, publique um locatário do Microsoft 365 e teste o agente dentro do Teams, do Outlook ou de outras interfaces do Microsoft 365.

Saiba mais sobre testes

Publique seu agente

Quando o agente estiver pronto para experiências do Microsoft 365 reais, como chats do Teams, mensagens do Outlook, Word @mentions, você o publicará em um locatário do Microsoft 365. O comando CLI publish do Agente 365 cuida da embalagem: ele 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, o agente fica registrado e instalável dentro do locatário.

Importante

Após publicar seu agente, você deve configurar o blueprint do agente no Portal de Desenvolvedores antes de criar instâncias. Aprenda como 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

  • Last updated on