A Workday custom agent's lifecycle, from first deploy to Production

What happens in each tenant

A Workday custom agent moves through the same promotion levels as its Extend or Agent app, but registration and activation happen per tenant. In Development, Implementation and Sandbox tenants, Save and Deploy in App Builder pushes the agent to Agent System of Record (ASOR), which registers it automatically; you then configure security and activate it. For Production and other higher environments, you promote the app, register the agent with Update Agents in App Manager, and configure and activate it in that tenant's ASOR.

Three things are permanent and worth knowing before the first deploy: a registered custom agent can't be deleted, an app installed on an Implementation, Sandbox or Production tenant can't be removed from it, and two agents can't share a name.

Stage 1: build and deploy

You build the agent in App Builder, in an Agent app or an Extend app, either with Developer Agent or by writing the .agent and .agentskill files yourself. Before deploying:

1. Make the agent's name final. Workday's tutorial renames the component and then changes the Name in the agent definition to match, and stresses that the two must be identical. You can't create agents with the same name, and a registered agent can't be deleted, so a name you deploy as a test stays taken.
2. Click Validate and clear every error.
3. Check WIDs in the skill files for spaces. A space anywhere in a WID stops that tool from registering, and you find out only when the agent can't call it.

Then click Save and Deploy and choose the tenant. App Builder can deploy only to Development, Implementation and Sandbox tenants. On deploy, the agent artifacts are pushed into ASOR, and in those environments ASOR registers the agent automatically. Before configuration and activation, it stays hidden from users: ASOR is the gate for visibility in the Workday Chat panel.

Stage 2: configure and activate

From the Deploy Successful window, select View Agent Registry, or open Agent Management Hub in the tenant.

1. Open the agent and click Configure Agent.
2. Turn on the agent in the Status column.
3. In Available To, choose the security groups that may use the agent.
4. Click Activate.

Workday creates the agent's Agent System User (ASU), named after the agent, automatically; you never create it by hand. Workday's custom agent page says this happens the first time the agent is activated with a security group assigned, while the Agent Security page describes the ASU being created disabled when skills are enabled and switched on at activation. Either way, every tool call at run time happens under the ASU token.

At run time Workday checks the user's membership in an Available To group, then the user's domain and business process access for each tool. The two sets of groups don't have to match one to one, but a user needs a group on the skill and a group on the tool's API security policies. Run View Security for Agent Skill before you call the agent ready; the ASOR security guide covers what to look for.

A status change can take up to a minute to reach Agent Gateway, so wait before you retest a newly activated or deactivated agent.

Stage 3: iterate with redeploys

Redeploys don't regenerate the ASU. The same ASU persists across skill edits and redeploys, so security you granted it stays in place. To confirm a redeploy changed the tool list, open Agent Traces, then the AviatoTurboChatCIS node of a fresh run: its Inputs list the tools passed to the agent at inference time. If a tool you added is missing there, Workday's advice is to check the ASOR configuration and redeploy. The tab shows the latest 100 runs, Workday keeps traces for 30 days, and the feature is for Extend Professionals only.

Stage 4: promote the app

Promotion happens on the Developer Site, not in App Builder. From Console > Apps, open the app and use the Promotions tab. The levels run Development, Implementation, Sandbox, Production, and each promotion replaces the version at the target level:

• Promoting to Implementation takes the most recent passing build of the latest Development version.
• Promoting to Sandbox takes the latest Implementation version.
• Promoting to Production lets your account administrator install and configure the app on Production tenants.

Your Developer Site role decides how far you can go. Developers and Company Administrators can promote to Production; Specialists only to Implementation and Sandbox. For the app side of promotion in more detail, see promoting Workday Extend apps.

Stage 5: register the agent in the higher tenant

After the app is installed in the higher tenant, register its agents there:

1. In Workday, open App Manager.
2. Select Configure for the app.
3. On the Configuration tab of the App Details page, select Update Agents in the Agent card.
4. In the Update Extend Agents pop-up, select Confirm and click OK, then OK again.

Then repeat stage 2 in that tenant: configure the skill, choose Available To groups, activate. Nothing from the lower tenant's ASOR carries over. Workday states that ASOR must be set up and configured in each tenant because there is no current method to migrate configurations, so the ASOR functional area, its domain security policies, and the agent's security groups all have to exist in the Production tenant first. Workday's ASOR setup also notes that only unconstrained groups can currently be configured on ASOR security policies, which are the domain policies that govern who can manage agents.

Choose the Production Available To groups for the population the agent is for. Workday's tutorial gives a Development agent to HR Administrator for testing; that choice should not carry over. Then use View Security for Agent Skill to confirm those users also hold a group that each tool's policies grant.

Stage 6: deactivate, never delete

When an agent is no longer needed, deactivate it in Agent Management Hub. That hides it from users and keeps it in the hub so you can reactivate it later. Deactivating the agent also deactivates its ASU. There is no delete: once a custom agent is registered, Workday says you can't delete it.

How to prove each stage worked