{"title":"Integrate with the Tasks AL API","url":"https://jonas-paprotka.de/docs/dev-itpro/ai/ai-development-toolkit-tasks-api/","by":"JOP-AL","license":"Copyright (c) Microsoft Corporation. CC BY 4.0, https://creativecommons.org/licenses/by/4.0/; code samples MIT. From https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/ai/ai-development-toolkit-tasks-api, MicrosoftDocs/dynamics365smb-devitpro-pb at 828b6ee (2026-11-19). Changed: includes filled in, links to this site, and for agents shortened without dropping a fact.","credit":"Microsoft Corporation, CC BY 4.0","origin":"https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/ai/ai-development-toolkit-tasks-api","source":{"name":"Business Central developer and IT pro docs","repo":"https://github.com/MicrosoftDocs/dynamics365smb-devitpro-pb","commit":"828b6ee72fcd75755627cd6011f3d20899217ab2","date":"2026-11-19"},"checked":"2026-11-19","description":"Learn how to integrate custom agents with common scenarios using the Tasks AL API in Dynamics 365 Business Central.","date":"2026-10-02","meta":{"topic":"concept-article"},"outline":[{"level":1,"title":"Integrate with the Tasks AL API","slug":"integrate-with-the-tasks-al-api","at":0,"chars":3750},{"level":2,"title":"Get information about the available custom agents","slug":"get-information-about-the-available-custom-agents","at":1110,"chars":844},{"level":2,"title":"Detect custom agent sessions","slug":"detect-custom-agent-sessions","at":1954,"chars":714},{"level":2,"title":"Related information","slug":"related-information","at":2668,"chars":1082}],"text":"# Integrate with the Tasks AL API\n[This article is prerelease documentation and is subject to change.]\n> IMPORTANT\n > This is a preview feature. Preview features might have restricted functionality and are subject to supplemental terms of use<https://www.microsoft.com/en-us/business-applications/legal/supp-powerplatform-preview/>.\n > The AI development toolkit is available in sandbox environments only. The Agent SDK for AL is available in sandbox environments and, starting from version 28.1, also in production environments.\n > This article is primarily intended for product owners, domain experts, consultants, and developers who want to experiment with AI capabilities in Business Central.\nThe Tasks AL API allows you to work with custom agents programmatically from AL code. This article covers how to retrieve agent information and write AL code specific to agent sessions.\nFor information about creating and managing agent tasks, including triggering tasks from page actions, business events, adding attachments, and managing task lifecycle, see Coding agents in AL (preview)<ai-agent-sdk-overview>.\n## Get information about the available custom agents\nThe first step to configure agents is to retrieve their user ID. The Agent designer provides an API to retrieve all available agents.\n```al\nlocal procedure GetAllAgents()\nvar\n    CustomAgent: Codeunit \"Custom Agent\";\n    TempAgentInfo: Record \"Custom Agent Info\" temporary;\nbegin\n    // Retrieve all custom agents\n    CustomAgent.GetCustomAgents(TempAgentInfo);\n\n    // Iterate through the agents\n    if TempAgentInfo.FindSet() then\n        repeat\n            // Use the agent information\n            // TempAgentInfo.\"User Security ID\" contains the agent's user ID\n            // TempAgentInfo.\"User Name\" contains the agent's user name\n            Message('Agent: %1 (ID: %2)', TempAgentInfo.\"User Name\", TempAgentInfo.\"User Security ID\");\n        until TempAgentInfo.Next() = 0;\nend;\n```\n## Detect custom agent sessions\nTo write AL code that runs only when a custom agent is executing, use the `Agent Session` codeunit with the `Custom Agent` metadata provider:\n```al\nlocal procedure DoCustomAgentWork()\nvar\n    AgentSession: Codeunit \"Agent Session\";\n    AgentMetadataProvider: Enum \"Agent Metadata Provider\";\nbegin\n    if not AgentSession.IsAgentSession(AgentMetadataProvider::\"Custom Agent\") then\n        exit;\n\n    // Custom agent-specific code goes here...\n    Message('Running in a Custom Agent session!');\nend;\n```\nLearn more about writing AL code specific to agent sessions, including event subscription patterns and task-specific code, in Coding agents in AL (preview)<ai-agent-sdk-overview>.\n## Related information\nOverview (preview)<https://learn.microsoft.com/dynamics365/business-central/dev-itpro/ai/ai-development-toolkit-landing-page>\nDesigning and coding agents (preview)<ai-development-toolkit-overview>\nAgent models (preview)<ai-agent-models>\nCoding agents in AL (preview)<ai-agent-sdk-overview>\nCreate and activate (preview)<ai-development-toolkit-agent-create>\nWrite effective instructions (preview)<ai-development-toolkit-instructions>\nInstruction keywords (preview)<ai-development-toolkit-instruction-keywords>\nSet up permissions and profiles (preview)<ai-development-toolkit-permissions-profiles>\nRun an agent (preview)<ai-development-toolkit-run-agent>\nIterate and manage (preview)<ai-development-toolkit-iterate>\nFrequently asked questions (preview)<ai-development-toolkit-faq>\nBest practices for designing an agent (preview)<ai-development-toolkit-best-practices>\nCreate a Sales Validation Agent (preview)<ai-development-toolkit-sales-validation>\nTransparency note: Business Central AI development toolkit (preview)<transparency-note-ai-development-toolkit>"}