Cenários do agente TypeSpec para Microsoft 365 Copilot

Dica

Recomendado: Comece com o Work IQ Dev Tools para cenários de plug-in e de agente declarativo de código profissional com suporte. Consulte o início rápido do WIQD. As instruções baseadas em kit de ferramentas permanecem disponíveis para projetos e fluxos de trabalho existentes que as exigem. Verifique a capacidade e o suporte à experiência de destino antes de escolher uma ferramenta: O WIQD não tem como alvo agentes de mecanismo personalizados.

Este guia fornece exemplos completos de como criar agentes TypeSpec para o Microsoft 365 Copilot, desde agentes básicos simples até implementações complexas com vários recursos e métodos de autenticação.

Agente básico sem funcionalidades

Caso de uso: Um agente simples que fornece informações básicas e saudações sem integrações externas ou recursos especiais.

O que ele faz: esse agente pode responder a perguntas simples, fornecer informações gerais e ter conversas básicas. Ele não precisa acessar APIs externas, pesquisar na Web ou acessar dados do Microsoft 365.

import "@typespec/http";
import "@typespec/openapi3";
import "@microsoft/typespec-m365-copilot";

using TypeSpec.Http;
using TypeSpec.M365.Copilot.Agents;

@agent("Basic Helper Agent", "A simple agent that provides basic information and assistance")
@instructions("""
  You are a helpful assistant that provides basic information and support.
  Be friendly, professional, and helpful in all interactions. Provide clear,
  concise answers to user questions. If you don't know something, be honest
  about your limitations and suggest alternative ways to find the information.
""")
namespace BasicHelperAgent {
  // No capabilities defined - agent relies only on built-in conversational abilities
}

Agente com vários recursos

Caso de uso: Um assistente de trabalhador do conhecimento que pode pesquisar informações na Web, acessar o conteúdo do SharePoint de uma organização e encontrar informações sobre colegas na organização.

O que faz: esse agente ajuda os trabalhadores do conhecimento combinando pesquisa na Web por informações externas, acesso a arquivos para recuperação de documentos e pesquisa de pessoas para encontrar colegas e suas informações de contato. Esse padrão se ajusta a cenários de pesquisa e colaboração.

import "@typespec/http";
import "@typespec/openapi3";
import "@microsoft/typespec-m365-copilot";

using TypeSpec.Http;
using TypeSpec.M365.Copilot.Agents;

@agent("Knowledge Worker Assistant", "An intelligent assistant that helps with research, file management, and finding colleagues")
@instructions("""
  You are a knowledgeable research assistant specialized in helping knowledge workers
  find information efficiently. You can search the web for external research, access
  SharePoint documents for organizational content, and help locate colleagues within
  the organization. Always provide comprehensive research results, cite your sources,
  and suggest additional resources when relevant. When searching for people, respect
  privacy and only share publicly available organizational information.
""")
namespace KnowledgeWorkerAgent {
  // Web search capability for external research
  op webSearch is AgentCapabilities.WebSearch<Sites = [
    {
      url: "https://learn.microsoft.com";
    },
    {
      url: "https://www.microsoft.com";
    }
  ]>;

  // OneDrive and SharePoint access for document retrieval
  op oneDriveAndSharePoint is AgentCapabilities.OneDriveAndSharePoint<
    ItemsByUrl = [
      { url: "https://contoso.sharepoint.com/sites/IT" }
    ]
  >;

  // People search for finding colleagues
  op people is AgentCapabilities.People;
}

Agente simples com ação de API anônima

Caso de uso: um agente de gerenciamento de instalações que ajuda os usuários a relatar e rastrear problemas de manutenção usando uma API de reparos públicos.

O que faz: Este agente permite que os usuários relatem problemas nas instalações (equipamentos quebrados, problemas de iluminação, etc.) e marcar o status das solicitações de reparo existentes. A API de reparos é acessível publicamente e não requer autenticação, facilitando a comunicação de problemas por qualquer pessoa.

import "@typespec/http";
import "@typespec/openapi3";
import "@microsoft/typespec-m365-copilot";
import "./actions.tsp";

using TypeSpec.Http;
using TypeSpec.M365.Copilot.Agents;
using TypeSpec.M365.Copilot.Actions;

@agent("Facilities Repair Agent", "Report and track facility maintenance issues and repair requests")
@instructions("""
  You are a facilities management assistant that helps employees report and track
  maintenance issues. You can help users submit new repair requests by gathering
  all necessary details (description, location, category, priority) and submit
  them to the facilities team. You can also check the status of existing repair
  tickets and provide updates on progress. Always be helpful in categorizing
  issues correctly and setting appropriate priority levels based on safety and
  business impact.
""")
namespace FacilitiesRepairAgent {
  op reportIssue is RepairsAPI.reportIssue;
  op getRepairStatus is RepairsAPI.getRepairStatus;
  op getOpenRepairs is RepairsAPI.getOpenRepairs;
}

Agente avançado com autenticação de chave de API

Caso de uso: um agente de gerenciamento de reparos que ajuda as equipes a rastrear e gerenciar tarefas de manutenção de instalações usando uma API disponível publicamente com autenticação de chave de API.

O que faz: este agente fornece recursos abrangentes de gerenciamento de reparos para equipes de manutenção. Ele pode listar, criar, atualizar e excluir tarefas de reparo, filtrar reparos por destinatário ou descrição e fornecer respostas ricas baseadas em card com imagens. A autenticação de chave de API garante acesso controlado ao sistema de gerenciamento de reparos, ao mesmo tempo em que demonstra padrões de integração de API do mundo real.

import "@typespec/http";
import "@typespec/openapi3";
import "@microsoft/typespec-m365-copilot";
import "./actions.tsp";

using TypeSpec.Http;
using TypeSpec.M365.Copilot.Agents;
using TypeSpec.M365.Copilot.Actions;

@agent("Repairs Hub Agent", "Smart repair management agent for tracking and coordinating facility maintenance tasks")
@instructions("""
  You are a specialized repairs management assistant that helps teams efficiently track,
  organize, and coordinate facility maintenance tasks. You excel at managing repair
  workflows including creating detailed repair tickets, assigning tasks to team members,
  tracking progress, and providing status updates. You can filter repairs by various
  criteria such as assignee, keywords in descriptions, or completion status. Always
  provide clear, organized information using tables and cards when displaying repair
  data. When creating repairs, gather all necessary details and confirm the information
  before submission. Help prioritize urgent repairs and ensure proper task assignment
  for optimal team productivity.
""")
@conversationStarter(#{
  title: "List repairs",
  text: "List all repairs"
})
@conversationStarter(#{
  title: "List Karin's repairs",
  text: "List all repairs assigned to Karin"
})
@conversationStarter(#{
  title: "Find oil repairs",
  text: "List all repairs that are about oil"
})
@conversationStarter(#{
  title: "Create repair",
  text: "Create a new repair and assign it to me"
})
namespace RepairsAgent {
  // Repair management operations
  op listRepairs is RepairsHub.listRepairs;
  op createRepair is RepairsHub.createRepair;
  op updateRepair is RepairsHub.updateRepair;
  op deleteRepair is RepairsHub.deleteRepair;
}

Agente complexo com integração OAuth2 e API GitHub

Caso de uso: um agente de gerenciamento de projetos que ajuda as equipes de desenvolvimento a gerenciar seus repositórios do GitHub, rastrear problemas, gerenciar solicitações de pull e coordenar atividades do projeto usando a API abrangente do GitHub.

O que ele faz: esse agente atua como um assistente de gerenciamento de projetos que se integra ao GitHub para ajudar as equipes de desenvolvimento a otimizar seus fluxos de trabalho. Ele pode criar e gerenciar problemas, examinar e mesclar solicitações de pull, acompanhar os marcos do projeto e fornecer insights sobre a atividade do repositório. A autenticação OAuth2 garante acesso seguro aos repositórios do GitHub com permissões apropriadas, permitindo que as equipes gerenciem seus projetos com eficiência por meio de interações de linguagem natural.

import "@typespec/http";
import "@typespec/openapi3";
import "@microsoft/typespec-m365-copilot";
import "./actions.tsp";

using TypeSpec.Http;
using TypeSpec.M365.Copilot.Agents;
using TypeSpec.M365.Copilot.Actions;

@agent("GitHub Project Manager", "Smart project management agent with GitHub integration for issue tracking, pull request management, and project coordination")
@instructions("""
  You are an intelligent project management assistant specialized in GitHub workflows
  and development team coordination. You excel at managing GitHub repositories including
  creating and tracking issues, reviewing pull requests, coordinating project milestones,
  and providing insights about development activity. You can help prioritize work,
  track progress, manage code reviews, and facilitate team collaboration through GitHub's
  project management features. Always consider development best practices, help maintain
  code quality through proper review processes, and provide actionable insights to
  improve team productivity and project delivery.
""")
namespace GitHubProjectManager {
  // GitHub API operations for project management
  op createIssue is GitHubAPI.createIssue;
  op getIssues is GitHubAPI.getIssues;
  op updateIssue is GitHubAPI.updateIssue;
  op getPullRequests is GitHubAPI.getPullRequests;
  op createPullRequest is GitHubAPI.createPullRequest;
  op mergePullRequest is GitHubAPI.mergePullRequest;
  op getProjectInsights is GitHubAPI.getProjectInsights;
}

Resumo

Esses exemplos demonstram a progressão de agentes TypeSpec simples para complexos:

Cada exemplo se baseia nos anteriores, mostrando como adicionar recursos, autenticação e ações personalizadas para criar agentes mais complexos para cenários do mundo real.