# ASOR API Documentation v1.2

<div style="background: #f7f7f7; padding: 20px; border-radius: 5px; margin-bottom: 20px;">
<h2 style="margin-top: 0; color: #3b4151;">asor</h2>
<p><strong>Version:</strong> v1.2</p>
<p><strong>Base URL:</strong> <code>https://{workday-host}/api/asor/v1/{tenantname}/agentDefinition</code></p>
<p>The Agent System of Record Service is used to create and maintain Agent Definitions in Workday.</p>
</div>

## 📋 Navigation
- [🏠 All Versions](../README.md)
- [📖 Current: v1.2 Spec](#) : [📖 Current: v1.2 JSON](v1.2.json)

---

## 📡 Endpoints

### <span style="background: #49cc90; color: white; padding: 4px 8px; border-radius: 3px; font-size: 12px;">GET</span> `/agentDefinition/{id}`

> **Summary:** This operation returns the specific Agent Definition including Skills and certain Tools used in those Skills.

**Description:** This operation returns the specific Agent Definition including Skills and certain Tools used in those Skills. Each definition can contain many Skills, and in those Skills they *may* contain Tools based on the Invocation / Execution Type. Generally REST APIs will be listed here.

<b>Secured by:</b> Setup: Agents

#### Responses

| Status Code | Description | Schema |
|-------------|-------------|--------|
| <span style="background: #49cc90; color: white; padding: 2px 6px; border-radius: 3px;">200</span> | Successful response. A successful response can return no matched data. | [agentCardAndTools](#agentcardandtools) |
| <span style="background: #f93e3e; color: white; padding: 2px 6px; border-radius: 3px;">400</span> | Invalid request. (https://community.workday.com/rest/error-messages) | [VALIDATION_ERROR_MODEL_REFERENCE](#validation_error_model_reference) |
| <span style="background: #f93e3e; color: white; padding: 2px 6px; border-radius: 3px;">401</span> | Invalid resource or operation. (https://community.workday.com/rest/error-messages) | [VALIDATION_ERROR_MODEL_REFERENCE](#validation_error_model_reference) |
| <span style="background: #f93e3e; color: white; padding: 2px 6px; border-radius: 3px;">403</span> | User has insufficient permissions. (https://community.workday.com/rest/error-messages) | [VALIDATION_ERROR_MODEL_REFERENCE](#validation_error_model_reference) |
| <span style="background: #f93e3e; color: white; padding: 2px 6px; border-radius: 3px;">404</span> | Resource not found. (https://community.workday.com/rest/error-messages) | [VALIDATION_ERROR_MODEL_REFERENCE](#validation_error_model_reference) |
| <span style="background: #999; color: white; padding: 2px 6px; border-radius: 3px;">default</span> | An error occurred. | [ERROR_MODEL_REFERENCE](#error_model_reference) |


---

### <span style="background: #61affe; color: white; padding: 4px 8px; border-radius: 3px; font-size: 12px;">POST</span> `/agentDefinition`

> **Summary:** Based on the A2A Agent Card specification, this REST operation allows you to create an Agent Definition in Workday.

**Description:** Based on the A2A Agent Card specification, this REST operation allows you to create an Agent Definition in Workday, while also highlighting the specific Workday APIs/Resources that the Agent is allowed access to. It will update an existing instance IF one already exists with the same *name*, *provider organization*, and *version*.

<b>Secured by:</b> Development

#### Parameters

| Parameter | Location | Type | Required | Description                                                                                              |
|-----------|----------|------|----------|----------------------------------------------------------------------------------------------------------|
| `agentCardAndTools` | body | [agentCardAndTools](#agentcardandtools) | ✅ Yes | The Agent Definition that contains Skills optionally identifying Workday resources used in those Skills. |


#### Request Body

**Content Type:** `application/json`

**Schema:** [agentCardAndTools](#agentcardandtools)

#### Responses

| Status Code | Description | Schema |
|-------------|-------------|--------|
| <span style="background: #49cc90; color: white; padding: 2px 6px; border-radius: 3px;">201</span> | Resource created. | [agentCardAndTools](#agentcardandtools) |
| <span style="background: #f93e3e; color: white; padding: 2px 6px; border-radius: 3px;">400</span> | Invalid request. (https://community.workday.com/rest/error-messages) | [VALIDATION_ERROR_MODEL_REFERENCE](#validation_error_model_reference) |
| <span style="background: #f93e3e; color: white; padding: 2px 6px; border-radius: 3px;">401</span> | Invalid resource or operation. (https://community.workday.com/rest/error-messages) | [VALIDATION_ERROR_MODEL_REFERENCE](#validation_error_model_reference) |
| <span style="background: #f93e3e; color: white; padding: 2px 6px; border-radius: 3px;">403</span> | User has insufficient permissions. (https://community.workday.com/rest/error-messages) | [VALIDATION_ERROR_MODEL_REFERENCE](#validation_error_model_reference) |
| <span style="background: #f93e3e; color: white; padding: 2px 6px; border-radius: 3px;">404</span> | Resource not found. (https://community.workday.com/rest/error-messages) | [VALIDATION_ERROR_MODEL_REFERENCE](#validation_error_model_reference) |
| <span style="background: #999; color: white; padding: 2px 6px; border-radius: 3px;">default</span> | An error occurred. | [ERROR_MODEL_REFERENCE](#error_model_reference) |


---

## 📊 Models

### agentCardAndTools {#agentcardandtools}

| Property | Type                                | Description                                                                                                                                | Required |
|----------|-------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------|----------|
| `id` | `string`                            | The ID is part of the return payload when an Agent is created, it represents the internal Workday ID for this Agent. | ❌ No |
| `name` | `string`                            | Human readable name of the agent.                                                                                                          | ✅ Yes |
| `description` | `string`                            | A human-readable description of the agent. Used to assist users and other agents in understanding what the agent can do.                   | ✅ Yes |
| `url` | `string`                            | A URL to the address the agent is hosted at.                                                                                               | ✅ Yes |
| `overview` | `string`                            | A message to display when summarizing this Agent or when this Agent is initially invoked.                                                                                              | ❌ No |
| `iconUrl` | `string`                            | A URL to an icon for the agent.                                                                                                            | ❌ No |
| `provider` | [provider](#provider)               | The service provider of the agent.                                                     | ✅ Yes |
| `platform` | [platform](#platform)               | The Platform that this Agent is executing on. If no appropriate Platform is available use OTHER.                                                 | ✅ Yes |
| `version` | `string`                            | The version of the agent - format is up to the provider.                                                                                   | ✅ Yes |
| `documentationUrl` | `string`                            | A URL to documentation for the agent.                                                                                                      | ❌ No |
| `externalAgentID` | `string`                            | A referenceable ID that is understood by the partner system, useful for callbacks from Workday.                                                                                 | ❌ No |
| `externalTenantID` | `string`                            | A referenceable ID to locate where this Agent lives in the partner system to match the Workday tenant.                                                                                 | ❌ No |
| `capabilities` | [capabilities](#capabilities)       | Optional capabilities supported by the agent.                                                                                              | ✅ Yes  |
| `defaultInputModes` | `array`[mimeType](#mimeType)        | The set of interaction modes that the agent supports across all skills. This can be overridden per-skill. Supported media types for input. | ❌ No |
| `defaultOutputModes` | `array`[mimeType](#mimeType)        | Supported media types for output.                                                                                                          | ❌ No |
| `skills` | `array`[agentskill](#agentskill)    | Skills are a unit of capability that an agent can perform.                                                                                 | ✅ Yes |
| `supportsAuthenticatedExtendedCard` | `boolean`                           | true if the agent supports providing an extended agent card when the user is authenticated. Defaults to false if not specified.            | ❌ No |
| `workdayConfig` | `array`[agentSkillResource](#agentSkillResource) | Identify Workday Resources to be used in Agent Skills.                                                                                     | ❌ No |

### provider {#provider}

The service provider of the agent

| Property | Type | Description | Required |
|----------|------|-------------|----------|
| `id` | `string` | Agent Provider Reference ID = "Provider={Provider Name} | ✅ Yes |

### platform {#platform}

The execution platform for this agent

| Property | Type | Description | Required |
|----------|------|-------------|----------|
| `id` | `string` | Agent Platform Reference ID = "Platform={Platform Name} | ✅ Yes |


### capabilities {#capabilities}

Optional capabilities supported by the agent.

| Property | Type | Description | Required |
|----------|------|-------------|----------|
| `pushNotifications` | `boolean` | true if the agent can notify updates to client. | ❌ No |
| `streaming` | `boolean` | true if the agent supports SSE. | ❌ No |
| `stateTransitionHistory` | `boolean` | true if the agent exposes status change history for tasks. | ❌ No |

### mimeType {#mimetype}

| Property | Type | Description | Required |
|----------|------|-------------|----------|
| `type` | `string` | Supported media type. | ✅ Yes |

### agentSkill {#agentskill}

| Property | Type | Description | Required |
|----------|------|-------------|----------|
| `id` | `string` | Unique identifier for the agent's skill. | ✅ Yes |
| `name` | `string` | Human readable name of the skill. | ✅ Yes |
| `description` | `string` | Description of the skill - will be used by the client or a human as a hint to understand what the skill does. | ✅ Yes |
| `tags` | `array`[agentSkillTag](#agentSkillTag) | Set of tagwords describing classes of capabilities for this specific skill. | ✅ Yes |
| `inputModes` | `array`[mimeType](#mimeType) | The set of interaction modes that the skill supports (if different than the default). | ❌ No |
| `outputModes` | `array`[mimeType](#mimeType) | Supported media types for output. | ❌ No |


### agentSkillTag {#agentskilltag}

| Property | Type | Description | Required |
|----------|------|-------------|----------|
| `tag` | `string` | Will be used by the client as a hint to understand how the skill can be used. | ✅ Yes |


### agentSkillResource {#agentskillresource}

| Property | Type                                       | Description | Required |
|----------|--------------------------------------------|-------------|----------|
| `skillId` | `string`                                   | Unique identifier for the agent's skill. | ✅ Yes |
| `executionMode` | [executionMode](#executionMode)                 | Unique identifier for the agent's skill. | ✅ Yes |
| `workdayResources` | `array`[workdayResource](#workdayResource) | List of Workday Resources used by this agents skill. | ✅ Yes |

### executionMode {#executionMode}

| Property    | Type   | Description                                 | Required |
|-------------|--------|---------------------------------------------|----------|
| `id`        | `enum`[Ambient, Delegate] | If this Skill requires/necessitates human invocation, it is "Delegate". If no human is required to invoke it would be classed as "Ambient". This deliniates the Grant Type necessary. Note, must be in format "Mode=Ambient" or "Mode=Delegate" | ✅ Yes |

### workdayResource {#workdayResource}

| Property    | Type                          | Description                                                                                                                 | Required |
|-------------|-------------------------------|-----------------------------------------------------------------------------------------------------------------------------|----------|
| `agent_resource`        | [agent_resource](#agent_resource) | Workday Resource for this Tool if applicable.           | ❌ No |
| `tool_name`       | `string`                      | The Operation that defines what this Tool can do - i.e. Endpoint or Task.          | ✅ Yes |
| `description` | `string`                      | Description of the Operation.                                         | ❌ No |
| `tools` | `array`[tools](#tools)      | List of *related* Workday Securable Items. For example, Data Sources for WQL queries. | ❌ No |

### agent_resource {#agent_resource}

| Property | Type   | Description                                             | Required |
|----------|--------|---------------------------------------------------------|----------|
| `id`     | `string` | Workday ID of the Workday Tool required for this Skill. | ✅ Yes |
| `descriptor`     | `string` | In Preview Only ** Only used for Orchestrate Actions ** Name of this Agent Action | ❌ No |
| `type`     | `string` | In Preview Only ** Only used for Orchestrate Actions ** MUST BE the string `AGENT_ACTION` (later will be other action types) | ❌ No |

### tools {#tools}

| Property | Type | Description | Required |
|----------|------|-------------|----------|
| `id` | `string` | Workday ID of the Workday Securable Item related to this Agent Tool - i.e. CRF Fields or Data Sources etc. | ✅ Yes |

### VALIDATION_ERROR_MODEL_REFERENCE {#validation_error_model_reference}

| Property | Type | Description | Required |
|----------|------|-------------|----------|
| `error` | `string` | A description of the error | ✅ Yes |
| `errors` | `array` | An array of validation errors | ❌ No |

### ERROR_MODEL_REFERENCE {#error_model_reference}

| Property | Type | Description | Required |
|----------|------|-------------|----------|
| `error` | `string` | A description of the error | ✅ Yes |
| `code` | `string` | The code that corresponds to the error message. Use the error code to drive programmatic error-handling behavior. Don't use error message strings for this purpose because they are subject to change | ❌ No |
| `field` | `string` | The field related to the error | ❌ No |
| `path` | `string` | The path of the field related to the error | ❌ No |

---