/skill-agent-task-patterns

name: skill-agent-task-patterns
description: "Agent SDK task integration patterns for Business Central. Triggers on: Agent Task Builder, Agent Task Message Builder, Public API, AssignTask, ExternalId, agent session detection, BindSubscription, TryFunction agent task, multi-turn agent conversation, agent attachment, task lifecycle management, OnPrem-only methods, AddToTask, SetRequiresReview, SetSkipMessageSanitization, runtime availability."
argument-hint: "Describe the integration pattern needed (Public API, page action, business event, multi-turn, attachment...)"

BC Agent Task Integration Patterns

Knowledge base for every Agent SDK task integration pattern, with runtime-availability matrix and Extension-safe workarounds. For SDK architecture and the 3 interfaces, see `skill-agent-toolkit`.

**References**:

• [Tasks AL API](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/ai/ai-development-toolkit-tasks-api)
• [Agent SDK overview](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/ai/ai-development-toolkit-overview)

API availability matrix (Runtime 17.0 / Platform 27.0)

**Critical**: not every documented method works in Extension scope today. Verify here before designing.

| Method | Scope | Status | Workaround | | -------------------------------------------- | ---------------- | -------------- | ------------------------------------------------------- | | `AddTaskMessage(From, Text)` | Extension | ✅ Available | — | | `AddAttachment(Name, MediaType, InStream)` | Extension | ✅ Available | — | | `SetExternalId(Text)` | Extension | ✅ Available | — | | `SetRequiresReview(true)` | **OnPrem only** | ❌ Ext. blocked | Use `IAgentTaskExecution` Warning annotation | | `SetSkipMessageSanitization(true)` | **OnPrem only** | ❌ Ext. blocked | Pre-format message text upstream | | `AddToTask(AgentTask)` | Future | ❌ Not in 17.0 | Create a new follow-up task referencing original ExternalId | | `Custom Agent.GetCustomAgents()` | Future | ❌ Not in 17.0 | Use `Agent Setup.OpenAgentLookup()` |

OnPrem-only methods are documented but throw at runtime when invoked from a cloud Extension. Treat the workarounds as the canonical Extension pattern.

SDK codeunits — quick reference

| Codeunit | Purpose | Key methods | | ------------------------------ | -------------------------------------------- | ---------------------------------------------------------- | | `Agent Task Builder` | Create new tasks (fluent API) | `.Initialize(Guid, Text).SetExternalId(Text).AddTaskMessage(Text, Text).Create()` | | `Agent Task Message Builder` | Build messages with options | `.Initialize(From, Text)`, `.AddAttachment(Name, MediaType, InStream)`, `.AddToTask(Record)` | | `Agent Task` | Query/manage existing tasks | `GetTaskByExternalId(Guid, Text)`, `CanSetStatusToReady(Record)`, `SetStatusToReady(Record)` | | `Agent Message` | Read/update message text | `GetText(Record)`, `UpdateText(Record, Text)` | | `Agent Setup` | Agent lookup + setup management | `OpenAgentLookup(Enum, var Guid)`, `GetSetupRecord(...)`, `SaveChanges(...)` | | `Agent` | Core agent operations | `SetInstructions(Guid, SecretText)`, `Deactivate(Guid)`, `IsActive(Guid)`, `GetDisplayName(Guid)`, `PopulateDefaultProfile(...)` | | `Agent Session` | Detect agent runtime context | `IsAgentSession(var Enum)`, `IsAgentSession(Enum)`, `GetCurrentSessionAgentTaskId()` |

8 integration patterns

Pattern A — Public API (standard entry point)

**When**: every reusable task-creation surface. All other patterns call through here.

**Architecture**: Public codeunit (`Access = Public`) + Internal implementation codeunit.

**Contract**:

// Overload 1: basic task
procedure AssignTask(AgentUserSecurityID: Guid; TaskTitle: Text[150]; From: Text[250]; Message: Text): Record "Agent Task"

// Overload 2: with ExternalId for tracking / multi-turn
procedure AssignTask(AgentUserSecurityID: Guid; TaskTitle: Text[150]; ExternalId: Text[2048]; From: Text[250]; Message: Text): Record "Agent Task"

// Overload 3: with attachments
procedure AssignTaskWithAttachment(AgentUserSecurityID: Guid; TaskTitle: Text[150]; From: Text[250]; Message: Text; var TempAttachments: Record "Agent Task File"): Record "Agent Task"

// Lifecycle
procedure Deactivate(AgentUserSecurityID: Guid)
procedure IsActive(AgentUserSecurityID: Guid): Boolean

**Implementation** (Impl codeunit, `Access = Internal`):

local procedure AssignTaskInternal(
    AgentUserSecurityID: Guid;
    TaskTitle: Text[150];
    ExternalId: Text[2048];
    From: Text[250];
    Message: Text;
    var TempAttachments: Record "Agent Task File" temporary): Record "Agent Task"
var
    AgentTaskBuilder: Codeunit "Agent Task Builder";
    AgentTaskMsgBuilder: Codeunit "Agent Task Message Builder";
    ContentStream: InStream;
begin
    AgentTaskMsgBuilder.Initialize(From, Message);

    if TempAttachments.FindSet() then
        repeat
            TempAttachments.Content.CreateInStream(ContentStream);
            AgentTaskMsgBuilder.AddAttachment(
                TempAttachments."File Name",
                TempAttachments."Content Type",
                ContentStr