skill-agent-task-patterns
/skill-agent-task-patterns
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.
- Author
- javiarmesto ↗
- Repository
- aldc-al-development-collection ↗
- Licence
- MIT
- Last repository change
- 21.10.2026
Assessment and security
- Files in this package
- 3
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 2
No signals detected. Repository changed on 21.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
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.
Arguments
/skill-agent-task-patterns Describe the integration pattern needed (Public API, page action, business event, multi-turn, attachment...)
Original author 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.
How it works
- API availability matrix (Runtime 17.0 / Platform 27.0)
- SDK codeunits — quick reference
- 8 integration patterns
- Human review without SetRequiresReview
- Agent discovery — current state
- Pattern selection guide
- Non-negotiable rules
- Examples
SKILL.md preview
---
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**:
```al
// 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`):
```al
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()`.
```al
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()`.
```al
[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)`
```al
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:
```al
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:
```al
// 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.
| Operation | Method |
| --------------------- | -------------------------------------------------------- |
| Check active | `Agent.IsActive(AgentUserSecurityId)` |
| Deactivate | `Agent.Deactivate(AgentUserSecurityId)` |
| Find by ExternalId | `AgentTask.GetTaskByExternalId(AgentUserId, ExternalId)` |
| Resume paused task | `if AgentTask.CanSetStatusToReady(Rec) then AgentTask.SetStatusToReady(Rec)` |
| Display name lookup | `Agent.GetDisplayName(AgentUserSecurityId)` |
### Pattern G — Agent session detection
**When**: AL code must run only inside an agent session (not in normal user sessions).
```al
// 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`.
```al
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`:
```al
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:
```al
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
| Situation | Pattern(s) |
| ------------------------------------------ | ----------------- |
| Standard reusable task creation | A (Public API) |
| User clicks button to assign work | B → A |
| Business event triggers agent | C → A |
| Agent processes uploaded files | D + (A, B, or C) |
| Follow-up on existing task | E |
| Monitor / restart / stop tasks | F |
| Code runs only in agent context | G |
| Performance: subscribers only during tasks | H |
| Need to force human review (Extension) | Warning annotation in `AnalyzeAgentTaskMessage` |
## 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`.
Files in this package (3)
- SKILL.md 17 KB
- examples/lead-handoff-with-attachment.md 2 KB
- examples/session-events-binding.md 2 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · javiarmesto/aldc-al-development-collection | 100 | MIT |
| javiarmesto/aldc-al-development-collection | 100 | MIT |
Identical content appears in 2 other GitHub folders. We show one copy with the highest score.
Database snapshot: 13.11.2026 · package version 482148aa47cf (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100skill-agent-toolkit
Build, configure, and integrate Business Central agents using the AI Development Toolkit and Agent SDK. Triggers on Agent SDK, Agent Metadata Provider, IAgentFactory, IAgentMetadata, IAgentTaskExecution, ConfigurationDialog, Agent Task Builder, Agent Session, Copilot Capability,… - 100skill-agent-toolkit
Build, configure, and integrate Business Central agents using the AI Development Toolkit and Agent SDK. Triggers on Agent SDK, Agent Metadata Provider, IAgentFactory, IAgentMetadata, IAgentTaskExecution, ConfigurationDialog, Agent Task Builder, Agent Session, Copilot Capability,…