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
• Agent SDK overview

API availability matrix (Runtime 17.0 / Platform 27.0)

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

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

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",
                ContentStream);
        until TempAttachments.Next() = 0;

    AgentTaskBuilder := AgentTaskBuilder
        .Initialize(AgentUserSecurityID, TaskTitle)
        .AddTaskMessage(AgentTaskMsgBuilder);

    if ExternalId <> '' then
        AgentTaskBuilder.SetExternalId(ExternalId);

    exit(AgentTaskBuilder.Create());
end;

Pattern B — Page action (user-initiated)

When: a button on a page sends work to an agent.

Flow: AgentSetup.OpenAgentLookup() → user picks agent → PublicAPI.AssignTask().

trigger OnAction()
var
    AgentSetup: Codeunit "Agent Setup";
    MyAgentAPI: Codeunit "My Agent Public API";
    AgentUserSecurityId: Guid;
begin
    if not AgentSetup.OpenAgentLookup(
        Enum::"Agent Metadata Provider"::"My Agent", AgentUserSecurityId) then
        exit;

    MyAgentAPI.AssignTask(
        AgentUserSecurityId,
        CopyStr(StrSubstNo('Process: %1', Rec.Name), 1, 150),
        'LEAD-' + Rec."No.",
        CopyStr(UserId(), 1, 250),
        StrSubstNo('Please process customer %1 (No. %2).', Rec.Name, Rec."No."));
end;

Pattern C — Business event (automated)

When: a business event (posting, releasing, approval) auto-triggers an agent task.

Non-negotiable rules:

1. Always wrap in [TryFunction] — never block the business event on agent failure.
2. Always filter by business condition BEFORE creating the task — not inside the TryFunction.
3. Always log failures via Session.LogMessage with category and GetLastErrorText().

[EventSubscriber(ObjectType::Codeunit, Codeunit::"Release Sales Document",
                 OnBeforeReleaseSalesDoc, '', false, false)]
local procedure OnBeforeRelease(var SalesHeader: Record "Sales Header")
begin
    if SalesHeader."Document Type" <> SalesHeader."Document Type"::Order then exit;
    if not MeetsCondition(SalesHeader) then exit;

    if not TryCreateTask(SalesHeader) then
        Session.LogMessage('BCA2A-FAIL',
            StrSubstNo('Task creation failed for %1: %2', SalesHeader."No.", GetLastErrorText()),
            Verbosity::Error, DataClassification::SystemMetadata,
            TelemetryScope::ExtensionPublisher, 'Category', 'BCA2A');
end;

[TryFunction]
local procedure TryCreateTask(var SalesHeader: Record "Sales Header")
var
    PublicAPI: Codeunit "My Agent Public API";
begin
    PublicAPI.AssignTask(
        GetAgentSecurityId(),
        'Validate SO ' + SalesHeader."No.",
        'SO-' + SalesHeader."No.",
        'System',
        BuildMessage(SalesHeader));
end;

Pattern D — Attachment task

When: agent needs to process files (PDFs, images, CSVs, Excel).

Signature: AddAttachment(Name: Text[250]; MediaType: Text; ContentStream: InStream)

procedure CreateTaskWithAttachment(AgentUserId: Guid; var DocumentBlob: Codeunit "Temp Blob")
var
    AgentTaskBuilder: Codeunit "Agent Task Builder";
    AgentTaskMsgBuilder: Codeunit "Agent Task Message Builder";
    ContentStream: InStream;
begin
    DocumentBlob.CreateInStream(ContentStream);

    AgentTaskMsgBuilder.Initialize(CopyStr(UserId(), 1, 250), 'Review attached document.');
    AgentTaskMsgBuilder.AddAttachment('Document.pdf', 'application/pdf', ContentStream);

    AgentTaskBuilder := AgentTaskBuilder
        .Initialize(AgentUserId, 'Process Document')
        .SetExternalId('DOC-1001')
        .AddTaskMessage(AgentTaskMsgBuilder);

    AgentTaskBuilder.Create();
end;

Common MIME types: application/pdf, image/png, image/jpeg, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet (Excel xlsx), text/csv.

When you need a canonical end-to-end example combining attachment + business condition + telemetry + lead handoff, load examples/lead-handoff-with-attachment.md.

Pattern E — Multi-turn conversation

When: continue an existing task with follow-up messages.

Flow: GetTaskByExternalId() → build follow-up → workaround needed (see below) → SetStatusToReady().

Status (Runtime 17.0): AgentTaskMessageBuilder.AddToTask() is not available in Extension scope yet. Until it ships, create a new task that references the original ExternalId:

procedure SendFollowUpTask(AgentUserId: Guid; OriginalExternalId: Text; AdditionalInfo: Text)
var
    AgentTaskBuilder: Codeunit "Agent Task Builder";
    AgentTaskMsgBuilder: Codeunit "Agent Task Message Builder";
begin
    AgentTaskMsgBuilder.Initialize(CopyStr(UserId(), 1, 250), AdditionalInfo);

    AgentTaskBuilder := AgentTaskBuilder
        .Initialize(AgentUserId, CopyStr('Update for ' + OriginalExternalId, 1, 150))
        .SetExternalId(OriginalExternalId + '-UPD')
        .AddTaskMessage(AgentTaskMsgBuilder);

    AgentTaskBuilder.Create();
end;

When AddToTask becomes available in a future runtime, the canonical pattern will be:

// FUTURE — not yet in Extension scope
AgentTaskRecord := AgentTaskCU.GetTaskByExternalId(AgentSecurityId, ExternalId);
AgentTaskMsgBuilder.Initialize('User', FollowUpText);
AgentTaskMsgBuilder.AddToTask(AgentTaskRecord);
if AgentTaskCU.CanSetStatusToReady(AgentTaskRecord) then
    AgentTaskCU.SetStatusToReady(AgentTaskRecord);

Pattern F — Lifecycle management

When: monitor, restart, or stop tasks programmatically.

Pattern G — Agent session detection

When: AL code must run only inside an agent session (not in normal user sessions).

// Any agent
var
    AgentSession: Codeunit "Agent Session";
    Provider: Enum "Agent Metadata Provider";
begin
    if not AgentSession.IsAgentSession(Provider) then exit;
    // agent-specific logic
end;

// Specific agent
if not AgentSession.IsAgentSession(Enum::"Agent Metadata Provider"::"Lead Qualifier") then exit;

Pattern H — Agent session event binding (performance)

When: event subscribers should be active only during agent tasks, never in normal user sessions.

Architecture: SingleInstance codeunit + BindSubscription on System Initialization.OnAfterInitialization.

codeunit 52120 "My Agent Session Events"
{
    Access = Internal;
    SingleInstance = true;

    [EventSubscriber(ObjectType::Codeunit, Codeunit::"System Initialization",
                     OnAfterInitialization, '', false, false)]
    local procedure OnInit()
    var
        AgentSession: Codeunit "Agent Session";
    begin
        if not AgentSession.IsAgentSession(
            Enum::"Agent Metadata Provider"::"My Agent") then exit;

        GlobalEvents.SetAgentTaskID(AgentSession.GetCurrentSessionAgentTaskId());
        if BindSubscription(GlobalEvents) then;
    end;

    var
        GlobalEvents: Codeunit "My Agent Events";
}

Human review without SetRequiresReview

SetRequiresReview is OnPrem-only. To force human review from an Extension, add a Warning annotation in IAgentTaskExecution.AnalyzeAgentTaskMessage:

procedure AnalyzeAgentTaskMessage(
    AgentTaskMessage: Record "Agent Task Message";
    var Annotations: Record "Agent Annotation")
var
    AgentMessage: Codeunit "Agent Message";
    MessageText: Text;
begin
    MessageText := AgentMessage.GetText(AgentTaskMessage);

    if MessageText.Contains('DISQUALIFICATION') then begin
        Annotations.Severity := Annotations.Severity::Warning;
        Annotations.Message :=
            'Disqualification requires human approval. Review before proceeding.';
        Annotations.Insert();
    end;
end;

Warning annotations trigger the user-intervention flow via GetAgentTaskUserInterventionSuggestions. Error annotations stop the task.

Agent discovery — current state

Until Custom Agent.GetCustomAgents() becomes available in Extension scope, use Agent Setup.OpenAgentLookup() for user selection and Agent.GetDisplayName(Guid) for display:

trigger OnLookup(var Text: Text): Boolean
var
    AgentSetup: Codeunit "Agent Setup";
    SelectedAgentUserId: Guid;
begin
    if AgentSetup.OpenAgentLookup(
        Enum::"Agent Metadata Provider"::"Quote Builder", SelectedAgentUserId) then begin
        Rec."Target Agent Security ID" := SelectedAgentUserId;
        Text := Format(SelectedAgentUserId);
        exit(true);
    end;
    exit(false);
end;

local procedure GetAgentDisplayText(AgentSecurityId: Guid): Text
var
    AgentCU: Codeunit Agent;
begin
    if IsNullGuid(AgentSecurityId) then exit('');
    exit(AgentCU.GetDisplayName(AgentSecurityId) + ' (' + Format(AgentSecurityId) + ')');
end;

Pattern selection guide

Non-negotiable rules

1. Public API is the entry point — all other patterns call through it.
2. TryFunction for event-driven creation — never block posting, releasing, approval.
3. Filter before creating — business condition checked outside the TryFunction.
4. Log failures to telemetry — Session.LogMessage with category and error text.
5. Mensaje contiene todo el contexto — el agente solo sabe lo que le pasas por el mensaje + attachments.
6. ExternalId follows {PREFIX}-{No.} — SO-1001, LEAD-001, EMAIL-{threadId}. Never GUIDs or auto-increments.
7. Use Agent Task Message Builder for attachments — never manipulate the underlying records directly.
8. Verify availability against the matrix above before designing — don't ship code that relies on OnPrem-only methods.

Examples

Load an example only when you need its concrete template:

• When implementing an end-to-end attachment + business condition + telemetry + handoff flow, load examples/lead-handoff-with-attachment.md.
• When wiring Pattern H with a companion Events codeunit, load examples/session-events-binding.md.