Introdução ao desenvolvimento do Agent 365

O Agente 365 funciona com uma variedade de implementações de agente. Um agente pode ajudar os usuários sob demanda, executar de forma autônoma em segundo plano ou operar com sua própria identidade de usuário em Microsoft 365. Entender qual padrão melhor descreve seu agente é importante porque determina o modelo de identidade do agente, qual acesso ele tem para Microsoft 365 recursos e quais etapas de ciclo de vida se aplicam.

Tipos de agentes

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

Há dois tipos de agentes dependendo do tipo de acesso que eles têm:

Tipo de agente Visão geral
Agentes Atue em nome de um usuário com acesso delegado ou opere como um aplicativo com permissões limitadas. Registrado como aplicações do Microsoft Entra ou modelos de identidade de agente.
Companheiro de equipe de IA Opere com sua própria identidade de usuário em Microsoft 365, incluindo caixa de correio, presença do Teams e entrada de diretório. Esse tipo de agente só está disponível para locatários que participam do programa de prévia Frontier.

Agentes

Um agente funciona em nome de um usuário. Ele responde a solicitações, executa tarefas em segundo plano, conecta-se a APIs, processa dados e conduz ações.

Os agentes vêm em todas as formas. Alguns são conversadores - um usuário pergunta algo e o agente responde. Alguns são executados silenciosamente em segundo plano - disparados por uma agenda, um evento ou uma mensagem de entrada - sem ninguém ativamente envolvido. Alguns fazem as duas coisas.

Cenários de exemplo:

  • Um usuário pede a um agente para resumir os seus emails não lidos e elaborar respostas em rascunho. O agente faz o trabalho, acessando apenas os recursos que o usuário pode acessar e devolve o resultado.
  • Um agente de atendimento ao cliente ajuda um engenheiro de suporte a consultar bases de dados de conhecimento internas e redigir respostas durante uma sessão de suporte ao vivo.
  • Um agente de monitoramento de conformidade é executado todas as noites, varre os sites do SharePoint aos quais o agente recebe acesso para detectar violações de política e arquiva relatórios de auditoria - tudo isso sem ninguém supervisionando.
  • Um agente de processamento de pedidos pega novos pedidos de vendas de uma fila, atualiza um CRM e envia e-mails de confirmação - tudo isso sem que ninguém precise iniciar o processo.

Base de identidade:

Tradicionalmente, você cadastra agentes como aplicativos do Microsoft Entra. Essa abordagem continua funcionando. De agora em diante, você também pode criar agentes em um ID do agente Microsoft Entra por meio de um modelo de identidade de agente - a definição aprovada por TI e imposta por governança das capacidades de um agente, acesso permitido às ferramentas e restrições de conformidade. A criação de um blueprint é o caminho recomendado para novos agentes. Ele desbloqueia o acesso à ferramenta Intelligence de Trabalho governada, proteção de dados do Microsoft Purview, monitoramento de ameaças com o Microsoft Defender e governança do Entra ID - tornando seu agente uma identidade empresarial completamente governada desde o primeiro dia.

Colega de equipe de IA

Importante

Para obter acesso antecipado a esse tipo de agente, você precisa fazer parte do programa de prévia Frontier. A Frontier conecta você diretamente com as inovações de IA mais recentes da Microsoft. As versões preliminares da Frontier estão sujeitas aos termos de versão preliminar existentes dos contratos de cliente. Uma vez que estas funcionalidades ainda estão em desenvolvimento, a disponibilidade e as capacidades podem mudar ao longo do tempo.

Um colega de equipe de IA opera em Microsoft 365 usando sua própria identidade de agente. Você pode provisioná-lo com recursos como enviar e receber emails por meio de sua própria caixa de correio, participar do Teams 1:1 e de conversas em grupo e aparecer em diretórios e metadados organizacionais com uma relação de gerente atribuída. As pessoas podem interagir com ele por meio de pontos de entrada Microsoft 365 familiares, como @mentions, email, convites de calendário e chat do Teams.

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

O que o agente faz — seja conversacional, ou em segundo plano, ou ambos — depende de como você o desenha. Alguns agentes são altamente interativos, respondendo a mensagens e dando suporte ao trabalho em tempo real. Outras pessoas processam tarefas em segundo plano, agindo em emails ou eventos sem envolvimento direto do usuário. O agente opera com sua própria identidade de usuário e suas ações são governadas e auditáveis por meio dessa identidade.

Se você já tem um agente, não precisa recomeçar. Os agentes existentes podem ser estendidos para operar com sua identidade própria, adicionando a identidade individual e a configuração de plano descritas mais adiante neste guia.

Cenários de exemplo:

  • Adicione um companheiro de equipe de IA de integração de RH ao canal de integração do Teams de um novo contratado. Ele envia emails de boas-vindas de sua própria caixa de correio, agenda reuniões de orientação em seu próprio calendário e responde a perguntas usando os recursos configurados para essa instância do agente.
  • Atribua uma relação de gerenciamento em metadados de diretório a um colega de equipe para IA de aquisições. Os funcionários enviarão solicitações de compra por email para sua caixa de correio. O agente processa a solicitação, consulta os sistemas ERP e financeiros usando seu acesso governado à ferramenta Work IQ e responde com aprovação ou escalonamento sob sua própria identidade.
  • Adicione um colega de equipe de IA de pesquisa ao site de SharePoint de uma equipe de projeto e ao canal do Teams. Ele pode exibir documentos relevantes durante reuniões, responder em threads de conversa e elaborar relatórios de status semanais usando as permissões e ferramentas configuradas para esse agente.

Base de identidade:

Criado com base em um blueprint de identidade do agente, que cria um ID do agente Microsoft Entra e uma conta de usuário associada, sempre exigido.

Adicionando funcionalidades do Agente 365 incrementalmente

Agente 365 não é tudo ou nada. Você não precisa criar um parceiro de IA no primeiro dia - ou de modo algum, se seu cenário não exigir isso. Adote funcionalidades de forma incremental, começando com o que seu agente precisa agora e expandindo à medida que seus requisitos evoluem.

Por que desenvolver um projeto de identidade para agentes?

Quando você cria um plano de identidade do agente, a CLI do Agent 365 provisiona um ID do agente Microsoft Entra para seu agente - uma identidade de primeira classe em seu ambiente, estando sujeito às mesmas políticas de governança empresarial que os usuários humanos. Essa única identidade é a base para os benefícios de segurança que fluem automaticamente para cada agente baseado em projeto.

Benefício O que significa para seu agente
Governança do Microsoft Entra ID O ciclo de vida de acesso e identidade do agente é gerenciado por meio do mesmo Acesso Condicional, proteção de identidade e revisões de acesso que se aplicam a usuários humanos.
Microsoft Purview Cada interação de dados executada pelo agente está sujeita aos rótulos de confidencialidade do locatário, às políticas de DLP e às políticas de retenção – automaticamente, sem código extra.
Microsoft Defender O comportamento do agente é monitorado continuamente para anomalias e ameaças. A atividade suspeita dispara os mesmos alertas e fluxos de trabalho de resposta que para qualquer usuário no locatário.

Esses benefícios se aplicam a todos os agentes orientados por blueprint, incluindo tanto agentes com acesso delegado pelo usuário quanto agentes que operam com suas próprias identidades, assim que o blueprint é criado. Você não precisa configurá-los separadamente.

As quatro camadas de capacidade abaixo representam níveis que você pode adotar incrementalmente. A tabela a seguir mostra o que está disponível para o Agente 365 com base no seu ponto de partida:

Capability Agente de motor personalizado do Microsoft 365 Todos os outros agentes 1
Registrar ✓ 2 ✓
Observabilidade ✓ ✓
Qi de trabalho ✓ ✓
Companheiro de IA ✓ 3 ✓ 3

1 Agentes que estão atualmente registrados como aplicativos Microsoft Entra devem primeiro criar um esquema de identidade de agente para começar com qualquer funcionalidade nesta coluna.

2 agentes personalizados de mecanismo do Microsoft 365 já estão cadastrados usando o registro existente de aplicativo do Microsoft Entra – sem necessidade de configuração adicional.

3 companheiro de IA para agentes de mecanismo personalizados do Microsoft 365 requer um blueprint de identidade de agente. Disponível somente para participantes do programa Frontier .

PDV

Registrar seu agente torna-o visível e gerenciável no Centro de administração do Microsoft 365. Os administradores podem descobri-lo e vê-lo no inventário de agentes de sua organização.

O que você obtém:

  • 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 organização.
  • Os agentes baseados em blueprint também recebem os benefícios completos de governança do Entra ID, Purview e Defender descritos em Por que construir em um blueprint de identidade do agente?

O que você cria:

Registre seu agente usando seu registro de aplicativo Microsoft Entra existente ou um blueprint.

Note

Se seus agentes forem criados com base na IA do Google Vertex ou na Amazon Bedrock, o registro não exigirá nenhum trabalho de desenvolvimento – os agentes serão retirados automaticamente por meio das APIs do Google e da Amazon. Nenhuma integração do SDK, nenhum blueprint e nenhuma alteração de código são necessárias. Depois de registrado, você pode usar o SDK do Agent 365 para adicionar observabilidade, acesso à ferramenta Work IQ e outros recursos de forma incremental. Consulte Registro de agentes do Google Vertex AI e da Amazon Bedrock para começar.

Como você o cria:

Use a configuração guiada por IA e responda às perguntas de tipo de agente adequadamente. A configuração orientada por IA executa as etapas necessárias para essa camada. Microsoft 365 agentes personalizados já podem ser descobertos hoje usando o registro de aplicativo Microsoft Entra existente.

Observability

Depois que seu agente for registrado, o próximo investimento será em observabilidade, dando às equipes de TI, equipes de segurança e à sua própria equipe de engenharia visibilidade sobre o que seu agente está realmente fazendo. Cada chamada de inferência, invocação de ferramenta e interação é capturada, rastreada e tornada auditável.

A observabilidade é a base para a confiança. Sem ele, os administradores não têm como verificar o comportamento, a conformidade de auditoria ou diagnosticar problemas em escala. Com ele, seu agente se torna um ativo da empresa em vez de uma caixa preta.

O que você obtém:

  • Rastreamento completo [OpenTelemetry (OTel) ](https://opentelemetry.io/docs/specs/otel/protocol/) baseado em cada interação do agente: entradas, saídas, chamadas de ferramenta e invocações de modelo.
  • Atividade visível no Centro de administração do Microsoft 365 e superfícies de monitoramento conectadas.
  • Trilhas de auditoria que se integram com Microsoft Entra, Microsoft Purview e Microsoft Defender, oferecendo suporte a requisitos de conformidade, proteção de dados e resposta a ameaças.

O que você cria:

Instrumentação usando as APIs de observabilidade do SDK do Agent 365: auto-instrumentação (se você estiver usando OpenAI, LangChain ou Agent Framework) ou instrumentação manual para outras tecnologias.

Como você o cria:

Use a configuração guiada por IA e responda às perguntas de observabilidade adequadamente. A instalação guiada por IA executa as etapas necessárias para essa capacidade.

QI de trabalho

Depois de registrar e tornar seu agente observável, dê a ele acesso aos dados e ações do Microsoft 365 por meio do Work IQ. O IQ de Trabalho é um conjunto controlado de ferramentas que permite que seu agente trabalhe com Email, Calendário, OneDrive, SharePoint, Teams e muito mais.

Ferramentas de Work IQ requerem consentimento do administrador, são auditadas e revogáveis. Seu agente os chama usando as permissões definidas em seu blueprint – nenhum fluxo OAuth extra ou conectores personalizados necessários.

O que você obtém:

  • Acesso ao catálogo completo de ferramentas Work IQ – E-mail, Calendário, OneDrive, SharePoint, Teams e muito mais.
  • Permissões que os administradores controlam e limitam exatamente ao que seu agente precisa.
  • Cada chamada de ferramenta rastreada e auditável por meio do pipeline de observabilidade.

O que você cria:

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

Como você o cria:

Use as APIs de ferramentas do SDK do Agent 365 para adicionar chamadas da ferramenta Work IQ ao código do agente manualmente. Atualmente, a instalação orientada por IA não dá suporte a essa funcionalidade.

Colega de equipe de IA

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

A fase final permite que seu agente opere em Microsoft 365 com sua própria identidade. Dependendo da configuração, ele pode ter uma caixa de correio, presença no Teams, entrada de diretório e relação com o gerente. As pessoas podem interagir com ele por meio de experiências Microsoft 365 familiares, como e-mail, chat, reuniões e interfaces de aplicativo.

Note

Mudança de modelo de identidade e permissões

A mudança para um colega de equipe de IA representa uma alteração fundamental na forma como o agente acessa os recursos. Seu agente existente pode usar o acesso de usuário delegado, no qual o agente atua em nome de um usuário conectado e pode acessar apenas os recursos que esse usuário pode acessar, ou permissões de aplicativo associadas a uma entidade de serviço. Um agente com uma identidade de usuário não herda, em tempo de execução, o acesso de um usuário que realiza chamadas. Em vez disso, opera sob sua própria identidade de usuário, com suas próprias concessões de acesso, políticas de governança e trilha de auditoria.

Isso significa:

  • No acesso delegado ao usuário, o agente atua em nome do usuário conectado e está limitado ao acesso desse usuário. Com a própria identidade de um agente, você concede acesso a recursos de Microsoft 365, como caixa de correio, calendário, Teams e SharePoint diretamente à identidade do agente.
  • Você governa e audita as permissões concedidas à identidade do agente, tratando essas permissões como o próprio acesso do agente. Elas não são as mesmas que as permissões delegadas pelo usuário que são transmitidas a partir do usuário que realiza a chamada.
  • Se a implementação atual depender de permissões delegadas de acesso de usuário ou de aplicativo, examine e refinar essas permissões para a identidade do agente antes de habilitar essa funcionalidade.

O que você obtém:

  • Tudo, desde Discoverability, Observability e Work IQ.
  • Uma identidade de usuário de agente com sua própria caixa de correio - as pessoas podem enviar mensagens para ela diretamente e ela pode enviar e-mails do seu próprio endereço.
  • Uma presença nos aplicativos Microsoft 365 - as pessoas podem conversar com ele, @mention-lo, adicioná-lo a canais e convidá-lo para reuniões no Teams; além de interagir com ele diretamente no Word, Excel, PowerPoint e outras plataformas M365.
  • Uma entrada de organograma sob um gerente designado – o agente aparece no diretório da organização.
  • Ciclo de vida controlado pelo administrador – o agente é criado, gerenciado e desativado por meio do Centro de administração do Microsoft 365, com governança total em todas as instâncias.

O que você cria:

Todos os recursos, mais criação de instância e (opcionalmente) publicação do Marketplace.

Como você o cria:

Use a configuração guiada por IA e responda às perguntas do companheiro de equipe de IA adequadamente. A configuração orientada por IA executa as etapas necessárias para essa camada.

Configuração guiada por IA

Use um agente de codificação de IA para automatizar a configuração e a configuração do agente para o Agente 365. A instalação guiada por IA orienta você pelas verificações de pré-requisitos, etapas de configuração e integração de código necessárias para habilitar recursos como registro, observabilidade, acesso à ferramenta Work IQ e funcionalidade de assistente de equipe de IA.

Pré-requisitos de instalação guiados por IA

Antes de começar, verifique se você tem os seguintes itens:

Requisito Detalhes
Agente de codificação de IA Visual Studio Code com extensões GitHub Copilot e GitHub Copilot Chat ou outro agente de codificação de IA com acesso ao terminal
Código do agente Um projeto de agente de trabalho em Python, Node.jsou .NET. Se você não tiver um, comece com um exemplo de início rápido.
Função de entrada Administrador global – conclui todas as etapas, incluindo concessões de permissão OAuth2. Desenvolvedor de ID do agente – conclui todas as etapas, exceto concessões de autorização OAuth2; a configuração gera uma transferência para um Administrador Global.

Etapas de instalação orientadas por IA

Estas etapas se aplicam se você está habilitando um único agente ou uma fábrica de agentes. O agente de IA verifica as ferramentas necessárias e manipula automaticamente a instalação, a autenticação e a validação.

Abra o projeto do agente e copie esse prompt para o agente de IA de sua escolha. Se você estiver usando GitHub Copilot, alterne para o modo Agent primeiro – 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 fazendo três perguntas para determinar quais recursos se aplicam ao seu agente:

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

  • Yes
  • No

Pergunta 2: Como seu agente se autenticará ao chamar APIs downstream?

  • On-behalf-of (OBO) – o agente atua como o usuário conectado (permissões delegadas)
  • Serviço-para-serviço (S2S) – o agente funciona como sua própria identidade (permissões de aplicação)
  • Ambos (OBO e S2S)

Pergunta 3: Quais recursos do Agente 365 você deseja habilitar?

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

O agente de IA funciona automaticamente nas camadas aplicáveis, pausando apenas para solicitar sua entrada:

Capability O que o agente de IA faz 1
Registrar Verifica se há .NET e CLI do Agente 365 (instala ou atualiza se estiver ausente), instala CLI do Azure se estiver ausente, executa az login se não estiver autenticado, valida o registro do seu aplicativo cliente personalizado, coleta o nome do agente e o e-mail do gerente, configura seu agente no Portal de Desenvolvedores do Teams e registra o modelo do agente.
Observabilidade Incorpora a instrumentação de observação do SDK Agent 365 ao seu código de agente
Companheiro de equipe de IA Executa a365 publish e orienta você pelas etapas pós-implantação, incluindo a criação de instância de agente

1 As etapas executadas dependem do tipo de agente e das fases selecionadas no início da configuração.

Importante

Para Observabilidade, o agente de IA grava o código diretamente em seu projeto. Agentes de codificação de IA podem cometer erros. Sempre examine as alterações antes de implantar na produção.

Informações necessárias para completar

O agente de IA faz uma pausa para coletar a configuração durante a instalação:

Rápido O que fornecer
Nome do agente, email do gerente Metadados básicos do agente
Confirmação de valor derivado Examinar nomes gerados automaticamente para a identidade do agente, o blueprint e o principal do usuário
Revisão de manifesto Confirme que o seu manifest.json está atualizado com o nome, a descrição e as informações do desenvolvedor do agente.

Etapas de pós-implantação

Quando as camadas automatizadas são concluídas, o agente de IA pausa duas etapas que exigem interação com o navegador:

  1. Crie uma instância de agente

    (somente equipe de IA) — no Microsoft Teams, vá para Apps, pesquise seu agente e selecione Add. Se a aprovação do administrador for necessária, o administrador do Microsoft 365 receberá a solicitação. Depois de aprovado, o agente aparece no organograma. Para obter instâncias adicionais, consulte Criar instâncias de agente. Pode levar alguns minutos para 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 ele está funcionando.

Concluído – seu agente é implantado, publicado e em operação. Consulte Criar instâncias de agente se você precisar de instâncias adicionais.

Se algo não funcionar, o agente de IA fornecerá solução de problemas direcionada. Você também pode consultar o Guia de Solução de Problemas do Agente 365.

Referência de caminho manual

Use essa referência somente se você estiver solucionando problemas de uma etapa, criando automação de CI/CD ou trabalhando sem um agente de codificação de IA.

Etapa O que ele faz Guide
Configuração de instalação Cria a365.config.json com seu locatário, assinatura e detalhes do projeto. Se você tiver uma implantação existente, configure o ponto de extremidade das mensagens aqui. Configuração do Setup Agent 365
Blueprint de instalação Registra a identidade do agente no Entra e provisiona recursos Azure (grupo de recursos, Plano do Serviço de Aplicativo, Aplicativo Web) Projeto do agente de configuração
Implantar Implanta o código do agente no Serviço de Aplicativo do Azure. Opcional se já estiver hospedado em outro lugar. Azure · AWS · GCP
Publish Cria manifest.zip e carrega para Centro de administração do Microsoft 365 Agente de publicação

Para instalação, comandos e solução de problemas da CLI, consulte a CLI do Agente 365.

Publicar seu agente no Microsoft Marketplace

Depois de desenvolver e testar totalmente seu agente em seu próprio locatário ou locatários, disponibilize-o no Microsoft Marketplace.

Para fazer isso, você precisa de uma conta do Microsoft AI Cloud Partner Program no Partner Center. Se você não tiver uma, crie uma conta para obter sua PartnerID. Em seguida, inscreva-se no programa Microsoft 365 e Copilot, que oferece acesso aos recursos e suporte necessários para publicar ofertas de agentes. Depois de registrado, examine a lista de verificação de envio e as diretrizes de validação e envie seu agente por meio do guia de envio passo a passo do Partner Center.

Saiba como enviar seu agente para o Microsoft Marketplace usando o Partner Center.

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

Solução de problemas da configuração guiada por IA

Se você encontrar problemas durante a instalação guiada por IA, consulte os seguintes problemas comuns e suas soluções.

Problema Description
O agente de IA não executa comandos de terminal O agente de IA descreve os comandos, mas não os executa
Agente de IA pula etapas A instalação parece ignorar as etapas necessárias
Os comandos da CLI falham com erros de permissão Erros de autorização ao executar comandos da CLI a365
Os valores de configuração estão errados Precisa alterar a configuração depois de criar a365.config.json

Agente de IA não executa comandos de terminal

Se o agente de IA descreve comandos, mas não os executa, verifique se você está usando o modo Agent no chat GitHub Copilot. Os modos Perguntar e Editar não têm acesso ao terminal.

Agente de IA ignora etapas

O arquivo de instruções impõe uma ordenação rigorosa de passos. Se o agente de IA parecer ignorar uma etapa, peça para o agente começar novamente.

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

Comandos CLI falham com erros de permissão

Se a365 os comandos CLI falharem com erros de autorização, a causa mais comum é o registro de aplicativo personalizado ausente ou incompleto. O agente de IA valida isso durante a configuração, mas se a validação foi ignorada, consulte registro personalizado de aplicativo cliente.

Para obter solução de problemas gerais, consulte o Guia de solução de problemas do Agente 365.

Valores de configuração estão errados

Se você precisar alterar os valores de configuração após a criação de a365.config.json, faça uma das seguintes opções: ou continue com a próxima etapa, ou escolha uma alternativa adequada.

  • Editar o arquivo diretamente e executar novamente a365 config init -c ./a365.config.json
  • Peça ao agente de IA para atualizar valores específicos
  • Last updated on