Início rápido: Configurar e executar o agente de exemplo do Agent Framework em Python

Neste Início Rápido, irá configurar um agente funcional do Agent Framework em Python utilizando o Agent 365 para ferramentas, notificações e observabilidade, e testar o agente com o Ambiente de Demonstração de Agentes e o Teams.

Pré-requisitos

  • Se pretender utilizar o Visual Studio Code, é necessário ter o .NET instalado. (Recomenda-se a utilização do .NET 8.0.)

  • Python 3.11+ instalado

  • Gestor de Pacotes UV instalado. Instale este pacote num terminal usando pip install uv.

  • Dependências 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á instalar automaticamente estas dependências quando utilizar a extensão Agents Toolkit no VS Code para criar o exemplo, ou pode instalar o pacote manualmente usando este comando:

    uv pip install -e . --prerelease=allow

  • Acesso ao GitHub

  • Um projeto de Agente de IA já existente. Este guia de início rápido utiliza um agente de exemplo do Agent 365 a partir do Toolkit de Agentes do Microsoft 365, também conhecido como ATK no VS Code.

  • CLI do A365

  • Autenticação da Identidade do Agente

Configurar o Agent Framework + exemplo Python do Microsoft 365 Agents Toolkit

Para preparar tudo, instale o Microsoft 365 Agents Toolkit no VS Code, abra a galeria de exemplos e crie localmente o exemplo do Agent Framework + Python para que possa configurá-lo e executá-lo mais tarde. As capturas de ecrã seguintes mostram o que deve esperar ver à medida que avança.

  1. Abra o Visual Studio Code, em seguida, abra o painel ExtensõesCtrl+Shift+X.

  2. Na barra de pesquisa, digite "Toolkit de Agentes".
    Deve ver o resultado mostrado na captura de ecrã seguinte:

    Captura de ecrã da pesquisa no Mercado de Extensões para o Toolkit de Agentes.

  3. Selecione Toolkit de Agentes do Microsoft 365.

  4. Selecione Instalar.

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

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

  5. Depois de instalado, o ícone do Toolkit de Agentes do M365 aparece na barra de navegação à esquerda.

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

    Agora deverá ver opções como Criar um Agente Declarativo, Criar um Novo Agente/Aplicação e Ver Exemplos, como mostrado aqui:

    Captura de ecrã da Vista de Boas-Vindas do Toolkit com as opções Criar um Agente Declarativo, Criar um Novo Agente ou Aplicação e Ver Exemplos.

  7. Selecione Ver Exemplos.

  8. Na lista de exemplos, percorra-a até encontrar o exemplo de agente Agent Framework + Python.

  9. Selecione-a.

    Verá duas opções: Criar (estruturar localmente) ou Ver no GitHub.

  10. Escolha Criar.

    Captura de ecrã do exemplo de um Agente do Agent Framework com o SDK do Agent 365 em Python.

  11. Quando pedido, selecione uma pasta no seu computador onde o exemplo deve ser gerado. Por exemplo: C:\A365-python-sample

    O toolkit cria a estrutura do exemplo Agent Framework + Python numa subpasta (por exemplo, sample_agent) e, em seguida, abre-a automaticamente no VS Code.

    Assim que a criação da estrutura é concluída, passa a ter um projeto de agente Agent Framework + Python totalmente funcional no seu computador

  12. Instale os pacotes necessários do Agent 365

    Antes de executar o exemplo, abra o pyproject.toml no seu projeto e confirme que todas as dependências necessárias do Agent 365 e do Agent Framework estão listadas. O exemplo gerado pelo Toolkit de Agentes do Microsoft 365 já inclui estas entradas.

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

    uv pip install -e . --prerelease=allow

    Este comando instala todas as bibliotecas do SDK do Agent 365, dependências do Agent Framework, componentes de alojamento e quaisquer outras dependências definidas no exemplo.

  13. Após a instalação, verifique se o projeto é compilado e executado iniciando o servidor de desenvolvimento com este comando:

    uv run python start_with_generic_host.py

Adicionar ferramentas do Microsoft 365 (servidores MCP)

Pode explorar e gerir servidores MCP utilizando os comandos de desenvolvimento do a365 na CLI.

Ao trabalhar com servidores MCP, pode:

  • Detetar quais os servidores MCP estão disponíveis para uso
  • Adicionar um ou mais servidores MCP à configuração do agente
  • Rever os servidores MCP atualmente configurados
  • Remover os servidores MCP que já não são necessários

Depois de adicionar servidores MCP, o manifesto de ferramentas do seu agente passa a 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 processamento de notificações

O agente de exemplo subscreve todas as notificações do SDK do Agent 365 usando onAgentNotification("*") e encaminha-as para um único processador. Este processador 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 a seguir mostra como a notificação é configurada no ficheiro agent.py.

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 fragmento mostra as alterações mínimas necessárias para ativar a observabilidade no exemplo. Inicializa o SDK de Observabilidade do Agent 365 e envolve cada invocação do agente num InferenceScope para capturar automaticamente entradas, saídas e metadados.

O código que se segue mostra um exemplo simplificado de observabilidade no ficheiro agent.py.

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 Python + Agent Framework. Saber mais sobre a observabilidade

Teste o seu agente

Defina as variáveis de ambiente necessárias, selecione um modo de autenticação e inicie o agente localmente. Pode testar tudo de ponto a ponto com o Ambiente de Demonstração de Agentes sem precisar de um inquilino do Microsoft 365, a menos que pretenda publicar o agente e utilizá-lo em aplicações como o Teams ou o Outlook.

Descrição geral dos passos de teste

  • Adicione as suas chaves de API e definições de modelo ao ficheiro .env para que o exemplo possa comunicar com um LLM.
  • Escolha o seu modo de autenticação. Para desenvolvimento local, o exemplo suporta Autenticação por meio de Agentes utilizando os valores criados a partir do seu Esquema do Agente.
  • Inicie o agente localmente, o que o expõe a ferramentas como o Ambiente de Demonstração de Agentes.
  • Use o Ambiente de Demonstração de Agentes para testar mensagens, ferramentas e notificações sem configurar um inquilino ou implementar nada.
  • Quando estiver pronto para comportamentos reais, publique um inquilino do Microsoft 365 e teste o agente dentro do Teams, Outlook ou de outras plataformas do Microsoft 365.

Saber mais sobre testes

Publicar o seu agente

Quando o seu agente estiver pronto para experiências reais do Microsoft 365, como conversas no Teams, mensagens no Outlook ou documentos do Word @mentions, publique-o num inquilino do Microsoft 365. O comando publish da CLI do Agent 365 processa o empacotamento: atualiza o seu manifesto, agrupa tudo e carrega o agente para o centro de administração da Microsoft.

Durante a publicação, reveja e personalize o nome, a descrição, os ícones e a versão do agente antes de concluir o carregamento. Uma vez publicado, o seu agente fica registado e instalável no inquilino.

Importante

Depois de publicar o seu agente, deve configurar o esquema do agente no Portal do Programador antes de criar instâncias. Saiba como configurar o esquema do agente no Portal do Programador

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

  • Last updated on