Comece a desenvolver com o Agent 365

O Agent 365 funciona com uma variedade de implementações de agentes. Um agente pode assistir utilizadores a pedido, executar autonomamente em segundo plano ou operar com identidade própria de utilizador no Microsoft 365. É importante identificar o padrão que melhor descreve o seu agente, pois isso determina o modelo de identidade do agente, o acesso que ele terá aos recursos do Microsoft 365 e quais passos do ciclo de vida são aplicáveis.

Tipos de agentes

Antes de começar, pergunte a si mesmo: Que tipo de agente estou a criar?

Existem dois tipos de agentes dependendo do tipo de acesso que têm:

Tipo de agente Descrição geral
Agentes Trabalhar em nome de um utilizador com acesso delegado ou operar como uma aplicação com permissões com âmbito definido. Registado como aplicações Microsoft Entra ou como esquemas de identidade do agente.
Colega de equipa de IA Opera com a sua própria identidade de utilizador no Microsoft 365, incluindo caixa de correio, presença no Teams e entrada no diretório. Este tipo de agente está disponível apenas para inquilinos que participam no programa de pré-visualização do Frontier.

Agentes

Um agente trabalha em nome de um utilizador. Responde a pedidos, executa tarefas em segundo plano, liga-se a APIs, processa dados e impulsiona ações.

Os agentes apresentam-se de várias formas. Alguns são conversacionais – um utilizador faz uma pergunta e o agente responde. Alguns funcionam silenciosamente em segundo plano – acionados por uma agenda, um evento ou uma mensagem recebida – sem que ninguém esteja ativamente envolvido. Alguns desempenham ambas as funções.

Cenários de exemplo:

  • Um utilizador pede a um agente que resuma os seus e-mails não lidos e elabore respostas. O agente faz o trabalho, acedendo apenas aos recursos aos quais o utilizador tem acesso, e devolve o resultado.
  • Um agente de suporte ao cliente ajuda um engenheiro de suporte a consultar bases de dados de conhecimento internas e a redigir respostas durante uma sessão de suporte em direto.
  • Um agente de monitorização de conformidade é executado todas as noites, analisa os sites do SharePoint aos quais o agente pode aceder para detetar violações de políticas e gera relatórios de auditoria – sem supervisão.
  • Um agente de processamento de encomendas recolhe novas ordens de venda numa fila, atualiza um CRM e envia e-mails de confirmação – tudo isto sem que ninguém o inicie.

Base de identidade:

Tradicionalmente, regista agentes como aplicações Microsoft Entra. Esta abordagem continua a funcionar. No futuro, também pode criar agentes num ID do Agente Microsoft Entra através de um esquema de identidade do agente – a definição aprovada por TI e imposta pela governação das capacidades de um agente, acesso permitido à ferramenta e restrições de conformidade. Criar com base num esquema é o caminho recomendado para os novos agentes. Desbloqueia o acesso governado à ferramenta Work IQ, a proteção de dados do Microsoft Purview, a monitorização de ameaças do Microsoft Defender e a governação do Entra ID – tornando o seu agente uma identidade empresarial totalmente governada desde o primeiro dia. Se os utilizadores do seu agente iniciarem sessão através de um fornecedor de identidade de terceiros, consulte Integrar o ID do Agente Microsoft Entra com fornecedores de identidade de terceiros.

Colega de equipa de IA

Importante

Para obter um acesso antecipado a este tipo de agente, é necessário fazer parte do programa de pré-visualização do Frontier. O Frontier liga-o diretamente às mais recentes inovações de IA da Microsoft. As pré-visualizações do Frontier estão sujeitas aos termos de pré-visualização existentes nos seus contratos de cliente. Como estas funcionalidades ainda estão em fase de desenvolvimento, a sua disponibilidade e capacidades podem variar ao longo do tempo.

Um colega de equipa de IA opera no Microsoft 365 utilizando a sua própria identidade do agente. Pode aprovisioná-lo com capacidades como enviar e receber e-mails através da sua própria caixa de correio, participar em conversas 1:1 e de grupo no Teams, e aparecer em metadados de diretório e organizacionais com uma relação de gestor atribuída. As pessoas podem interagir com ele através de pontos de entrada familiares do Microsoft 365, como @mentions, email, convites para o calendário e conversa no Teams.

Crie estes agentes a partir de um esquema de agente, que é a definição aprovada por TI e imposta pela governação das capacidades do agente, do acesso permitido às ferramentas e das restrições de conformidade. Cada instância de agente herda o modelo de identidade, as permissões e as políticas do seu esquema de identidade do agente principal.

O que o agente faz – seja conversacional, em segundo plano, ou ambos – depende de como o configura. Alguns agentes são altamente interativos, respondendo a mensagens e suportando o trabalho em tempo real. Outros processam tarefas em segundo plano, agindo de acordo com e-mails ou eventos sem cativação direta do utilizador. O agente opera com a sua própria identidade de utilizador, e as suas ações são governadas e auditáveis através dessa identidade.

Se já tem um agente, não precisa de começar do zero. Pode estender os agentes existentes para operarem com a sua própria identidade, adicionando a configuração de identidade e esquema descrita mais adiante neste guia.

Cenários de exemplo:

  • Adicione um agente de IA de inclusão de RH ao canal de inclusão do Teams de um novo colaborador. Envia e-mails de boas-vindas a partir da sua própria caixa de correio, agenda reuniões de orientação no seu próprio calendário e responde a perguntas utilizando as capacidades configuradas para essa instância de agente.
  • Atribua uma relação de gestor nos metadados do diretório a um agente de IA de aquisições. Pedidos de compra por e-mail dos colaboradores para a sua caixa de correio. O agente processa o pedido, consulta os sistemas ERP e financeiros utilizando o seu acesso governado à ferramenta Work IQ, e responde com aprovação ou escalamento a partir da sua própria identidade.
  • Adicione um colega de equipa de IA de investigação ao site do SharePoint e ao canal do Teams de uma equipa de projeto. Pode apresentar documentos relevantes durante reuniões, responder em tópicos de conversas e redigir relatórios semanais de estado utilizando as permissões e ferramentas configuradas para esse agente.

Base de identidade:

Criada de acordo com um esquema de identidade do agente, que cria um ID do Agente Microsoft Entra e uma conta de utilizador associada: sempre obrigatório.

Adicionar capacidades do Agent 365 de forma incremental

O Agent 365 não é tudo ou nada. Não precisa de criar um colega de equipa IA logo no primeiro dia — ou mesmo nunca, se o seu cenário não o exigir. Adote capacidades de forma incremental, começando pelo que o seu agente precisa agora e expandindo à medida que os seus requisitos evoluem.

Por que criar de acordo com um esquema de identidade do agente?

Quando cria um esquema de identidade do agente, a CLI do Agent 365 aprovisiona um ID do Agente Microsoft Entra para o seu agente – uma identidade de primeira classe no seu inquilino, sujeita às mesmas políticas de governação empresarial que os utilizadores humanos. Essa identidade única constitui a base para os benefícios de segurança que se aplicam automaticamente a cada agente baseado no esquema.

Benefício O que isso significa para o seu agente
Microsoft Entra ID Governance A identidade e o ciclo de vida do acesso do agente são geridos através do mesmo Acesso Condicional, da proteção de identidade e de revisões de acesso que se aplicam aos utilizadores humanos.
Microsoft Purview Cada interação de dados que o agente realiza está sujeita às etiquetas de sensibilidade, políticas DLP e políticas de retenção do inquilino - automaticamente, sem código extra.
Microsoft Defender O comportamento do agente é continuamente monitorizado em busca de anomalias e ameaças. As atividades suspeitas acionam os mesmos alertas e fluxos de trabalho de resposta que para qualquer utilizador no inquilino.

Estes benefícios aplicam-se a todos os agentes baseados em esquemas, incluindo agentes com acesso delegado pelo utilizador e agentes que operam com a sua própria identidade, assim que o esquema é criado. Não precisa de configurá-los separadamente.

Os quatro escalões de capacidade abaixo representam os níveis que pode adotar incrementalmente. A tabela seguinte mostra o que está disponível para o Agent 365 com base no seu ponto de partida:

Capacidade Agente personalizado de motor do Microsoft 365 Todos os outros agentes 1
Registar ✓ 2 ✓
Observabilidade ✓ ✓
Work IQ ✓ ✓
Colega de equipa de IA ✓ 3 ✓ 3

1 Os agentes que estejam atualmente registados como aplicações Microsoft Entra devem primeiro criar um esquema de identidade do agente para iniciar qualquer capacidade nesta coluna.

2 Os agentes personalizados de motores do Microsoft 365 já estão registados utilizando o registo de aplicação do Microsoft Entra existente — não é necessária qualquer configuração adicional.

3 O colega de equipa de IA para agentes personalizados de motores do Microsoft 365 requer um esquema de identidade do agente. Disponível apenas para participantes do programa Frontier.

Registar

Ao registar o seu agente, torna-o visível e gerível no centro de administração Microsoft 365. Os administradores podem descobri-lo e vê-lo no inventário de agentes da sua organização.

O que obtém:

  • O seu agente aparece no centro de administração do Microsoft 365; os administradores podem encontrá-lo e vê-lo no inventário de agentes da sua organização.
  • Os agentes baseados em esquemas também recebem todos os benefícios de governação do Entra ID, do Purview e do Defender descritos em Por que criar de acordo com um esquema de identidade do agente?

O que cria:

Registe o agente utilizando o registo de aplicação do Microsoft Entra existente ou um esquema.

Nota

Se criar os seus agentes no Google Vertex AI ou no Amazon Bedrock, o registo não requer trabalho de desenvolvimento. As APIs da Google e da Amazon removem automaticamente os agentes. Não é necessária integração com SDK, nem blueprint, nem alterações de código. Após o registo, pode utilizar o SDK do Agent 365 para adicionar observabilidade, acesso à ferramenta Work IQ e outras capacidades de forma incremental. Para começar, consulte Registar agentes do Google Vertex AI e do Amazon Bedrock.

Como criar:

Utilize a configuração orientada por IA e responda às perguntas sobre o tipo de agente em conformidade. A configuração orientada por IA executa os passos necessários para este escalão. Os agentes personalizados de motores do Microsoft 365 já podem ser descobertos hoje utilizando o registo de aplicação do Microsoft Entra existente.

Observabilidade

Depois de registar o seu agente, invista em observabilidade. Este investimento dá às equipas de TI, de segurança e de engenharia visibilidade sobre o que o seu agente está realmente a fazer. Cada chamada de inferência, invocação de ferramenta e interação é capturada, monitorizada e tornada auditável.

A observabilidade é a base da confiança. Sem isso, os administradores não têm como verificar o comportamento, auditar a conformidade ou diagnosticar problemas em larga escala. Com isso, o seu agente torna-se um ativo empresarial em vez de uma caixa negra.

Nota

Se o seu agente for um super agente — isto é, se internamente chamar um ou mais subagentes para concluir uma tarefa — essas chamadas do subagente também podem ser registadas no pipeline de observabilidade. Registe-as como uma chamada de ferramenta ou uma chamada agente para agente (A2A), conforme aplicável, para que toda a cadeia de delegação seja visível e auditável.

O que obtém:

  • Rastreio completo baseado em [OpenTelemetry (OTel) (OTel)](https://opentelemetry.io/docs/specs/otel/protocol/) de cada interação do agente: entradas, saídas, chamadas de ferramentas e invocações de modelos.
  • Atividade visível no centro de administração do Microsoft 365 e nas superfícies de monitorização ligadas.
  • Registos de auditoria que alimentam o Microsoft Entra, o Microsoft Purview e o Microsoft Defender, suportando requisitos de conformidade, proteção de dados e resposta a ameaças.

O que cria:

Instrumentação utilizando as APIs de observabilidade do Agent 365 SDK: autoinstrumentação (se estiver a utilizar OpenAI, LangChain ou Agent Framework) ou instrumentação manual para qualquer outra pilha.

Nota

Para a maioria das novas integrações, utilize o Microsoft OpenTelemetry Distro — a configuração orientada por IA pode configurar a observabilidade automaticamente.

Se já tiver um pipeline OpenTelemetry implementado, se o seu Agent Framework não puder utilizar o Agent 365 SDK ou se o seu agente estiver desenvolvido numa linguagem ainda não suportada pelo SDK (como Java), pode enviar telemetria diretamente para o Agent 365 via OTLP/HTTP não processado, sem qualquer dependência do SDK. Consulte Integrar com a observabilidade do Agent 365 utilizando o OTel direto.

Como criar:

Utilize a configuração orientada por IA e responda às perguntas de observabilidade adequadamente. A configuração orientada por IA realiza os passos necessários para esta capacidade. Esta utiliza o Microsoft OpenTelemetry Distro para instrumentar o seu agente.

Work IQ

Depois de registar e tornar o seu agente observável, dê-lhe acesso a dados e ações do Microsoft 365 através do Work IQ. O Work IQ é um conjunto governado de ferramentas que permite ao seu agente trabalhar com Correio, Calendário, OneDrive, SharePoint, Teams e muito mais.

As ferramentas do Work IQ requerem um consentimento do administrador, são auditadas e revogáveis. O seu agente chama-as utilizando as permissões definidas no seu esquema – sem necessidade de fluxos OAuth adicionais ou conectores personalizados.

O que obtém:

  • Acesso ao catálogo completo de ferramentas do Work IQ – Correio, Calendário, OneDrive, SharePoint, Teams e muito mais.
  • As permissões que os administradores controlam e definem com âmbito o que o seu agente necessita.
  • Cada chamada de ferramenta rastreada e auditável através do pipeline de observabilidade.

O que cria:

Código de agente que chama as ferramentas do Work IQ utilizando as APIs de ferramentas do Agent 365 SDK.

Como criar:

Utilize as APIs de ferramentas do Agent 365 SDK para adicionar manualmente chamadas de ferramentas do Work IQ ao seu código de agente. De momento, a configuração orientada por IA não suporta esta capacidade.

Colega de equipa de IA

Os colegas de equipa de IA estão disponíveis para os participantes do programa Frontier.

A fase final irá ativar a capacidade do seu agente de operar no Microsoft 365 com a sua própria identidade. Dependendo da configuração, pode ter uma caixa de correio, presença no Teams, entrada de diretório e relação com o gestor. Os utilizadores podem interagir com ele através de experiências familiares do Microsoft 365, como e-mail, chat, reuniões e superfícies de aplicações.

Nota

Alteração no modelo de identidade e permissões

A transição para um colega de esquipa de IA representa uma alteração fundamental na forma como o seu agente acede aos recursos. O seu agente existente pode utilizar o acesso de utilizador delegado, em que o agente atua em nome de um utilizador com sessão iniciada e só pode aceder aos recursos aos quais esse utilizador tem acesso, ou permissões de aplicação com âmbito definido para um principal de serviço. Um agente com uma identidade de utilizador não herda o acesso do utilizador que fez a chamada em runtime. Em vez disso, opera sob a sua própria identidade de utilizador, com as suas próprias atribuições de acesso, políticas de governação e registo de auditoria.

Esta alteração significa:

  • No acesso do utilizador delegado, o agente atua em nome do utilizador que iniciou sessão e está limitado ao acesso desse utilizador. Quando o agente possui uma identidade própria, concede acesso diretamente à caixa de correio, ao calendário, ao Teams e ao SharePoint do Microsoft 365 à identidade do agente.
  • Governa e audita as permissões concedidas à identidade do agente, bem como o próprio acesso desse agente. Não são as mesmas que as permissões delegadas pelo utilizador, passadas através do utilizador que faz a chamada.
  • Se a sua implementação atual depender do acesso delegado do utilizador ou de permissões da aplicação, reveja e reajuste o âmbito dessas permissões para a identidade do agente antes de ativar esta capacidade.

O que obtém:

  • Tudo, desde a Capacidade de descoberta e Observabilidade ao Work IQ.
  • Uma identidade de utilizador agente com a sua própria caixa de correio - as pessoas podem enviar e-mails diretamente para ela e ela pode enviar e-mails a partir do seu próprio endereço.
  • Uma presença em todas as aplicações Microsoft 365 – as pessoas podem conversar com ela, @mention adicioná-la a canais e convidá-la para reuniões no Teams; e interagir diretamente com ela no Word, Excel, PowerPoint e outras superfícies do M365.
  • Uma entrada no organograma sob um gestor designado – o agente aparece no diretório da organização.
  • Ciclo de vida controlado pelo administrador - o agente é criado, gerido e desativado através do centro de administração Microsoft 365, com governação total sobre cada instância.

O que cria:

Todas as capacidades, além da criação de instâncias e (opcionalmente) a publicação no Marketplace.

Como criar:

Utilize a configuração orientada por IA e responda às perguntas do colega de equipa de IA em conformidade. A configuração orientada por IA executa os passos necessários para este escalão.

Configuração orientada por IA

Utilize um agente de codificação com IA para automatizar a instalação e a configuração do seu agente para o Agent 365. A configuração orientada por IA guia-o através das verificações de pré-requisitos, dos passos de configuração e da integração de código necessárias para permitir capacidades como o registo, a observabilidade, o acesso à ferramenta Work IQ e a funcionalidade de colega de equipa de IA.

Pré-requisitos de configuração orientada por IA

Antes de começar, certifique-se de que tem os seguintes itens:

Necessidade Details
Agente de codificação com IA Visual Studio Code com as extensões GitHub Copilot e GitHub Copilot Chat, ou outro agente de codificação com IA com acesso ao terminal
Código do agente Um projeto de agente funcional em Python, Node.js ou .NET. Se não tiver um, comece com um exemplo de início rápido.
Função do Entra Administrador Global - conclui todos os passos, incluindo a concessão de permissões OAuth2. Programador de ID do Agente - conclui todos os passos, exceto a concessão de permissões OAuth2; a configuração gera uma entrega para um Administrador Global.

Passos de configuração orientados por IA

Estes passos aplicam-se quer esteja a ativar um único agente ou uma fábrica de agentes. O agente de IA verifica as ferramentas necessárias e gere automaticamente a instalação, a autenticação e a validação.

Abra o seu projeto de agente e copie este pedido para o agente de IA à sua escolha. Se estiver a utilizar o GitHub Copilot, altere primeiro para o modo Agente – os modos Perguntar e Editar não têm acesso ao terminal.

Follow the steps at aka.ms/agent365enable to enable my agent for Agent 365.

O agente de IA começa por fazer três perguntas para determinar quais as capacidades que se aplicam ao seu agente:

Pergunta 1: O seu agente já está disponível no Teams ou no Copilot?

  • Sim
  • Não

Pergunta 2: Como é que o seu agente irá autenticar-se ao chamar APIs a jusante?

  • On-behalf-of (OBO) — o agente atua como o utilizador que iniciou sessão (permissões delegadas)
  • Serviço a serviço (S2S) — o agente atua como a sua própria identidade (permissões de aplicação)
  • Ambos (OBO e S2S)

Pergunta 3: Que capacidades do Agent 365 quer ativar?

A configuração inclui automaticamente todas as capacidades necessárias para a sua seleção.

De seguida, o agente de IA percorre automaticamente os escalões aplicáveis, parando apenas para pedir a sua entrada:

Capacidade O que o agente de IA faz 1
Registar Verifica o .NET e a CLI do Agent 365 (instala ou atualiza, se estiver em falta), instala a CLI do Azure se estiver em falta, executa az login caso não esteja autenticado, valida o registo de aplicação cliente personalizada, recolhe o nome do agente e o e-mail do gestor, configura o agente no Portal do Programador do Teams e regista o esquema do agente
Observabilidade Adiciona a instrumentação de observabilidade do Agent 365 SDK ao código do seu agente
Colega de equipa de IA Executa a365 publish e orienta-o através dos passos pós-implementação, incluindo a criação de instâncias de agentes

1 Os passos realizados dependem do tipo de agente e das fases que selecionou no início da configuração.

Importante

Para a Observabilidade, o agente de IA escreve o código diretamente no seu projeto. Os agentes de codificação de IA podem cometer erros. Reveja sempre as alterações antes de colocar em produção.

Informações necessárias para concluir

O agente de IA pausa para recolher a configuração durante a configuração:

Pedido O que fornecer
Nome do agente, e-mail do gestor Metadados básicos do agente
Confirmação do valor derivado Reveja os nomes gerados automaticamente para a identidade do agente, o esquema e principal de utilizador
Revisão do manifesto Confirme se o seu manifest.json está atualizado com o nome do agente, a descrição e as informações do programador

Passos pós-implementação

Quando os escalões automatizados terminam, o agente de IA faz uma pausa por dois passos que exigem interação com o browser:

  1. Criar uma instância de agente

    (Apenas para colegas de equipa de IA) — No Microsoft Teams, vá para Aplicações, procure o seu agente e selecione Adicionar. Se for necessária aprovação do administrador, o seu administrador do Microsoft 365 recebe o pedido. Uma vez aprovado, o seu agente aparece no seu organograma. Para instâncias adicionais, consulte Criar instâncias de agentes. Pode demorar alguns minutos até que um agente recém-publicado apareça na pesquisa do Teams.

  2. Testar o seu agente

    Envie uma mensagem ao seu agente no Teams para verificar se está a funcionar.

Concluído — o seu agente está implementado, publicado e em direto. Consulte Criar instâncias de agentes se precisar de instâncias adicionais.

Se algo não funcionar, o agente de IA fornece assistência específica para resolver problemas. Também pode consultar o Guia de Resolução de Problemas do Agent 365.

Referência do caminho manual

Utilize esta referência apenas se estiver a resolver problemas num passo, a criar a automatização CI/CD ou a trabalhar sem um agente de codificação de IA.

Passo O que faz Guia
Configuração Cria a365.config.json com os detalhes do seu inquilino, da subscrição e do projeto. Se já tiver uma implementação existente, defina aqui o ponto final de mensagens. Configuração do Agent 365
Esquema de configuração Regista a identidade do seu agente no Entra e aprovisiona recursos do Azure (grupo de recursos, Plano do Serviço de Aplicações, Aplicação Web) Configurar esquema de agente
Implementar Implementa o código do seu agente no Serviço de Aplicações do Azure. Opcional se já estiver alojado noutro local. Azure · AWS · GCP
Publicar Cria manifest.zip e carrega para o centro de administração do Microsoft 365 Publicar agente

Para instalação, comandos e resolução de problemas da CLI, consulte CLI do Agent 365.

Publicar o seu agente no Microsoft Marketplace

Após desenvolver e testar completamente o seu agente com o(s) seu(s) próprio(s) inquilino(s), disponibilize-o no Microsoft Marketplace.

Para isso, precisa de uma conta Microsoft AI Cloud Partner Program no Centro de Parceiros. Se não tiver uma, crie uma conta para obter o seu PartnerID. Em seguida, inscreva-se no programa Microsoft 365 e Copilot, que lhe dará acesso aos recursos e ao suporte necessários para publicar ofertas para agentes. Depois de se inscrever, reveja a lista de verificação de submissão e as diretrizes de validação, e depois submeta o seu agente utilizando o guia de submissão passo a passo do Centro de Parceiros.

Saiba como submeter o seu agente ao Microsoft Marketplace utilizando o Centro de Parceiros.

Quando terminar, o seu agente será publicado no Microsoft Marketplace e ficará disponível para os clientes descobrirem e implementarem.

Resolução de problemas da configuração orientada por IA

Se encontrar problemas durante a configuração orientada por IA, consulte os seguintes problemas comuns e as suas soluções.

Problema Descrição
O agente de IA não executa comandos de terminal O agente de IA descreve os comandos, mas não os executa
O agente de IA salta passos A configuração parece saltar os passos obrigatórios
Os comandos da CLI falham com erros de permissão Erros de autorização ao executar comandos da CLI do a365
Os valores de configuração estão incorretos Preciso de mudar a configuração depois de criar a365.config.json

O agente de IA não executa comandos de terminal

Se o agente de IA descrever comandos mas não os executar, verifique se está a utilizar o modo Agente no GitHub Copilot Chat. Os modos Perguntar e Editar não têm acesso ao terminal.

O agente de IA salta passos

O ficheiro de instruções impõe uma ordenação rigorosa dos passos. Se o agente de IA parecer saltar um passo, peça-lhe para começar de novo:

Please start from Step 1 in the setup instructions and work through each step in order.

Os comandos da CLI falham com erros de permissão

Se os comandos da CLI do a365 falharem devido a erros de autorização, a causa mais comum é um registo da aplicação cliente personalizada em falta ou incompleto. O agente de IA valida este registo durante a configuração, mas se a validação foi ignorada, consulte Registo de aplicação cliente personalizada.

Para resolver problemas gerais, consulte o Guia de Resolução de Problemas do Agent 365.

Os valores de configuração estão incorretos

Se precisar de alterar os valores de configuração após criar a365.config.json, ou seja:

  • Edite o ficheiro diretamente e volte a executar a365 config init -c ./a365.config.json
  • Pedir ao agente de IA para atualizar valores específicos
  • Last updated on