Escenarios del agente TypeSpec para Microsoft 365 Copilot

Recomendación

Recomendado: Comience con las herramientas de desarrollo de Work IQ para escenarios de complemento y agente declarativo de código profesional compatibles. Consulte el inicio rápido de WIQD. Las instrucciones basadas en el kit de herramientas siguen estando disponibles para los proyectos existentes y los flujos de trabajo que las requieren. Compruebe la compatibilidad con la capacidad y la experiencia de destino antes de elegir una herramienta: WIQD no se dirige a agentes de motor personalizados.

Esta guía proporciona ejemplos completos de la creación de agentes de TypeSpec para Microsoft 365 Copilot, desde agentes básicos sencillos hasta implementaciones complejas con varias funcionalidades y métodos de autenticación.

Agente básico sin capacidades

Caso de uso: Un agente simple que proporciona información básica y saludos sin integraciones externas ni capacidades especiales.

Qué hace: este agente puede responder preguntas sencillas, proporcionar información general y tener conversaciones básicas. No necesita acceder a API externas, buscar en la web ni acceder a ningún dato de 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 varias funcionalidades

Caso de uso: un asistente de trabajador del conocimiento que puede buscar información en la Web, acceder al contenido de SharePoint de una organización y encontrar información sobre colegas de la organización.

Qué hace: este agente ayuda a los trabajadores del conocimiento combinando la búsqueda en la web de información externa, el acceso a archivos para la recuperación de documentos y la búsqueda de compañeros y su información de contacto. Este patrón se ajusta a los escenarios de investigación y colaboración.

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 simple con acción anónima de API

Caso de uso: un agente de administración de instalaciones que ayuda a los usuarios a informar y realizar un seguimiento de los problemas de mantenimiento mediante una API de reparaciones pública.

Qué hace: Este agente permite a los usuarios informar problemas de instalaciones (equipos rotos, problemas de iluminación, etc.) y verificar el estado de las solicitudes de reparación existentes. La API de reparaciones es de acceso público y no requiere autenticación, lo que facilita que cualquier persona notifique problemas.

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 avanzado con autenticación de clave API

Caso de uso: Un agente de gestión de reparaciones que ayuda a los equipos a realizar un seguimiento y administrar las tareas de mantenimiento de las instalaciones mediante una API disponible públicamente con autenticación de clave API.

Qué hace: este agente proporciona capacidades completas de administración de reparaciones para los equipos de mantenimiento. Puede enumerar, crear, actualizar y eliminar tareas de reparación, filtrar reparaciones por asignado o descripción, y proporcionar respuestas completas basadas en tarjetas con imágenes. La autenticación de clave API garantiza un acceso controlado al sistema de administración de reparaciones al tiempo que demuestra patrones de integración de API del 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 complejo con integración de API de OAuth2 y GitHub

Caso de uso: un agente de administración de proyectos que ayuda a los equipos de desarrollo a administrar sus repositorios de GitHub, realizar un seguimiento de los problemas, administrar solicitudes de incorporación de cambios y coordinar las actividades del proyecto mediante la API integral de GitHub.

Qué hace: este agente sirve como un asistente de administración de proyectos que se integra con GitHub para ayudar a los equipos de desarrollo a simplificar sus flujos de trabajo. Puede crear y administrar problemas, revisar y combinar solicitudes de incorporación de cambios, realizar un seguimiento de los hitos del proyecto y proporcionar información sobre la actividad del repositorio. La autenticación OAuth2 garantiza el acceso seguro a los repositorios de GitHub con los permisos adecuados, lo que permite a los equipos administrar sus proyectos de manera eficiente a través de interacciones de lenguaje 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;
}

Resumen

Estos ejemplos demuestran la progresión de agentes TypeSpec simples a complejos:

Cada ejemplo se basa en los anteriores y muestra cómo agregar funcionalidades, autenticación y acciones personalizadas para crear agentes más complejos para escenarios reales.