Why an orchestration succeeds in Orchestration Builder but fails in Agent Chat
When you test a Custom Agent Action orchestration inside Orchestration Builder on the Workday Developer Site, every Send Workday API Request step executes directly under your own signed-in user session without consulting the Agent System of Record (ASOR) tool boundary. When you invoke that exact same orchestration through Workday Agent Chat, the agent runtime routes the call through the Workday Agent Gateway using the agent’s Agent System User (ASU) credential.
If the agent runtime or a downstream Workday API call inside the orchestration isn’t authorized at both layers, Agent Chat fails with one of three errors even though the signed-in user holds the domain or role permissions:
S22 Permission Denied(or HTTP403on a REST step) when invoking the Custom Agent Action or a WQL query inside itThe task submitted is not authorized(or HTTP401on a SOAP step) when an orchestration step calls a Workday web service such asSubmit_Billing_ScheduleorGet_Billing_ScheduleUnknown tool(for example,Unknown tool 'use-wql') when the agent attempts to call a resource directly by a non-catalog name or an unregistered identifier
Two independent gates govern Custom Agent Action execution
Under the ASOR Delegate security model, a Custom Agent Action only succeeds when both the Agent Skill resource list and user-plus-ASU domain security align:
- Every Workday resource called inside the orchestration must be declared in
tool-wids: When a Custom Agent launches a Custom Agent Action orchestration, the ASU access credential issued for that run is scoped strictly to the Workday resources registered on the agent’s skill. Listing only the Custom Agent Action’s Action ID lets the agent start the orchestration, but any Send Workday API Request step inside that orchestration (including steps inside suborchestrations) will fail with403,401, orThe task submitted is not authorizedunless the specific REST operation, SOAP operation, custom report, or WQL method WID is also listed in the.agentskillfile’stool-widsblock. - Read-before-write SOAP and REST chains require all operation WIDs: If your orchestration calls
Get_Billing_Schedulefirst to read existing schedule lines and then callsSubmit_Billing_Scheduleto update them, registering only theSubmit_Billing_ScheduleWID still causes the run to fail on the initial read. Every operation touched during the run must be present intool-wids. - Both the user and the underlying data sources require domain access: Registering a resource WID on the agent skill allows the ASU token to call that API endpoint, but does not grant user data access. For WQL queries, both the signed-in user and the security groups configured in ASOR must have
Viewaccess to the Workday Query Language (WQL for Extend) domain and every Primary Business Object (PBO), Related Business Object (RBO), and data source referenced in theSELECTandWHEREclauses.
Discovering the exact resource WIDs with /asor/v1/agentResourceSearch
Do not guess tool names or copy paths from URL strings. Connect to your tenant on the Developer Site as a user with the Agent Management Hub and Setup: Agents domains, click Copy Token, and query the Agent Resource Search API (GET /asor/v1/agentResourceSearch) on your regional Agent Gateway host (https://us.agent.workday.com in the US—never the tenant’s own REST host, which rejects Developer Site tokens):
curl --request GET \
--url "https://us.agent.workday.com/asor/v1/agentResourceSearch?searchString=Billing%20Schedule&toolType=SOAP&operationType=VIEW" \
--header "Accept: application/json"Include your copied bearer credential in the Authorization header. Filter with toolType (REST or SOAP) and operationType (VIEW for GET or SOAP Get_*, CREATE for POST, and PATCH for PATCH or SOAP Put_* / Submit_*).
- Multiple matches: When
agentResourceSearchreturns more than one entry with the same operation name, copy every returnedwidinto your skill definition. - WQL method WIDs: When an orchestration runs WQL via Send Workday API Request, include the WQL operation WID corresponding to the HTTP method your step uses:
GET /wql/v1/data:9749ba9ac47e1000073fdc1bc8a5001aPOST /wql/v1/data:3e15b2a1676d10000c9572ea9cc264b3
- Write SOAP operations omitted from search: If a write SOAP operation does not appear in
agentResourceSearch, run Create Custom Report in your tenant with Report Type set to Advanced, Optimized for Performance unchecked, and Data Source set to Public Web Services (or All Public Service Operations for REST), and output theWeb Service Operation>Workday IDcolumn.
Registering the orchestration and its underlying APIs in .agentskill
Open your .agentskill file in App Builder (Code Mode) and list both the Custom Agent Action (Action ID from the orchestration’s Start step > Configure Request > Custom Agent Actions tab) and every underlying Workday API WID the orchestration invokes:
---
name: update-equipment-billing-schedule
description: "Retrieves an existing billing schedule and submits an updated schedule via the equipmentBillingAction orchestration."
metadata:
tags:
- billing
- equipment-request
allowed-tools:
- equipmentBillingAction
- wqlGet
- get_billing_schedule
- submit_billing_schedule
tool-wids:
- name: equipmentBillingAction
wid: 4a81bc09d12e58749102bcdef1234567
- name: wqlGet
wid: 9749ba9ac47e1000073fdc1bc8a5001a
- name: get_billing_schedule
wid: 2c6143cd33da10000d22312205450221
- name: submit_billing_schedule
wid: c1941a9b6f071000142d9832a9865172
---Formatting in .agentskill files is strict: any leading, trailing, or embedded space inside a wid value prevents the tool from registering in ASOR. Save and deploy the app, then sign out and back in to refresh your session’s access credential (an access credential issued prior to updating the registration does not carry the newly added resource WIDs).
Verifying the fix in your tenant
- In Agent Management Hub, open your agent, go to the Skills tab, and click View Security to open the View Security for Agent Skill report.
- Inspect every tool row in the report for a Functional Status of Review Required or Config Required. Those statuses mean the security groups in the skill’s Available To list are missing from the domain or business process security policy that governs that API or WQL data source.
- For each flagged domain, open Domain > Edit Domain Security Policy Permissions, add the user security group (and any required app/ISU security group for Extend model domains), and run Activate Pending Security Policy Changes.
- Trigger the action again in Agent Chat and inspect the run on the Developer Site under Orchestration Activity (filtering by
OrchIdif an error occurred) and Agent Traces (AviatoTurboChatCISnode) to confirm all steps complete with HTTP200.