main.tsp

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

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

@agent(
  "Repairs Hub Agent (OAuth)",
  "An agent for managing repair information"
)

@instructions("""
  You are a repairs expert agent.
""")

@conversationStarter(#{
  title: "List repairs",
  text: "List all repairs"
})

@conversationStarter(#{
  title: "List all Karin's repairs",
  text: "List all repairs assigned to Karin"
})

@conversationStarter(#{
  title: "List all repairs about oil",
  text: "List all repairs that are about oil"
})

@conversationStarter(#{
  title: "List all overdue repairs",
  text: "List all overdue repairs"
})

@conversationStarter(#{
  title: "Create repair",
  text: "Create a new repair titled [TO_REPLACE] and assign it to me"
})

@conversationStarter(#{
  title: "Assign me a repair",
  text: "Update the repairs about [TO_REPLACE] and assign it to me"
})

namespace RepairsAgent {  
  @service
  @actions(#{
    nameForHuman: "Repairs Hub",
    descriptionForHuman: "Manage your repairs and maintenance tasks.",
    descriptionForModel: "Plugin to add, update, remove, and view repair objects.", 
  })
  @server("https://repairshub-oauth.azurewebsites.net", "Repairs Hub API")
  @useAuth(RepairsHubAuth)
  namespace RepairsHub {
    /**
     * List all repairs.
     * @param assignedTo Optional filter to list repairs assigned to a specific user.
     */
    /*@responding("""
      * **ALWAYS** return the data in a markdown table format that includes the following columns:
        * Title
        * Description
        * Assigned To
      * If there is no data for a column, leave it blank.
      * Always add a link to the image in the title column using this format [title](image)
    """)*/
    @route("/repairs")
    @card(#{ dataPath: "$", title: "$.title", url: "$.image", file: "cards/repair.json" })
    @get op listRepairs(@query assignedTo?: string): string;

    /**
     * Create a new repair. 
     * When creating a repair, the `id` field is optional and will be generated by the server.
     * The `date` field should be in ISO 8601 format (e.g., "2023-10-01T12:00:00Z").
     * The `image` field should be a valid URL pointing to the image associated with the repair.
     * @param repair The repair to create.
     */
    @route("/repairs")
    @capabilities(#{
      confirmation: #{
        type: "AdaptiveCard",
        title: "Create a new repair",
        body: """   
        Creating a new repair with the following details:       
          * **Title**: {{ function.parameters.title }}
          * **Description**: {{ function.parameters.description }}
          * **Assigned To**: {{ function.parameters.assignedTo }}
        """
      }
    })
    @post op createRepair(@body repair: Repair): Repair;

    /**
     * Update an existing repair.
     * The `id` field is required to identify the repair to update.
     * The `date` field should be in ISO 8601 format (e.g., "2023-10-01T12:00:00Z").
     * The `image` field should be a valid URL pointing to the image associated with the repair.
     * @param repair The repair to update.
     */
    @route("/repairs")
    /*@reasoning("""
      **ALWAYS** use the listRepairs function to get the ID first.
    """)*/
    @capabilities(#{
      confirmation: #{
        type: "AdaptiveCard",
        title: "Create a new repair",
        body: """   
        Updating a repair with the following details:       
          * **ID**: {{ function.parameters.id }}      
          * **Title**: {{ function.parameters.title }}
          * **Description**: {{ function.parameters.description }}
          * **Assigned To**: {{ function.parameters.assignedTo }}
        """
      }
    })
    @patch op updateRepair(@body repair: Repair): Repair;

    /**
     * Delete a repair.
     * The `id` field is required to identify the repair to delete.
     * @param repair The repair to delete.
     */
    @route("/repairs")
    /*@reasoning("""
      **ALWAYS** use the listRepairs function to get the ID first.
    """);*/
    @capabilities(#{
      confirmation: #{
        type: "AdaptiveCard",
        title: "Delete a repair",
        body: """   
        Deleting a repair with the following details:       
          * **ID**: {{ function.parameters.id }}
        """
      }
    })
    @delete op deleteRepair(@body repair: Repair): Repair;
    
    /**
     * A model representing a repair.
     */
    model Repair {
      /**
       * The unique identifier for the repair.
       */
      id?: string;

      /**
       * The short summary or title of the repair.
       */
      title: string;

      /**
       * The detailed description of the repair.
       */
      description?: string;

      /**
       * The user who is assigned to the repair.
       */
      assignedTo?: string;

      /**
       * The optional date and time when the repair is scheduled or completed.
       */
      @format("date-time")
      date?: string;

      /**
       * The URL of the image associated with the repair.
       */
      @format("uri")
      image?: string;
    }
  }

  @authReferenceId("\${{REPAIRSHUBAUTH_REGISTRATION_ID}}")
  model RepairsHubAuth is OAuth2Auth<[{
    type: OAuth2FlowType.authorizationCode;
    authorizationUrl: "https://login.microsoftonline.com/organizations/oauth2/v2.0/authorize";
    tokenUrl: "https://login.microsoftonline.com/organizations/oauth2/v2.0/token";
    refreshUrl: "https://login.microsoftonline.com/organizations/oauth2/v2.0/token";
  }]> { }
}