Connect External Agents to Workday Using A2A

Set Up Agent System of Record.

Ensure that you include a body payload containing the target 3P agent metadata, platform ID, and the Self-Service Agent tool skill configuration (ssa-agent-as-a-tool / resource ID 6bfadd7c014610000dffae8d77c00000).

You can connect AI assistants that run outside Workday, such as Microsoft Copilot and Google Gemini Enterprise, to invoke the Self-Service Agent using the industry Agent2Agent (A2A) protocol. When you register a third-party client in Workday's Agent System of Record, you can enable that agent to discover and call Self-Service Agent on behalf of an authorized user.

For detailed instructions for how to connect Workday to Gemini Enterprise, see Set Up Sana From Workday for Gemini Enterprise.

Configure your external agent in Workday.

Example POST Agent Definition.yaml to register your 3P Agent with Self-Service Agent as a tool


info:
name: POST Agent Definition
type: http
seq: 5
            
http:
method: POST
url: https://{{hostname}}/asor/v1/agentDefinition
headers:
- name: Content-Type
  value: application/json
- name: wd-agent-tenant-alias
  value: wdaiplatform_wcpdev2
- name: accept-encoding
  value: identity
body:
  type: json
  data: |
    {"name": "Workday Self-Service Agent on XYZ client",
    "description": "<<enter a short description of the agent>>",
    "url": "https://your-agent-url.com",
    "documentationUrl": "https://your-agent-docs-url.com",
    "provider": {
            "id": "Provider=Self-Built"},
            "iconUrl": "https://<<icon-url>>",
            "version": "1.0.1",
            "capabilities": {
            "streaming": false,
            "pushNotifications": false,
            "stateTransitionHistory": false},
            "platform": {
            "id": "Platform=<<platform-id>>"
            },
            "defaultInputModes": [
            {
            "type": "text/plain"
            "}],
            "defaultOutputModes": [
            {
            "type": "text/plain"
            },
            {"type": "application/json"
            }
            ],
            "skills": [
            {
            "id": "ssa-agent-as-a-tool",
            "name": "Workday Self-Service Agent",
            "description": "Connects to SSA",
            "tags": [
            {
            "tag": "workday"
            },
            {
            "tag": "workers"
            },
            {
            "tag": "staffing"
            },
            {
            "tag": "hr-operations"
            }
            ],
            "inputModes": [
            {
            "type": "text/plain"
            }
            ],
            "outputModes": [
            {
            "type": "text/plain"
            },
            {
            "type": "application/json"
            }
            ]
            }
            ],
            "workdayConfig": [
            {
            "skillId": "ssa-agent-as-a-tool",
            "executionMode": {
            "id": "Mode=Delegate"
            },
            "workdayResources": [
            {
            "tool_name": "Workday Self-Service Agent",
            "description": "SSA tool",
            "agent_resource": {
            "id": "6bfadd7c014610000dffae8d77c00000"
            }
            }
            ]
            }
            ]
            }
            auth:
            type: bearer
            token: <<ISU Token>>
            runtime: variables:
            - name: hostname
            value: <<agent-gateway hostname>>
            
            settings:
            encodeUrl: true
            timeout: 0
            followRedirects:
            true maxRedirects: 5

Create or reuse an ISU OAuth client:

System Admin

Access the

Create Integration System User

task (if you don’t have a suitable ISU already).

Access the

task and:

Select Agent System of Record
from the Functional Area
prompt.

Check the

Include Workday Owned Scopes

check box.

Save

Client ID

and

Client secret

On the client:

Click

Related Actions

Manage Refresh Tokens

Select the ISU that you created.

Generate a new refresh token.

Record the new refresh token.

You now have:

CLIENT_ID / CLIENT_SECRET (integration client)

REFRESH_TOKEN (ISU)

TENANT_ALIAS (typically your tenant name).

Generate an ISU bearer token.

Send a POST using POST ISU Bearer Token.yaml in your preferred API client.

Example:


                info: name: POST ISU Bearer Token
                type: http
                seq: 7
                http:
                method: POST
                url: https://<<agent-gateway-hostname>>/auth/oauth2/{{tenant-alias}}/token
                body:
                type: text
                data: grant_type=refresh_token&refresh_token={{refresh-token}}&client_id={{client-id}}&client_secret={{client-secret}}
                auth: inherit
                
                runtime:
                variables:
                - name: refresh-token
                value: <<refresh-token>>
                - name: tenant-alias
                value: <<tenant-alias>>
                - name: client-secret
                value: <<client-secret>>
                - name: client-id
                value: <<client-id>> scripts:
                - type: after-response
                code: |-
                let data = res.getBody();
                bru.setEnvVar("bearer-token", data.access_token);     
                bru.setEnvVar("refresh-token", data.refresh_token);
                
                settings:
                encodeUrl:true
                timeout: 0
                followRedirects: true
                maxRedirects: 5

Save the returned ISU Bearer Token.

Retrieve the Agent Card JSON using the GET Agent Card.yaml in your preferred API Client:


                info:
                name: GET Agent Card
                type: http seq: 2
                
                http:
                method: GET
                url: https://{{agent-gateway-hostname}}/v1/a2a/{{tenant-alias}}/{{agent-wid}}/.well-known/agent-card.json
                headers:
                - name: Accept-Encoding
                value: identity
                - name: Content-Type
                value: application/json
                - name: Authorization
                value: Bearer {{bearer-token}}
                body:
                type: json
                data: ""
                auth: inherit
                
                runtime:
                variables:
                - name: tenant-alias
                value: <<tenant-alias>>
                - name: bearer-token
                value: <<ISU-bearer-token>>
                - name: agent-wid
                value: <<self-service-agent-wid>>
                
                settings:
                encodeUrl: true
                timeout: 0
                followRedirects: true
                maxRedirects: 5

Save the JSON response. This is your Agent Card.

Configure the external platform.

Import/paste the Agent Card JSON into your external AI platform.

Configure these OAuth settings in the external platform:

Client ID

and

Client Secret

: Use the credentials saved from the

Configure and Activate the New Agent in Workday

step above.

PKCE

: Enable PKCE.

Auth URL

: https://<region-code>[.agent.workday.com/auth/authorize/](https://.agent.workday.com/auth/authorize/)<tenant-alias>?response_type=code.

Token URL

: https://<region-code>[.agent.workday.com/auth/oauth2/](https://.agent.workday.com/auth/oauth2/)<tenant-alias>/token.

Redirect URL

: Ensure it matches the Redirect URI from the

Configure and Activate the New Agent in Workday

step above.

Grant end users access.

In Workday: Ensure target end users belong to the security groups assigned in the

Configure and Activate the New Agent in Workday

step above.

In the external platform: Assign the Workday Agent configuration, roles, or permissions to the appropriate end-users/groups in the external system.

Your external platform can now retrieve information from Workday and displays it in responses.