Scenari di agente TypeSpec per Microsoft 365 Copilot

Suggerimento

Consigliato: Inizia con Work IQ Dev Tools per scenari di agenti dichiarativi e plug-in pro-code supportati. Vedere la guida introduttiva di WIQD. Le istruzioni basate su toolkit rimangono disponibili per i progetti e i flussi di lavoro esistenti che le richiedono. Controlla il supporto per le funzionalità e l'esperienza di destinazione prima di scegliere uno strumento: WIQD non si rivolge agli agenti del motore personalizzato.

Questa guida fornisce esempi completi di creazione di agenti TypeSpec per Microsoft 365 Copilot, da semplici agenti di base a implementazioni complesse con più funzionalità e metodi di autenticazione.

Agente di base senza funzionalità

Caso d'uso: un semplice agente che fornisce informazioni e saluti di base senza integrazioni esterne o funzionalità speciali.

Cosa fa: questo agente può rispondere a domande semplici, fornire informazioni generali e avere conversazioni di base. Non è necessario accedere ad API esterne, eseguire ricerche nel Web o accedere ai dati di 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 con funzionalità multiple

Caso d'uso: un assistente knowledge worker in grado di cercare informazioni sul Web, accedere ai contenuti SharePoint di un'organizzazione e trovare informazioni sui colleghi dell'organizzazione.

Scopo dell'operazione: questo agente aiuta i knowledge worker combinando la ricerca sul Web per informazioni esterne, l'accesso ai file per il recupero dei documenti e la ricerca di persone per trovare colleghi e le loro informazioni di contatto. Questo modello si adatta agli scenari di ricerca e collaborazione.

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 semplice con azione API anonima

Caso d'uso: un agente di gestione delle strutture che aiuta gli utenti a segnalare e tenere traccia dei problemi di manutenzione utilizzando un'API di riparazione pubblica.

Cosa fa: questo agente consente agli utenti di segnalare problemi di struttura (apparecchiature rotte, problemi di illuminazione, ecc.) e controllare lo stato delle richieste di riparazione esistenti. L'API di riparazione è accessibile pubblicamente e non richiede l'autenticazione, rendendo facile per chiunque segnalare i problemi.

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 avanzato con autenticazione con chiave API

Caso d'uso: un agente di gestione delle riparazioni che aiuta i team a tenere traccia e gestire le attività di manutenzione della struttura utilizzando un'API disponibile pubblicamente con autenticazione con chiave API.

Scopo dell'operazione: questo agente fornisce funzionalità complete di gestione delle riparazioni per i team di manutenzione. Può elencare, creare, aggiornare ed eliminare le attività di riparazione, filtrare le riparazioni per assegnatario o descrizione e fornire risposte complete basate su schede con immagini. L'autenticazione della chiave API garantisce un accesso controllato al sistema di gestione delle riparazioni, dimostrando al contempo i modelli di integrazione API del mondo reale.

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 complesso con integrazione di OAuth2 e API GitHub

Caso d'uso: Un agente di gestione dei progetti che aiuta i team di sviluppo a gestire i loro repository GitHub, tenere traccia dei problemi, gestire le richieste di pull e coordinare le attività del progetto utilizzando l'API completa di GitHub.

Funzione : questo agente funge da assistente alla gestione dei progetti che si integra con GitHub per aiutare i team di sviluppo a semplificare i flussi di lavoro. Può creare e gestire problemi, rivedere e unire richieste di pull, tenere traccia delle attività cardine del progetto e fornire informazioni dettagliate sull'attività del repository. L'autenticazione OAuth2 garantisce l'accesso sicuro ai repository GitHub con le autorizzazioni appropriate, consentendo ai team di gestire i propri progetti in modo efficiente attraverso interazioni in linguaggio naturale.

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;
}

Riepilogo

Questi esempi mostrano la progressione da agenti TypeSpec semplici a complessi:

Ogni esempio si basa sui precedenti, mostrando come aggiungere funzionalità, autenticazione e azioni personalizzate per creare agenti più complessi per scenari reali.