Building Microsoft 365 Copilot Apps from Zero

Guia técnico e prático para compreender e construir Declarative Agents com Microsoft 365 Agents Toolkit, evoluindo de um Agent mínimo para Knowledge, SharePoint, Actions e uma arquitetura corporativa governada.

Microsoft 365 Copilot extensibility deve ser entendida como uma extensão do ecossistema de aplicações do Microsoft 365, e não simplesmente como a criação de um chatbot. A documentação oficial descreve Declarative Agents como versões especializadas do Microsoft 365 Copilot, definidas por configuração de identidade, comportamento, capabilities e Knowledge. O mesmo Agent pode posteriormente receber Actions e integrações, mas neste artigo começaremos deliberadamente pela menor arquitetura possível.

Tutorial oficial que guia este artigo:
Microsoft Learn — Tutorial: Create declarative agents by using Microsoft 365 Agents Toolkit

Documentação central:
Microsoft 365 Copilot extensibility documentation

1. Antes do tutorial: o que estamos construindo?

A Microsoft documenta que um Declarative Agent customiza o Microsoft 365 Copilot para um cenário de negócio. Ele continua utilizando o orchestrator, foundation models e serviços de IA confiáveis que sustentam o Microsoft 365 Copilot. O desenvolvedor fornece configuração que especializa esse comportamento.

Uma forma útil de começar a pensar é:

Microsoft 365 Copilot + Declarative Agent ├── Instructions ├── Knowledge └── Actions ↓ Specialized business experience

Instructions descrevem propósito, comportamento e limites. Knowledge fornece informação que pode sustentar respostas. Actions adicionam operações que o Agent pode executar. Knowledge e Action não devem ser confundidos: consultar uma política corporativa é um problema de conhecimento; criar uma solicitação no SharePoint é uma operação.

2. Agents também são Microsoft 365 Apps

Um conceito arquitetural especialmente importante para desenvolvedores Microsoft 365 é que, ao construir um Agent, também estamos construindo um app para Microsoft 365. A Microsoft utiliza um modelo comum de manifest, packaging, distribuição e administração.

Leia também:

Microsoft Learn — Agents are apps for Microsoft 365

Isso aproxima Agent development de práticas já conhecidas em desenvolvimento Microsoft 365: projeto fonte, manifestos, package, assets, provisionamento, publicação, governança e ciclo de vida.

3. Qual ferramenta usar?

A Microsoft oferece caminhos pro-code, low-code e no-code. Para este artigo usaremos Microsoft 365 Agents Toolkit, porque queremos enxergar o projeto e o lifecycle de um Agent como software. Depois, o mesmo modelo conceitual pode ser comparado ao Copilot Studio.

Referência: Choose the right tool to build a declarative agent.

4. O laboratório oficial que vamos reproduzir

O primeiro tutorial da Microsoft é propositalmente pequeno. Ele exige Visual Studio Code e a extensão Microsoft 365 Agents Toolkit, cria um Declarative Agent básico, provisiona esse Agent e o testa no Microsoft 365 Copilot. Essa simplicidade é uma vantagem: ela permite provar o lifecycle antes de adicionar SharePoint, Graph, REST, Power Automate ou outras variáveis.

5. Pré-requisitos

Segundo o tutorial atual, precisamos de Visual Studio Code e da extensão Microsoft 365 Agents Toolkit. O cenário também pressupõe uma organização Microsoft 365 adequada e disponibilidade/licenciamento compatível com o Microsoft 365 Copilot. A documentação observa que o Agent desse tutorial é direcionado a usuários licenciados para Microsoft 365 Copilot; existem também cenários para Copilot Chat com capacidades limitadas.

Importante: ferramenta de desenvolvimento, licença do criador e entitlement do usuário final são assuntos diferentes. Não devemos concluir que todos os usuários terão automaticamente as mesmas capacidades apenas porque o Agent pôde ser criado.

6. Passo a passo — criando o primeiro Declarative Agent

Abra o Visual Studio Code

O projeto será criado em um ambiente de desenvolvimento convencional. Isso é importante porque, a partir daqui, podemos tratar a definição do Agent como parte de um projeto versionável e não apenas como configuração escondida em uma interface web.

Abra Microsoft 365 Agents Toolkit

No sidebar do Toolkit, selecione Create a New Agent/App. A expressão “Agent/App” é significativa: estamos entrando no modelo unificado de aplicações do Microsoft 365.

Selecione Declarative Agent

Escolher Declarative Agent significa que especializaremos o Microsoft 365 Copilot declarando comportamento e capacidades. Não estamos criando, neste laboratório, um runtime de IA totalmente independente.

Selecione No Action

O tutorial inicial mantém o Agent sem Action. Arquiteturalmente isso é excelente: se algo falhar, não precisamos investigar simultaneamente autenticação, API, parâmetros, workflow e sistema externo.

Escolha a pasta e o nome

Selecione Default folder ou seu workspace e informe My Agent como Application Name, acompanhando o tutorial oficial. Em um projeto real, o código normalmente terminaria sob Git e um lifecycle de engenharia mais formal.

7. Pare antes de provisionar: examine o projeto

O Learn avança rapidamente para Provision, mas vale observar o projeto gerado. O objetivo aqui não é decorar cada arquivo de uma versão específica do Toolkit. É perceber que o Agent possui artefatos declarativos que podem ser inspecionados, versionados, validados e posteriormente empacotados.

Source repository ↓ Agent configuration / manifests ↓ Microsoft 365 Agents Toolkit ↓ Provision / Package / Deploy ↓ Microsoft 365

Essa visão é particularmente útil para quem vem de SPFx: embora os artefatos e runtime sejam diferentes, a disciplina mental de tratar configuração, source control, environments e deployment como partes do produto continua válida.

8. Provision

No novo projeto, abra Microsoft 365 Agents Toolkit. No painel Lifecycle, selecione Provision. Provision não deve ser mentalmente traduzido como “executar o chatbot”. Trata-se de preparar/configurar no ambiente Microsoft 365 os recursos necessários para que o Agent exista e possa ser usado.

Local Agent Project ↓ Lifecycle: Provision ↓ Microsoft 365 environment ↓ Declarative Agent available to the target experience

Nesse ponto, valide cuidadosamente a conta e o tenant usados. Em ambientes de consultoria é comum possuir identidades de DEV, cliente, demonstração e produção; provisionar no tenant errado é uma falha operacional perfeitamente possível.

9. Testando no Microsoft 365 Copilot

O tutorial orienta abrir Microsoft 365 Copilot, abrir o conversation drawer próximo de New Chat, selecionar My Agent e enviar uma pergunta.

O teste prova a primeira vertical slice completa:

Developer ↓ Visual Studio Code ↓ Agents Toolkit ↓ Declarative Agent project ↓ Provision ↓ Microsoft 365 ↓ Microsoft 365 Copilot ↓ My Agent ↓ User prompt / response

10. O que esse primeiro teste prova — e o que não prova

Se o Agent aparece e responde, provamos o lifecycle básico. Ainda não provamos SharePoint Knowledge, Retrieval, Grounding, Actions, Power Automate, REST APIs, Microsoft Graph ou autenticação externa. Essa separação é deliberada.

Princípio de laboratório: mude uma variável arquitetural por vez. Quando o Agent mínimo funciona, temos uma baseline. Tudo que adicionarmos depois pode ser comparado contra essa baseline.

11. Segundo tutorial oficial: TypeSpec

Depois do Agent mínimo, o tutorial mais interessante para uma evolução pro-code é:

Microsoft Learn — Create declarative agents using Microsoft 365 Agents Toolkit and TypeSpec

O guia atual passa por criação do Agent, Instructions, Conversation Starters, web content, OneDrive e SharePoint, Teams messages, people knowledge, email knowledge, image generator, code interpreter e Copilot connectors.

12. Instructions com TypeSpec

No tutorial TypeSpec, o arquivo main.tsp passa a ser central. O decorator @instructions representa as Instructions que serão colocadas na definição do Agent durante provisioning.

Conceitualmente:

main.tsp ↓ @instructions(…) ↓ Provision ↓ Declarative Agent manifest/configuration ↓ Agent behavior

Isso evidencia uma distinção fundamental: Instructions alteram comportamento; não adicionam fatos corporativos por si mesmas.

13. Conversation Starters

O tutorial adiciona @conversationStarter. Conversation Starters ajudam o usuário a descobrir o escopo do Agent e iniciar interações adequadas. Eles fazem parte do design da experiência, não da base factual do Agent.

Um SharePoint Technical Agent poderia, por exemplo, sugerir: “Find our SPFx development standards”, “Explain our SharePoint provisioning process” ou “Where is the production deployment checklist?”.

14. Knowledge: quando o Agent começa a usar conteúdo corporativo

A Microsoft possui um tutorial específico para acrescentar Knowledge a um Agent já criado com Agents Toolkit:

Microsoft Learn — Add knowledge sources to a declarative agent created with Microsoft 365 Agents Toolkit

O guia atual aborda web search, SharePoint, Teams messages, people knowledge, email messages e Microsoft 365 Copilot connectors. Para nosso percurso, SharePoint é o cenário corporativo mais importante.

15. Nosso primeiro cenário SharePoint

Imagine uma biblioteca Corporate Policies contendo políticas aprovadas. O Agent deixa de ser apenas um Agent com Instructions e passa a possuir uma fonte corporativa de informação.

Employee ↓ Microsoft 365 Copilot ↓ Corporate Policy Agent ↓ Instructions ↓ SharePoint Knowledge ↓ Retrieval ↓ Relevant evidence/context ↓ Grounded generative response

Essa é a arquitetura que deve ser dominada antes de introduzirmos operações transacionais. O fato de uma fonte ser conectada não elimina as questões de identidade, autorização e qualidade do conteúdo.

16. Knowledge não é Action

Essa separação reduz ambiguidade arquitetural. Um LLM pode interpretar intenção e linguagem; uma operação empresarial sensível deve ser implementada por uma capability explicitamente definida e governada.

17. Evolução para Power Automate

Depois de dominar Knowledge, podemos introduzir uma Action pequena: criar um item em uma lista SharePoint. Uma arquitetura possível é:

User ↓ Agent ↓ Action / Tool ↓ Power Automate ↓ SharePoint List ↓ Create Item ↓ Structured result ↓ Agent ↓ User confirmation

Nessa etapa precisaremos responder perguntas que não existiam no Agent somente de Knowledge: quais parâmetros passam do Agent ao Flow? Qual connection executa o Flow? Com qual identidade? Quais permissões essa identidade possui? Qual resultado volta ao Agent?

18. REST APIs vêm depois

Uma Action também pode integrar um serviço REST. O padrão geral é:

User intent ↓ Agent ↓ API Action ↓ HTTP / OpenAPI contract ↓ External system ↓ JSON ↓ Agent ↓ Natural-language or structured presentation

A documentação atual também suporta API plugins como custom actions de Declarative Agents. Nesse estágio, OpenAPI, métodos HTTP, parâmetros, schemas, autenticação, erros e rate limits passam a fazer parte da arquitetura.

19. Microsoft Graph não deve ser reflexo automático

Microsoft Graph é poderoso, mas deve entrar quando uma necessidade concreta justificar seu uso. Antes dele, verifique se o requisito é atendido por capability nativa, SharePoint, Power Automate, Connector ou outra integração suportada.

Quando Graph for necessário, documente pelo menos: endpoint, método HTTP, request, response, scopes, autenticação, Delegated versus Application permissions, consent e princípio de least privilege.

20. Segurança acompanha o laboratório inteiro

Segurança não é uma seção adicionada apenas antes da produção. Cada nova capability muda o modelo de risco.

21. Copilot Studio como segundo caminho

Depois de compreender o fluxo pro-code, vale reproduzir conceitos semelhantes no Copilot Studio. A Microsoft mantém o módulo:

Build your first declarative agent for Microsoft 365 Copilot by using Copilot Studio

O módulo atual cobre criação de um Declarative Agent, custom Knowledge, suggested prompts, publicação/uso e validação. Isso cria uma comparação excelente entre o modelo pro-code do Agents Toolkit e o modelo low-code do Copilot Studio.

22. Roadmap prático depois deste artigo

23. Arquitetura-alvo

Depois dos laboratórios, nossa visão deixa de ser “Agent = chatbot” e passa a ser uma arquitetura governada:

Microsoft 365 User ↓ Microsoft 365 Copilot ↓ Declarative Agent ↓ Instructions + Orchestration ↓ ┌───────────────┬────────────────┐ │ Knowledge │ Actions │ │ SharePoint │ Power Automate │ │ Web / M365 │ REST APIs │ │ Connectors │ Graph* │ └───────────────┴────────────────┘ ↓ Enterprise information / business process ↓ Governed business outcome * quando houver necessidade arquitetural real

24. Referências oficiais

• Microsoft 365 Copilot extensibility documentation
• Create declarative agents using Microsoft 365 Agents Toolkit
• Agents are apps for Microsoft 365
• Choose the right tool to build a declarative agent
• Create declarative agents using Agents Toolkit and TypeSpec
• Add knowledge sources to a declarative agent
• Build your first declarative agent using Copilot Studio

Conclusão

O primeiro objetivo não é construir um grande assistente corporativo. É provar e compreender a menor vertical slice possível: Visual Studio Code → Agents Toolkit → Declarative Agent → Provision → Microsoft 365 Copilot → resposta. Depois alteramos Instructions, adicionamos Conversation Starters, introduzimos Knowledge e finalmente SharePoint. Actions só entram quando a arquitetura de conhecimento já está compreendida.

Essa progressão permite que cada novo comportamento seja explicado. Em vez de construir um Agent complexo e tentar descobrir por que ele funciona, construímos uma arquitetura cuja evolução conseguimos observar, testar e documentar.