Which way does A2A go for a Workday custom agent?

Over A2A, an agent platform outside Workday, such as Google Gemini Enterprise, discovers your Workday custom agent and calls it on behalf of a signed-in user. You set this up by registering a separate third-party (3P) agent definition in Agent System of Record (ASOR) whose skill uses the custom agent as its tool, then handing the outside platform that definition's agent card and OAuth details.

Workday documents only that direction. Its A2A pages do not describe a custom agent calling another vendor's agent, and the custom agent runtime is closed by design: it routes every call through its own tool clients and "can't invoke arbitrary API calls". Bundled and model-generated scripts in a skill run with no network egress. If your design needs the Workday agent to consult an outside system, that call goes in a Custom Agent Action orchestration (see Custom Agent Actions that call SOAP, REST and WQL), not in A2A.

Workday marks this feature as for Extend Professionals only, the SKU it has since renamed Extend AI. The custom agent must already be built, deployed and active (see the custom agent lifecycle), and ASOR must be set up in the tenant.

Why you need a second agent definition

The custom agent you built in App Builder is registered in ASOR automatically, but it is a Workday-side agent. The outside platform needs its own identity in ASOR: its own OAuth client, its own redirect URI and its own Agent System User (ASU). So you create a 3P agent definition whose only skill points at the custom agent. Workday recommends one 3P definition per client system you connect, not one per custom agent, so a single Gemini Enterprise registration can expose several custom agents as tools.

Step 1: get the custom agent's Workday ID

  1. Open Agent Management Hub.
  2. In Agent Registry, open the related actions of your custom agent and select Integration IDs > View IDs.
  3. Copy the Workday ID. This is the agent_resource.id in the next step.

Step 2: register the 3P agent definition with the ASOR API

External agents are registered only through the ASOR API, with a POST to /asor/v1/agentDefinition on your region's Agent Gateway host. The caller needs the Setup: Agents domain. The simplest token is the Developer Site's: connect to the tenant there and use Copy Token. Send two headers, Authorization: Bearer <access token> and wd-agent-tenant-alias: <tenant name>.

The example body on Workday's A2A page is malformed JSON in places, so here is the same definition assembled from it. The tool_name and agent_resource spellings come from Workday's sample ASOR agent definitions:

{
  "name": "Custom Agent via A2A",
  "description": "3P definition that lets one client system call Workday custom agents",
  "provider": { "id": "Provider=SELF-BUILT" },
  "platform": { "id": "Platform=OTHER" },
  "url": "https://us.agent.workday.com",
  "version": "v1",
  "capabilities": {
    "streaming": false,
    "pushNotifications": false,
    "stateTransitionHistory": false
  },
  "skills": [
    {
      "id": "custom-agent-as-a-tool",
      "name": "Custom Agent",
      "description": "Connects the client system to Workday custom agents.",
      "inputModes": [{ "type": "text/plain" }],
      "outputModes": [{ "type": "text/plain" }, { "type": "application/json" }]
    }
  ],
  "workdayConfig": [
    {
      "skillId": "custom-agent-as-a-tool",
      "executionMode": { "id": "Mode=Delegate" },
      "workdayResources": [
        {
          "tool_name": "Custom Agent as Tool",
          "description": "Equipment Request agent",
          "agent_resource": { "id": "<custom agent Workday ID>" }
        }
      ]
    }
  ]
}

Use the real provider and platform IDs from the View Agent Provider and View Agent Platforms tasks if Provider=SELF-BUILT and Platform=OTHER don't fit. Delegate is the only mode that makes sense here: custom agents are delegate-only.

To change the definition later, post it again with the same name, version and provider. Workday updates the existing registration when all three match and creates a new one when they don't, so a typo in the version leaves you with two agents.

Step 3: configure and activate the 3P agent

  1. In Agent Registry, open the new 3P agent and click Configure Agent.
  2. Enable the skill in the Status column.
  3. In Available To, choose the security groups whose members may use it from the outside platform.
  4. Confirm, then enter the Redirect URI of the outside platform's OAuth callback.
  5. Copy the Client ID and Client Secret shown. Workday shows them once. If you lose the secret, the agent's Credentials tab has Generate a New Client Secret, which replaces the old one.
  6. Click Activate Agent and confirm.

Workday checks two things at run time: that the user is in an Available To group, and that the user has the domain or business process permissions behind every tool the custom agent calls. Run View Security for Agent Skill on the custom agent's skills and fix any policy that excludes the groups you chose. The ASOR security guide covers this check in detail.

Step 4: fetch the agent card

The outside platform reads the agent's A2A agent card. Workday's steps obtain a bearer token for an integration system user (an API client registered for integrations with the Agent System of Record functional area and Include Workday Owned Scopes, plus a refresh token generated for the ISU), then call:

GET https://us.agent.workday.com/v1/a2a/<tenant alias>/<agent Workday ID>/.well-known/agent-card.json
Authorization: Bearer <ISU access token>
Accept-Encoding: identity

Workday's custom-agent page labels the path segment only as the agent ID. Its Self-Service Agent counterpart fills the same segment with the Workday agent's own ID, so start with the custom agent's ID from step 1. Save the JSON response; it is the agent card you import.

Step 5: configure the outside platform

Import the agent card, then set the OAuth client on the platform:

  • Client ID and Client Secret from step 3.
  • PKCE enabled.
  • Auth URL: https://<region>.agent.workday.com/auth/authorize/<tenant alias>?response_type=code
  • Token URL: https://<region>.agent.workday.com/auth/oauth2/<tenant alias>/token
  • Redirect URL exactly as entered in step 3.

The region prefix must match the data center that hosts the tenant. Agent Gateway runs at us, eu, uk, ca, au, sg, in and jp hosts. Changing region resets the agent's analytics in Agent Management Hub.

Finally, grant access on both sides: the people who will use it must be in the Workday security groups from step 3, and the outside platform must assign them the Workday agent configuration through its own roles or permissions.

How to prove it works

  • The card loads. The GET in step 4 returns JSON, not an error. If it fails, the bearer token or the agent ID in the path is wrong.
  • A user can sign in. On first use, the user signs in to Workday and sees an Allow/Deny page granting the agent access to their account. A user outside every Available To group is refused even if their domain security would allow the tasks.
  • The audit trail shows both identities. Run View AI Agent User Audit Trail. In delegate mode Workday records the agent's ASU as By User and the person as On Behalf Of User.
  • The custom agent actually ran. Open the custom agent's app in App Builder and check Agent Traces for the run. Traces can take a few seconds to appear, and the tab shows the latest 100.

What breaks it after it worked

Delegate access tokens for external agents last 4 hours and refresh tokens 24 hours, and Workday does not let you change that for third-party agents yet. A platform that caches tokens longer will start failing a day later. Workday also notes that expires_in can come back as a string or an integer depending on the environment, so the client should accept both.

Activating or deactivating an agent can take up to a minute to reach Agent Gateway, so test again after a short wait before assuming a configuration change failed.

Sources checked