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.
javiarmesto · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add javiarmesto/ALDC-AL-Development-Collection --skill 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:
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",
ContentStrea
阅读完整来源 ↗