[Agent] Upload first version of Sales Return sample agent

samples/BCAgents/SalesReturnAgent/app/.resources/Instructions/InstructionsV1.md

@@ -0,0 +1,36 @@
+You are acting as a Sales Returns Agent. You receive return requests from customers via email. You are responsible for handling the tasks in this area like creating credit memos and handling customer requests. The following are the responsibilities, processing guidelines, and instructions you need to follow.
+
+# **Communication**
+- Your replies are sent back to the customer who emailed you. Write them as responses to the customer.
+- When you encounter processing issues (e.g. cannot verify an invoice, items do not match, data discrepancies), do not reply to the customer. Instead, request assistance from the Business Central user so they can investigate.
+- When requesting approval to post a credit memo, request assistance from the Business Central user — not the customer.
+
+# **Guidelines**
+1. Do not post any draft credit memo's without asking for approval from the Business Central user.
+2. If customer number is not provided but there is a customer name or an email, first go to the customers list and search either by name or email and memorize the customer number.
+3. If no unit of measure can be looked up, try with PCS.
+
+# **Instructions**
+## **Validating the original invoice**
+1.0. Before creating a credit memo, verify the original sale:
+1.0.1. If a sales invoice is attached to the message, do not trust it at face value. Extract the customer, items, quantities, and date from the attachment, then search posted sales invoices in the system for a matching record. Only proceed if you find a posted invoice that matches. If the attachment does not match any posted invoice, treat it as unverified and follow step 1.0.4.
+1.0.2. If a sales invoice number or date is referenced in the message, look it up in posted sales invoices and confirm the items and quantities. If the referenced invoice number does not exist, request assistance from the Business Central user.
+1.0.3. If no invoice is provided but the customer and items are known, search posted sales invoices for that customer to find a matching transaction.
+1.0.4. If no matching invoice or shipment can be found, request assistance from the Business Central user explaining what was searched and what could not be verified. Do not create a credit memo.
+1.0.5. If a matching invoice is found but the items the customer wants to return are not in that invoice, request assistance from the Business Central user. Do not create a credit memo.
+1.0.6. If multiple invoices could match and you cannot determine which one, request assistance from the Business Central user.
+
+## **Handling returns**
+1.1. Create a draft credit memo for that customer with the items they want to be returned.
+1.1.1. Fill in the relevant lines. If the credit memo has been created as a correction of an existing invoice, ensure that the quantities and items match what is being returned. If the customer is doing a partial return, this should be reflected by removing the credit memo lines that are not being returned.
+1.1.2. Set the "Applies-to Doc. No." on the credit memo to link it to the original posted invoice.
+1.1.3. Fill out the work description with what is being returned and justification why. Also add any text that the customer may have provided as the reason.
+
+## **Requesting review and approval to post**
+1.2. After the draft credit memo is created, request a review of the credit memo from the Business Central user. You should also request to approve posting it. Do not post the credit memo until the user has reviewed it.
+1.2.1. If the Business Central user declines the review or requests changes, update the credit memo according to their feedback and request a new review.
+1.2.2. Continue this review cycle until the Business Central user approves the credit memo.
+
+## **Posting and responding to the customer**
+1.3. Once the Business Central user has approved the credit memo, post it.
+1.4. After posting, print the credit memo and attach the PDF to a reply to the customer, summarizing what was returned and why.

samples/BCAgents/SalesReturnAgent/app/Integration/SalesRetAgentInstall.Codeunit.al

@@ -0,0 +1,64 @@
+// ------------------------------------------------------------------------------------------------
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License. See License.txt in the project root for license information.
+// ------------------------------------------------------------------------------------------------
+
+namespace SalesReturnAgent.Integration;
+
+using SalesReturnAgent.Setup;
+using System.Agents;
+using System.AI;
+
+codeunit 53702 "Sales Ret. Agent Install"
+{
+    Subtype = Install;
+    Access = Internal;
+    InherentEntitlements = X;
+    InherentPermissions = X;
+
+    trigger OnInstallAppPerDatabase()
+    var
+        SalesRetAgentSetupRec: Record "Sales Ret. Agent Setup";
+    begin
+        RegisterCapability();
+
+        if not SalesRetAgentSetupRec.FindSet() then
+            exit;
+
+        repeat
+            InstallAgent(SalesRetAgentSetupRec);
+        until SalesRetAgentSetupRec.Next() = 0;
+    end;
+
+    local procedure InstallAgent(var SalesRetAgentSetupRec: Record "Sales Ret. Agent Setup")
+    begin
+        InstallAgentInstructions(SalesRetAgentSetupRec);
+    end;
+
+    local procedure InstallAgentInstructions(var SalesRetAgentSetupRec: Record "Sales Ret. Agent Setup")
+    var
+        Agent: Codeunit Agent;
+        SalesRetAgentSetup: Codeunit "Sales Ret. Agent Setup";
+    begin
+        Agent.SetInstructions(SalesRetAgentSetupRec."User Security ID", SalesRetAgentSetup.GetInstructions());
+    end;
+
+    [EventSubscriber(ObjectType::Page, Page::"Copilot AI Capabilities", 'OnRegisterCopilotCapability', '', false, false)]
+    local procedure OnRegisterCopilotCapability()
+    begin
+        RegisterCapability();
+    end;
+
+    local procedure RegisterCapability()
+    var
+        CopilotCapability: Codeunit "Copilot Capability";
+        LearnMoreUrlTok: Label 'https://go.microsoft.com/fwlink/?linkid=2350506', Locked = true;
+    begin
+        if not CopilotCapability.IsCapabilityRegistered(Enum::"Copilot Capability"::"Sales Return Agent") then
+            CopilotCapability.RegisterCapability(
+            Enum::"Copilot Capability"::"Sales Return Agent",
+            Enum::"Copilot Availability"::Preview,
+            "Copilot Billing Type"::"Microsoft Billed",
+            LearnMoreUrlTok);
+    end;
+}

samples/BCAgents/SalesReturnAgent/app/Integration/SalesRetCopilotCapability.EnumExt.al

@@ -0,0 +1,16 @@
+// ------------------------------------------------------------------------------------------------
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License. See License.txt in the project root for license information.
+// ------------------------------------------------------------------------------------------------
+
+namespace SalesReturnAgent.Integration;
+
+using System.AI;
+
+enumextension 53700 "Sales Ret. Copilot Capability" extends "Copilot Capability"
+{
+    value(53700; "Sales Return Agent")
+    {
+        Caption = 'Sales Return Agent';
+    }
+}

samples/BCAgents/SalesReturnAgent/app/Setup/KPI/SalesRetAgentKPI.Page.al

@@ -0,0 +1,63 @@
+// ------------------------------------------------------------------------------------------------
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License. See License.txt in the project root for license information.
+// ------------------------------------------------------------------------------------------------
+
+namespace SalesReturnAgent.Setup.KPI;
+
+page 53701 "Sales Ret. Agent KPI"
+{
+    PageType = CardPart;
+    ApplicationArea = All;
+    Caption = 'Sales Return Agent Summary';
+    SourceTable = "Sales Ret. Agent KPI";
+    Editable = false;
+    Extensible = false;
+    InherentEntitlements = X;
+    InherentPermissions = X;
+
+    layout
+    {
+        area(Content)
+        {
+            cuegroup(KeyMetrics)
+            {
+                Caption = 'Key Performance Indicators';
+
+                field(CreditMemosCreated; Rec."Credit Memos Created")
+                {
+                    Caption = 'Credit Memos Created';
+                    ToolTip = 'Specifies the number of sales credit memos created by the agent.';
+                }
+            }
+        }
+    }
+
+    trigger OnOpenPage()
+    begin
+        GetRelevantAgent();
+    end;
+
+    /// <summary>
+    /// Retrieves the relevant agent's KPI record for display.
+    /// This page is launched via IAgentMetadata.GetSummaryPageId(). The platform sets a filter on the
+    /// "User Security ID" field before opening the page, so the source record may not be fully populated
+    /// on open - the filter is evaluated here to resolve and load the correct record.
+    /// </summary>
+    local procedure GetRelevantAgent()
+    var
+        UserSecurityIDFilter: Text;
+    begin
+        if IsNullGuid(Rec."User Security ID") then begin
+            UserSecurityIDFilter := Rec.GetFilter("User Security ID");
+            if not Evaluate(Rec."User Security ID", UserSecurityIDFilter) then
+                Error(AgentDoesNotExistErr);
+        end;
+
+        if not Rec.Get(Rec."User Security ID") then
+            Rec.Insert();
+    end;
+
+    var
+        AgentDoesNotExistErr: Label 'The agent does not exist. Please check the configuration.';
+}

samples/BCAgents/SalesReturnAgent/app/Setup/KPI/SalesRetAgentKPI.Table.al

@@ -0,0 +1,43 @@
+// ------------------------------------------------------------------------------------------------
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License. See License.txt in the project root for license information.
+// ------------------------------------------------------------------------------------------------
+
+namespace SalesReturnAgent.Setup.KPI;
+
+table 53701 "Sales Ret. Agent KPI"
+{
+    Access = Internal;
+    Caption = 'Sales Ret. Agent KPI';
+    DataClassification = SystemMetadata;
+    InherentEntitlements = RIMX;
+    InherentPermissions = RIMX;
+    ReplicateData = false;
+    DataPerCompany = false;
+
+    fields
+    {
+        // This field is part of the IAgentMetadata.GetSummaryPageId() contract.
+        // The platform filters on "User Security ID" when opening the summary page,
+        // so it must be the primary key of this table.
+        field(1; "User Security ID"; Guid)
+        {
+            Caption = 'User Security ID';
+            ToolTip = 'Specifies the unique identifier for the agent user.';
+            Editable = false;
+        }
+        field(10; "Credit Memos Created"; Integer)
+        {
+            Caption = 'Credit Memos Created';
+            ToolTip = 'Specifies the number of sales credit memos created by the agent.';
+            DataClassification = CustomerContent;
+        }
+    }
+    keys
+    {
+        key(Key1; "User Security ID")
+        {
+            Clustered = true;
+        }
+    }
+}

samples/BCAgents/SalesReturnAgent/app/Setup/KPI/SalesRetAgentKPILogging.Codeunit.al

@@ -0,0 +1,65 @@
+// ------------------------------------------------------------------------------------------------
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License. See License.txt in the project root for license information.
+// ------------------------------------------------------------------------------------------------
+
+namespace SalesReturnAgent.Setup.KPI;
+
+using Microsoft.Sales.Document;
+using SalesReturnAgent.Setup;
+using System.Agents;
+
+/// <summary>
+/// Subscribes to business events to automatically log KPI metrics
+/// for the Sales Return Agent.
+///
+/// - Credit Memos Created: incremented each time the agent creates a sales credit memo.
+/// </summary>
+codeunit 53704 "Sales Ret. Agent KPI Logging"
+{
+    Access = Internal;
+    EventSubscriberInstance = StaticAutomatic;
+    SingleInstance = true;
+    InherentEntitlements = X;
+    InherentPermissions = X;
+
+    [EventSubscriber(ObjectType::Table, Database::"Sales Header", OnAfterInsertEvent, '', false, false)]
+    local procedure OnAfterInsertSalesHeader(var Rec: Record "Sales Header"; RunTrigger: Boolean)
+    var
+        AgentSession: Codeunit "Agent Session";
+        SalesRetAgentSetup: Codeunit "Sales Ret. Agent Setup";
+        AgentUserSecurityId: Guid;
+        AgentMetadataProvider: Enum "Agent Metadata Provider";
+    begin
+        if not AgentSession.IsAgentSession(AgentMetadataProvider) then
+            exit;
+
+        if AgentMetadataProvider <> Enum::"Agent Metadata Provider"::"Sales Return Agent" then
+            exit;
+
+        if Rec."Document Type" <> Rec."Document Type"::"Credit Memo" then
+            exit;
+
+        if not SalesRetAgentSetup.TryGetAgent(AgentUserSecurityId) then
+            exit;
+
+        if UserSecurityId() <> AgentUserSecurityId then
+            exit;
+
+        UpdateKPI(AgentUserSecurityId, 1);
+    end;
+
+    local procedure UpdateKPI(AgentUserSecurityId: Guid; CreatedIncrement: Integer)
+    var
+        SalesRetAgentKPI: Record "Sales Ret. Agent KPI";
+    begin
+        if not SalesRetAgentKPI.Get(AgentUserSecurityId) then begin
+            SalesRetAgentKPI.Init();
+            SalesRetAgentKPI."User Security ID" := AgentUserSecurityId;
+            SalesRetAgentKPI.Insert();
+        end;
+
+        SalesRetAgentKPI."Credit Memos Created" += CreatedIncrement;
+        SalesRetAgentKPI.Modify();
+    end;
+}

samples/BCAgents/SalesReturnAgent/app/Setup/Metadata/SalesRetAgentFactory.Codeunit.al

@@ -0,0 +1,54 @@
+// ------------------------------------------------------------------------------------------------
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License. See License.txt in the project root for license information.
+// ------------------------------------------------------------------------------------------------
+
+namespace SalesReturnAgent.Setup.Metadata;
+
+using SalesReturnAgent.Setup;
+using System.Agents;
+using System.AI;
+using System.Reflection;
+using System.Security.AccessControl;
+
+codeunit 53700 SalesRetAgentFactory implements IAgentFactory
+{
+    Access = Internal;
+    InherentEntitlements = X;
+    InherentPermissions = X;
+
+    procedure GetDefaultInitials(): Text[4]
+    begin
+        exit(SalesRetAgentSetup.GetInitials());
+    end;
+
+    procedure GetFirstTimeSetupPageId(): Integer
+    begin
+        exit(SalesRetAgentSetup.GetSetupPageId());
+    end;
+
+    procedure ShowCanCreateAgent(): Boolean
+    var
+        SalesRetAgentSetupRec: Record "Sales Ret. Agent Setup";
+    begin
+        exit(SalesRetAgentSetupRec.IsEmpty());
+    end;
+
+    procedure GetCopilotCapability(): Enum "Copilot Capability"
+    begin
+        exit("Copilot Capability"::"Sales Return Agent");
+    end;
+
+    procedure GetDefaultProfile(var TempAllProfile: Record "All Profile" temporary)
+    begin
+        SalesRetAgentSetup.GetDefaultProfile(TempAllProfile);
+    end;
+
+    procedure GetDefaultAccessControls(var TempAccessControlTemplate: Record "Access Control Buffer" temporary)
+    begin
+        SalesRetAgentSetup.GetDefaultAccessControls(TempAccessControlTemplate);
+    end;
+
+    var
+        SalesRetAgentSetup: Codeunit "Sales Ret. Agent Setup";
+}

samples/BCAgents/SalesReturnAgent/app/Setup/Metadata/SalesRetAgentMetadata.Codeunit.al

@@ -0,0 +1,44 @@
+// ------------------------------------------------------------------------------------------------
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License. See License.txt in the project root for license information.
+// ------------------------------------------------------------------------------------------------
+
+namespace SalesReturnAgent.Setup.Metadata;
+
+using SalesReturnAgent.Setup;
+using System.Agents;
+
+codeunit 53701 SalesRetAgentMetadata implements IAgentMetadata
+{
+    Access = Internal;
+    InherentEntitlements = X;
+    InherentPermissions = X;
+
+    procedure GetInitials(AgentUserId: Guid): Text[4]
+    begin
+        exit(SalesRetAgentSetup.GetInitials());
+    end;
+
+    procedure GetSetupPageId(AgentUserId: Guid): Integer
+    begin
+        exit(SalesRetAgentSetup.GetSetupPageId());
+    end;
+
+    procedure GetSummaryPageId(AgentUserId: Guid): Integer
+    begin
+        exit(SalesRetAgentSetup.GetSummaryPageId());
+    end;
+
+    procedure GetAgentTaskMessagePageId(AgentUserId: Guid; MessageId: Guid): Integer
+    begin
+        exit(Page::"Agent Task Message Card");
+    end;
+
+    procedure GetAgentAnnotations(AgentUserId: Guid; var Annotations: Record "Agent Annotation")
+    begin
+        Clear(Annotations);
+    end;
+
+    var
+        SalesRetAgentSetup: Codeunit "Sales Ret. Agent Setup";
+}