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

Neste Quickstart, percorre a configuração de um agente framework Python Agent funcional usando o Agent 365 para ferramentas, notificações, observabilidade e testes do agente usando o Agents Playground e Teams.

Pré-requisitos

Se planeias usar Visual Studio Code, tens de ter o .NET instalado. É recomendado o TLS 1.2.
Python 3.11+ instalado
Gestor de pacotes UV instalado. Instala isto num terminal usando pip install uv.
Dependências do Microsoft Agents Toolkit / Agent Framework

O exemplo utilizado no guia baseia-se nas bibliotecas do Agent Framework fornecidas através do Microsoft 365 Agents Toolkit ou ATK. Irá instalá-los automaticamente quando 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 preparar tudo, instalas o Microsoft 365 Agents Toolkit no VS Code, abres a galeria de exemplos e instalas localmente o framework Agent + o sample em Python para poderes configurá-lo e executá-lo mais tarde. As capturas de ecrã seguintes mostram o que deve esperar ver à medida que avança.

Abre o Visual Studio Code, depois abre o painel de Extensões Ctrl+Shift+X.
Na barra de pesquisa, escreva "Agents Toolkit".
Deves ver o resultado mostrado na captura de ecrã aqui:
Selecione o Microsoft 365 Agents Toolkit.
Selecione Instalar.

O VS Code mostra a visualização de detalhes da extensão de forma semelhante a:
Uma vez instalado, o ícone M365 Agents Toolkit aparece na barra de navegação esquerda.
Seleciona-o para abrir a experiência de boas-vindas.

Agora deverá ver opções como Construir um Agente Declarativo, Criar um Novo Agente/Aplicação e Ver Exemplos, como mostrado aqui:
Selecionar Ver Amostras.
Na lista de exemplos, desloce-se até encontrar o exemplo de Agent framework + Python .
Selecione-a.

Verás duas opções: Criar (andaime localmente) ou Visualizar 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 a framework Agent + sample Python numa subpasta (como sample_agent) e depois abre-a automaticamente no VS Code.

Quando a estrutura estiver concluída, terá agora um projeto de framework de agentes + agente Python totalmente funcional na sua máquina
Instalação necessária dos pacotes Agent 365

Antes de executar 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 estas entradas.

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

Adicionar ferramentas Microsoft 365 (servidores MCP)

Pode explorar e gerir servidores MCP usando os comandos de desenvolvimento a365 na linha de código.

Ao trabalhar com servidores MCP, pode:

Descubra quais os servidores MCP disponíveis para utilização
Adicione um ou mais servidores MCP à configuração do seu agente
Revise os servidores MCP atualmente configurados
Remova os servidores MCP de que já não precisa

Depois de adicionados servidores MCP, o manifesto de ferramentas do seu agente expande-se 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 gerir ferramentas

Subscrição e gestão de notificações

O agente de exemplo subscreve todas as notificações do SDK do Agente 365 e onAgentNotification("*") encaminha-as para um único handler. Este handler permite ao agente reagir a eventos em segundo plano ou do sistema, não apenas a mensagens diretas do utilizador.

Aprenda como notificar os agentes

O código seguinte mostra como a notificação está configurada no agent.py ficheiro.

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 excerto mostra as alterações mínimas necessárias para permitir a observabilidade na amostra. Inicializa o SDK de Observabilidade do Agente 365 e envolve cada invocação do agente de modo InferenceScope a capturar automaticamente entradas, saídas e metadados.

O código seguinte mostra um exemplo de observabilidade simplificada no agent.py ficheiro.

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}")

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

Teste o seu agente.

Defina as variáveis de ambiente necessárias, selecione um modo de autenticação e inicie o agente localmente. Podes testar tudo de ponta a ponta com o Agents Playground sem precisares de um tenant Microsoft 365, a menos que queiras publicar o agente e usá-lo em aplicações como o Teams ou o Outlook.

Visão geral dos passos de teste

Adicione as suas chaves de API e definições de modelo a um .env ficheiro para que o exemplo possa comunicar com um LLM.
Escolhe o teu modo de autenticação. Para desenvolvimento local, a amostra suporta a Autenticação Agential usando valores criados a partir do seu Agente Blueprint.
Inicia o agente localmente, o que o expõe a ferramentas como o Agents Playground.
Usa o Agents Playground para testar mensagens, ferramentas e notificações sem configurar um tenant ou implementar nada.
Quando estiver pronto para comportamentos reais, publique um tenant Microsoft 365 e teste o agente dentro do Teams, Outlook ou outras superfícies Microsoft 365.

Saiba mais sobre testes

Publicar o seu agente

Quando o seu agente estiver pronto para experiências reais do Microsoft 365, como chats no Teams, mensagens do Outlook, Word @mentions, publica tudo num tenant do Microsoft 365. O comando Agent 365 CLI publish trata da embalagem: atualiza o seu manifesto, agrupa tudo e carrega o agente no Microsoft Admin Center.

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

Pode ver os agentes publicados aqui: https://admin.cloud.microsoft/#/agents/all

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

Feedback

Esta página foi útil?

Last updated on 2025-12-02