Skip to main content
Documentation
Documentation
Administrator Guide
Last Updated: 2026-10-09
Connect Custom Agents to External Agents using A2A

Connect Custom Agents to External Agents using A2A

You can connect Custom Agents to external agents, such as Google Gemini Enterprise, using the industry Agent2Agent (A2A) protocol. When you register a third-party client in Workday's Agent System of Record (ASOR), you can enable that agent to discover and call the Custom 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.
This functionality is for Extend Professionals only.
  1. Create a Custom Agent (3P) Agent Definition in ASOR that references your Custom Agent as tools. Workday recommends creating a new agent definition per client system you integrate with, not per Custom Agent.
    1. Access the
      Agent Management Hub
      .
    2. In Agent Registry, select
      Integration IDs
      View IDs
       from the related action of the Custom Agent.
    3. Copy the Workday ID.
    4. Access the Workday Development Site.
    5. Connect to the relevant tenant and select
      Copy Token
      .
    6. Call the ASOR REST API and create a new request to register your agent using an external API Client, Example: Bruno.
      As you create the request, consider:
      1. Endpoint: https://us.agent.workday.com/asor/v1/agentDefinition
      2. Operation: POST
      3. Body: Refer to ASOR v1.2 API documentation on Github and ASOR JSON Swagger documentation sample.
      4. Headers:
        1. Authorization: Bearer <token>
        2. wd-agent-tenant-alias: <your tenant name>
      Example:
      curl --request post \
--url
https://us.agent.workday.com/asor/v1/agentDefinition
\
--header 'Authorization: {{bearer token}}' \
--header 'Content-Type: application/json'
\
--header 'wd-agent-tenant-alias: {{tenant-alias}}'
--data'
"name": "Custom Agent via A2A",
"description": "3P Agent Definition to enable
connectivity between Custom Agents and a 3P System",
"provider": {
},
"id": "Provider=SELF-BUILT"
"url": "https://us.agent.workday.com",
"platform": {
},
"id": "Platform=OTHER"
"skills": [
{
"description": "This skill enables connectivity
to Custom Agents.",
"id": "custom-agent-as-a-tool",
"inputModes": [
{
"type": "text/plain"
}
],
"name": "Custom Agent",
"outputModes": [
{
"type": "text/plain"
},
"type": "application/json"
}
]
}
 ,
"workdayConfig": [
{
"workdayResources":[
{
}
],
"description": "Custom Agent as a tool",
"tool name": "Custom Agent as Tool",
"agent resource": {
"id": "{{Custom Agent wid}}"
}
}
],
"executionMode": {
"id": "Mode=Delegate"
},
"skillId": "custom-agent-as-a-tool"
}'
"capabilities": {
},
"stateTransitionHistory": false,
"streaming": false,
"pushNotifications": false
"supportsAuthenticatedExtendedCard": false,
"version": "v1"
  2. Configure and activate 3P agent in App Registry:
    1. Access the
      Agent Management Hub
      .
    2. In
      Agent Registry
      , select the 3P agent just created.
    3. From the agent's profile view, click
      Configure Agent
      .
    4. In the
      Status
       column, make each relevant skill available by enabling the toggle slider.
    5. For each available delegate execution mode skill, populate the
      Available To
       prompt and determine the security groups that you want to add for that specific skill for the agent.
      The security groups you select in the
      Available To
       prompt must also have permissions to the domain or business process security policies that secure the agents' tools. You can use the
      View Security for Agent Skill
       report to assist with your agent security configurations. This report shows you detailed information about the agent's Tools APIs and the respective domain or business process security policies and permissions. At agent runtime, Workday evaluates both user access to the agent and the user access to the APIs the agent is executing as tools.
    6. Click the
      Confirm
       check box, and then click
      OK
      .
    7. For delegate skills, add the relevant redirect url for the client system you are connecting to.
    8. Click
      OK
      .
    9. When you configure the agent for the first time, we display the OAuth client details for the agent.
    10. Copy and save the Client ID and Client Secret values. This page won't display again and you won't be able to access this information again.
      Select
      Agent Registry
      , and click the agent you want to activate.
    11. From the agent's profile view, click
      Activate Agent
      . On the
      Activate Agent
      window, select the
      Confirm
       check box, and then
      OK
       to complete the activation.
  3. Create or reuse an ISU OAuth client:
    1. Log in to Workday as
      System Admin
      .
    2. Access the
      Create Integration System User
       task (if you don't have a suitable ISU already).
    3. Access the
      Register API Client for Integrations
       task and:
      1. Select
        Agent System of Record
         from the
        Functional Area
         prompt.
      2. Check the
        Include Workday Owned Scopes
         check box.
      3. Save Client ID and Client secret.
    4. On the client:
      1. Click
        Related Actions
        Manage Refresh Tokens
        .
      2. Select the ISU that you created.
      3. Generate a new refresh token.
      4. Record the new refresh token.
    5. You now have:
      1. CLIENT_ID / CLIENT_SECRET (integration client)
      2. REFRESH_TOKEN (ISU)
  4. Generate an ISU bearer token.
    1. Send a POST using POST ISU Bearer Token.yaml in your preferred API client.
      Example:
      curl --request POST
--url
https://us.agent.workday.com/auth/oauth2/TENANT ALIAS/toke
n
--header 'Content-Type:
application/x-www-form-urlencoded'
--data 'grant_type=refresh_token'
--data 'refresh token={{refresh token}}'
--data 'client id={{client id}}'
--data 'client_secret={{client secret}}'
    2. Save the returned ISU Bearer Token.
    3. Retrieve the Agent Card JSON using the GET Agent Card.yaml in your preferred API Client:
      curl --request GET
--url
https://us.agent.workday.com/v1/a2a/TENANT ALIAS/AGENT ID/
.well-known/agent-card.ison
--header 'Authorization: Bearer {{bearer token}}'
--header 'Accept-Encoding: identity'
--header 'Content-Type: application/json'
    4. Save the JSON response. This is your Agent Card.
  5. Configure the external platform.
    1. Import/paste the Agent Card JSON into your external Al platform.
    2. Configure these OAuth settings in the external platform, referencing the details provided in the Connectivity Tab of the Agent you configured:
      1. Client ID
        and
        Client Secret
        .
      2. PKCE
        : Enable PKCE.
      3. Auth URL
        : https://<region-code>.agent.workday.com/auth/authorize/<tenant-alias>?response_type=code.
      4. Token UR
        L: https://<region-code>.agent.workday.com/auth/oauth2/<tenant-alias>/token.
      5. Redirect URL
        : Ensure it matches the Redirect URI from the
        Configure activate 3P agent in App Registry
        step above.
Your external platform can now use the 3P agent.