Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
Tip
Recommended: Start with Work IQ Dev Tools for supported pro-code declarative-agent and plugin scenarios. See the WIQD quickstart. Toolkit-based instructions remain available for existing projects and workflows that require them. Check capability and target-experience support before choosing a tool: WIQD doesn't target custom engine agents.
This guide provides complete examples of creating TypeSpec agents for Microsoft 365 Copilot, from simple basic agents to complex implementations with multiple capabilities and authentication methods.
Basic agent with no capabilities
Use Case: A simple agent that provides basic information and greetings without any external integrations or special capabilities.
What it does: This agent can answer simple questions, provide general information, and have basic conversations. It doesn't need to access external APIs, search the web, or access any Microsoft 365 data.
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
}
Agent with multiple capabilities
Use Case: A knowledge worker assistant that can search the web for information, access an organization's SharePoint content, and find information about colleagues in the organization.
What it does: This agent helps knowledge workers by combining web search for external information, file access for document retrieval, and people search for finding colleagues and their contact information. This pattern fits research and collaboration scenarios.
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;
}
Simple agent with anonymous API action
Use Case: A facilities management agent that helps users report and track maintenance issues using a public repairs API.
What it does: This agent allows users to report facility issues (broken equipment, lighting problems, etc.) and check the status of existing repair requests. The repairs API is publicly accessible and doesn't require authentication, making it easy for anyone to report issues.
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;
}
Advanced agent with API key authentication
Use Case: A repairs management agent that helps teams track and manage facility maintenance tasks using a publicly available API with API key authentication.
What it does: This agent provides comprehensive repair management capabilities for maintenance teams. It can list, create, update, and delete repair tasks, filter repairs by assignee or description, and provide rich card-based responses with images. The API key authentication ensures controlled access to the repair management system while demonstrating real-world API integration patterns.
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;
}
Complex agent with OAuth2 and GitHub API integration
Use Case: A project management agent that helps development teams manage their GitHub repositories, track issues, manage pull requests, and coordinate project activities using GitHub's comprehensive API.
What it does: This agent serves as a project management assistant that integrates with GitHub to help development teams streamline their workflows. It can create and manage issues, review and merge pull requests, track project milestones, and provide insights about repository activity. The OAuth2 authentication ensures secure access to GitHub repositories with appropriate permissions, allowing teams to manage their projects efficiently through natural language interactions.
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;
}
Summary
These examples demonstrate the progression from simple to complex TypeSpec agents:
- Basic agent: No capabilities, pure conversational AI
- Multi-capability agent: Combines web search, file access, and people search
- Simple API integration: Anonymous access to external services
- Authenticated API integration: Secure access with API keys
- Complex GitHub integration: Advanced OAuth2 with comprehensive GitHub API access for project management
Each example builds upon the previous ones, showing how to add capabilities, authentication, and custom actions to create more complex agents for real-world scenarios.