Put the agent in the app, not next to it
If you already have a working Extend app, add the custom agent to that app rather than starting an Agent app beside it. Workday lets you build a custom agent in either app type, but an Agent app is cut down for agent work: it supports only agents, skills, attributes and orchestrations, and it can't contain PMD pages or Extend model components. An agent whose whole point is to read and write your app's business objects belongs where those objects live.
The trade-off is entitlement. Workday says Agent apps don't count against Extend app entitlements, so an Agent app is the natural home for an agent that only calls Workday's own tools. An agent whose tools are your app's business objects has no such option, because the Agent app can't hold the model components those tools come from.
The three ways the agent reaches your app
Once the agent is a component of the app, it has three ways in. Each is a tool listed in the agent's .agentskill file under allowed-tools, with its Workday ID under tool-wids.
The app's own model REST operations. Workday's sample Work Event agent shows this best. Its skills call tools with names like get_createAWorkEventWithAgent_mcwslt_workEvents and patch_createAWorkEventWithAgent_mcwslt_workEvents, which, going by their names, are generated from the sample app's Work Event business object (Workday's page doesn't spell this out). When you sign in to a tenant, the MCP Explorer lists your Extend model components alongside Workday's Agent-Ready tools, so you can copy those IDs from there. For an app built on business objects, this is usually most of what the agent needs: find, read, update.
Custom Agent Action orchestrations. Anything that isn't a single REST operation, such as your own logic, several Workday REST or SOAP calls in one action, or a connector to another system, goes in an orchestration built from the Custom Agent Action template. The Action Description you write on its Custom Agent Actions tab tells the agent what the action does and when to use it, and its annotation (Read-Only, Idempotent, Destructive, Open World) decides whether the user is asked to approve each call: Workday agents ask for every action that isn't Read-Only. Our guide to Custom Agent Actions that call SOAP, REST and WQL covers building these.
Agent pages for structured input. Workday's sample doesn't let the model create a Work Event by itself. Its create skill instructs the agent to collect the details by calling generate_a2ui with an agent page, createEventAui, and says the page creates the event on submit: "Never under any circumstance create the event on your own." The edit skill does the same with editEventAui, then patches the record only after the page returns a submit action. Workday's documentation shows this pattern only in the sample, not as a reference topic, so read the sample's .agentskill files closely before building your own agent pages.
In an existing app this is the pattern to copy first, as a design choice rather than a documented requirement: you already know which fields your create and edit flows need, and a page collects them in one place instead of the model assembling a record from free text.
What changes in security
Nothing about your app's security model goes away, but a second check is added in front of it.
Custom agents run in delegate mode only. Workday first checks whether the user belongs to a security group on the skill's Available To list, and denies the interaction if not, however much domain access the user has. It then checks the user's domain and business process permissions for the tools the skill calls. Tool calls at run time happen under the agent's Agent System User (ASU), and Workday's custom agent documentation notes that user and agent security are separate: a user can invoke an agent that does things they can't do directly, and the reverse.
Two consequences for an existing app:
- Available To doesn't have to match the groups on your app's security domain policies one to one, but a user needs a group that is on the skill and a group that the tool's policies grant. Run View Security for Agent Skill after deployment to see each tool's domain and business process policies and compare them with your Available To groups.
- Read your skill list with the separation of user and agent security in mind: every tool you add is something any Available To member can ask the agent to run.
A first version worth shipping
For an app built around one business object, a sensible first agent has three skills, mirroring Workday's sample:
- Find: a read-only skill on the object's GET operation, returning a short list with IDs so the user can pick one.
- View: show one record, by ID, ideally on an agent page.
- Edit or create: collect changes on an agent page and save only on the page's submit.
The agent definition's system prompt routes between them. The sample's .agent file tells the model that if a user asks to edit a Work Event without saying which, it should use the find skill first, then edit.
If users need to hand the agent a document, add Workday's agent_file_download tool to the skill's tool-wids and describe in the skill's steps when to use it; users then attach files through the Sources button in Workday Chat.
How to know it is working
Deploy, configure and activate the agent, then use it from the Workday Chat panel as a member of one of the Available To groups. Then open the app's Agent Traces tab in App Builder (Workday limits this to Extend Professionals, and it keeps traces for 30 days) and read the run. The AviatoTurboChatCIS node shows the tool list the model was given and the tool calls it made as JSON. If a tool you expected is missing from the inputs, Workday's advice is to check the ASOR configuration and redeploy.
Finally, read the business object back in the app. The chat reply is the model's account of what happened; the instance shows what changed.
Two lifecycle facts to settle before the first deploy: once a custom agent is registered, you can't delete it, only deactivate it; and App Builder deploys only to Development, Implementation and Sandbox tenants, so Production needs the app promoted and Update Agents run in App Manager. The custom agent lifecycle guide covers both.