Build Microsoft 365 Copilot Agents That Connect to SharePoint with TypeSpec and OAuth

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(
  "TasksItem",
  "Declarative agent created with Microsoft 365 Agents Toolkit and TypeSpec for Microsoft 365 Copilot."
)

@instructions("""
## Creating a New Volunteering Task
- When a user requests to create a new volunteering task, first call the function `getUserInformation` to get the user id and assign it to `AssignedTo0LookupId` before calling the function `createListItem` to create a new task in the SharePoint list. Also provide some examples by searching for "volunteering opportunities" using the function `searchVolunteerOpportunities`.
- After has an interest in an opportunity, use the information from their response to create a title and description for the task.
- The user should then be prompted to provide the following information:
  - Start Date
- The other fields should be set to default values:
  - Progress: "In Progress"
  - Priority: "Low"
  - Due Date: Start Date plus 1 day
  - AssignedTo0LookupId: The user id retrieved from `getUserInformation` that matches the logged-in user email address or name

- Pass the details provided by the user in the following JSON format. Within the AssignedTo0 used the claims id of the logged in user in the following format:

{
  "fields": {
    "Title": "Task Title",
    "Description": "Task Description", # Determined from the task type selected by the user
    "Progress": "In Progress", # Determined from the task type selected by the user
    "Priority": "Low",
    "StartDate":"2025-04-15", # User provided date
    "DueDate":"2025-04-16", # Start Date + 1 day
    "AssignedTo0LookupId": "{userId}", # User id retrieved from getUserInformation
    "Notes": "Task Notes" # Determined from the task type selected by the user
  }
}

## Listing Assigned Volunteering Tasks
- When a user requests to see assigned volunteering tasks, first call the function `getUserInformation` with parameter `expand=fields` to retrieve the user id of the logged-in user using the user name.
- Then assign it to `userId` replacing the  filter parameter with fields/AssignedTo0LookupId eq {userId} and call the function `getListItems` with parameter `expand=fields` to get the list of tasks assigned to the user
- List the tasks in a user-friendly format showing the following details:
  - Title
  - Description
  - Progress
  - Priority
  - Start Date
  - Due Date
  - Notes
- If no tasks are found, respond with "You have no volunteering tasks assigned to you."

""")

// Uncomment this part to add a conversation starter to the agent.
// This will be shown to the user when the agent is first created.
// Uncomment this part to add a conversation starter to the agent.
// This will be shown to the user when the agent is first created.
 @conversationStarter(#{
    title: "Get Volunteering tasks assigned to me",
    text: "Get the latest volunteering tasks assigned to you"
  })

namespace TasksItem {  
  @service
  @server(global.MsGraphAPI.SERVER_URL)
  @actions(global.MsGraphAPI.ACTIONS_METADATA)
  @useAuth(global.MsGraphAPI.TaskItemsAgentAuth)
  namespace MsGraphAPIActions {
   op getListItems is global.MsGraphAPI.getListItems; 
   op getUserInformation is global.MsGraphAPI.getUserInformation;
   op createListItem is global.MsGraphAPI.createListItem;
  }
}

const SITE_ID = "your-site-id-here";
const LIST_ID = "your-list-id-here";  

model TaskItemsAgentAuth is OAuth2Auth<[{
  type: OAuth2FlowType.authorizationCode;
  authorizationUrl: "https://login.microsoftonline.com/YOUR-TENANT-ID/oauth2/v2.0/authorize";
  tokenUrl: "https://login.microsoftonline.com/YOUR-TENANT-ID/oauth2/v2.0/token";  
  refreshUrl: "https://login.microsoftonline.com/YOUR-TENANT-ID/oauth2/v2.0/refresh";
  scopes: ["User.Read", "Directory.Read.All", "SharePoint.ReadWrite.All"];
}]> { }

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

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

@service
@server(MsGraphAPI.SERVER_URL)
@actions(MsGraphAPI.ACTIONS_METADATA)
namespace MsGraphAPI {
  const ACTIONS_METADATA = #{
    nameForHuman: "Volunteering Tracker",
    descriptionForHuman: "Helps users retrieve volunteering opportunities assigned to them.",
    descriptionForModel: "Helps users retrieve volunteering opportunities assigned to them.",
  };

  /**
   * The base URL for the Microsoft Graph API.
   */
  const SERVER_URL = "https://graph.microsoft.com/v1.0";  
  const SITE_ID = "reshmee.sharepoint.com,541d6ad1-322f-419d-8575-5309a29c3cf8,6b96c932-79a5-4f2a-91dc-41689290ebe7";
  const LIST_ID = "cb530b8f-5af3-44ad-8270-ec89d0357ae5";

  /**
   * Get all tasks in a list
   * @param filter The filter to apply to the list items.
   * @param expand The properties to expand in the response.
   */
  @route("/sites/${SITE_ID}/lists/${LIST_ID}/items")
  @get op getListItems(
    @query filter: string,
    @query expand?: string = "fields",
  ): ListItemsResponse;
  
  /**
   * Create a new item in the specified list.
   * @param input The fields for the new list item.
   */
  @route("/sites/${SITE_ID}/lists/${LIST_ID}/items")
  @post op createListItem(
    @body input: CreateListItemRequest
  ): CreateListItemResponse;
  
  /**
   * Get user information from the "User Information List"
   * @param siteId The ID of the site. If you don't know the 'id'
   */
  @route("/sites/${SITE_ID}/lists/User Information List/items")
  @get op getUserInformation(
    @query expand?: string = "fields",
    @header Prefer?: string
  ): UserInformationListResponse;

  model ListItemsResponse {
    @doc("Metadata context URL")
    "@odata.context": string;
    value: ListItem[];
  }

  model ListItem {
    id: string;
    createdDateTime: string;
    lastModifiedDateTime: string;
    webUrl: string;
    createdBy: CreatedBy;
    lastModifiedBy: CreatedBy;
    fields: ListItemFields;
  }

  model CreatedBy {
    user: UserInfo;
  }

  model UserInfo {
    email?: string;
    id?: string;
    displayName?: string;
  }

  model ListItemFields {
    Title?: string;
    Description?: string;
    Progress?: string;
    Priority?: string;
    StartDate?: string;
    DueDate?: string;
    AssignedTo0LookupId?: string;
    Created?: string;
    Modified?: string;
    AuthorLookupId?: string;
    EditorLookupId?: string;
    Attachments?: boolean;
    Notes?: string;
  }

  model CreateListItemRequest {
    fields: ListItemFields;
  }

  model CreateListItemResponse {
    id: string;
    fields: ListItemFields;
  }

  model UserInformationListResponse {
    "@odata.context": string;
    value: UserInformationListItem[];
  }

  model UserInformationListItem {
    id: string;
    createdDateTime: string;
    lastModifiedDateTime: string;
    webUrl: string;
    createdBy: SimpleUser;
    lastModifiedBy: SimpleUser;
    fields: UserInformationFields;
  }

  model SimpleUser {
    user: SimpleUserInfo;
  }

  model SimpleUserInfo {
    displayName?: string;
  }

  model UserInformationFields {
    id?: string;
    EMail?: string;
  }

  model TaskItemsAgentAuth is OAuth2Auth<[{
    type: OAuth2FlowType.authorizationCode;
    authorizationUrl: "https://login.microsoftonline.com/39f0e149-6ce0-483e-8acf-b6faa229a203/oauth2/v2.0/authorize";
    tokenUrl: "https://login.microsoftonline.com/39f0e149-6ce0-483e-8acf-b6faa229a203/oauth2/v2.0/token";
    refreshUrl: "https://login.microsoftonline.com/39f0e149-6ce0-483e-8acf-b6faa229a203/oauth2/v2.0/refresh";
    scopes: ["User.Read", "Directory.Read.All", "SharePoint.ReadWrite.All"];
  }]> { }

}

TASKITEMSAGENTAUTH_REGISTRATION_ID="MzlmMGUxNDktNmNlMC00ODNlLThhY2YtYjZmYWEyMjlhMjAzIyNjNTFhMTlmZS0wNGExLTQ4MWMtYjY4NC05ZmE3ODFjZWNjOTY="

npx --package=@typespec/compiler tsp compile ./main.tsp --config ./tspconfig.yaml