Skip to content

feat(spec): add optional inputFields and outputFields and to AgentSkill #814

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

feat(spec): add optional inputFields and outputFields and to AgentSkill #814

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f2b46bd
feat: add optional `inputFields` and `outputFields` to `AgentSkill`
inesmcm26 Jun 30, 2025
ab8597a
update specification.md and add field definition to proto
inesmcm26 Jul 1, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions docs/llms.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -74,6 +74,8 @@ Key features of the A2A protocol highlighted by the specification and samples in
- `examples`: (string[]) Example prompts or use cases demonstrating skill usage (optional).
- `inputModes`: (string[]) Overrides `defaultInputModes` for this specific skill. Accepted Media Types (optional).
- `outputModes`: (string[]) Overrides `defaultOutputModes` for this specific skill. Produced Media Types (optional).
- `inputFields`: (FieldDefinition[]) Structured input fields expected by this skill (richer metadata, see FieldDefinition).
- `outputFields`: (FieldDefinition[]) Structured output fields produced by this skill (richer metadata, see FieldDefinition).
- **`Task`:** Represents a unit of work processed by an agent.
- `id`: (string) Unique task identifier.
- `contextId`: (string) Groups related tasks in a conversation or session.
Expand Down
95 changes: 69 additions & 26 deletions docs/specification.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -233,15 +233,34 @@ Describes a specific capability, function, or area of expertise the agent can pe
--8<-- "types/src/types.ts:AgentSkill"
```

| Field Name | Type | Required | Description |
| :------------ | :--------- | :------- | :----------------------------------------------------------------------------- |
| `id` | `string` | Yes | Unique skill identifier within this agent. |
| `name` | `string` | Yes | Human-readable skill name. |
| `description` | `string` | Yes | Detailed skill description. [CommonMark](https://commonmark.org/) MAY be used. |
| `tags` | `string[]` | Yes | Keywords/categories for discoverability. |
| `examples` | `string[]` | No | Example prompts or use cases demonstrating skill usage. |
| `inputModes` | `string[]` | No | Overrides `defaultInputModes` for this specific skill. Accepted Media Types. |
| `outputModes` | `string[]` | No | Overrides `defaultOutputModes` for this specific skill. Produced Media Types. |
| Field Name | Type | Required | Description |
| :------------ | :------------------ | :------- | :----------------------------------------------------------------------------- |
| `id` | `string` | Yes | Unique skill identifier within this agent. |
| `name` | `string` | Yes | Human-readable skill name. |
| `description` | `string` | Yes | Detailed skill description. [CommonMark](https://commonmark.org/) MAY be used. |
| `tags` | `string[]` | Yes | Keywords/categories for discoverability. |
| `examples` | `string[]` | No | Example prompts or use cases demonstrating skill usage. |
| `inputModes` | `string[]` | No | [Deprecated] Accepted Media Types for input. |
| `outputModes` | `string[]` | No | [Deprecated] Produced Media Types for output. |
| `inputFields` | `FieldDefinition[]` | No | Structured input fields expected by this skill. |
| `outputFields`| `FieldDefinition[]` | No | Structured output fields produced by this skill. |

#### 5.5.4.1. `FieldDefinition` Object

Describes an expected input or output field for an agent skill. This allows agents to declare the structure, type, and semantics of the fields they expect as input or produce as output, enabling richer client validation and UI generation.

```ts { .no-copy }
--8<-- "types/src/types.ts:FieldDefinition"
```

| Field Name | Type | Required | Description |
| :----------- | :------------------ | :------- | :----------------------------------------------------------------- |
| `name` | `string` | No | Optional name of the field. |
| `kind` | `"text" \| "file" \| "data"` | No | The kind of content for this field: text, file, or data. |
| `mimeTypes` | `string[]` | No | Optional list of supported mime types for this field. |
| `schema` | `object` | No | Optional schema for data parts (structured data). |
| `description`| `string` | No | Optional description of the field. |
| `optional` | `boolean` | No | Whether this field is optional. |

### 5.6. Sample Agent Card

Expand Down Expand Up @@ -281,28 +300,52 @@ Describes a specific capability, function, or area of expertise the agent can pe
"Plan a route from '1600 Amphitheatre Parkway, Mountain View, CA' to 'San Francisco International Airport' avoiding tolls.",
"{\"origin\": {\"lat\": 37.422, \"lng\": -122.084}, \"destination\": {\"lat\": 37.7749, \"lng\": -122.4194}, \"preferences\": [\"avoid_ferries\"]}"
],
"inputModes": ["application/json", "text/plain"],
"outputModes": [
"application/json",
"application/vnd.geo+json",
"text/html"
]
"inputModes": ["text/plain"],
"outputModes": ["application/json", "application/vnd.geo+json", "text/html"],
"inputFields": [
{"name": "origin", "kind": "text", "optional": "false"},
{"name": "destination", "kind": "text", "optional": "false"},
{"name": "preference", "kind": "text", "optional": "false"}
],
"outputFields": [
{
"name": "route",
"kind": "data",
"mimeTypes": ["application/json", "application/vnd.geo+json", "text/html"],
"description": "A JSON object containing the computed route details, including geometry, directions, and any relevant metadata.",
"optional": "false"
}
],
},
{
"id": "custom-map-generator",
"id": "custom-map-generator",
"name": "Personalized Map Generator",
"description": "Creates custom map images or interactive map views based on user-defined points of interest, routes, and style preferences. Can overlay data layers.",
"tags": ["maps", "customization", "visualization", "cartography"],
"examples": [
"Generate a map of my upcoming road trip with all planned stops highlighted.",
"Show me a map visualizing all coffee shops within a 1-mile radius of my current location."
],
"inputModes": ["application/json"],
"outputModes": [
"image/png",
"image/jpeg",
"application/json",
"text/html"
"outputModes": ["image/png", "image/jpeg", "application/json", "text/html"],
"inputFields": [
{
"kind": "data",
"mimeTypes": ["application/json"],
"description": "List of locations to plot on the map",
"optional": "false"
}
],
"outputFields": [
{
"name": "mapImage",
"kind": "file",
"mimeTypes": ["image/png", "image/jpeg"],
"description": "Rendered map image",
"optional": "true",
},
{
"name": "mapData",
"kind": "data",
"mimeTypes": ["application/json"],
"description": "Data representing the map",
"optional": "true",
}
]
}
],
Expand Down
2 changes: 1 addition & 1 deletion docs/topics/agent-discovery.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ The Agent Card is a JSON document that serves as a digital "business card" for a
- **Service Endpoint:** The `url` where the A2A service can be reached.
- **A2A Capabilities:** Supported protocol features like `streaming` or `pushNotifications`.
- **Authentication:** Required authentication `schemes` (e.g., "Bearer", "OAuth2") to interact with the agent.
- **Skills:** A list of specific tasks or functions the agent can perform (`AgentSkill` objects), including their `id`, `name`, `description`, `inputModes`, `outputModes`, and `examples`.
- **Skills:** A list of specific tasks or functions the agent can perform (`AgentSkill` objects), including their `id`, `name`, `description`, `inputModes`, `outputModes`, `examples`, as well as optional structured `inputFields` and `outputFields` describing the expected input and output for each skill.

Client agents parse the Agent Card to determine if a remote agent is suitable for a given task, how to structure requests for its skills, and how to communicate with it securely.

Expand Down
16 changes: 16 additions & 0 deletions docs/tutorials/python/3-agent-skills-and-card.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,8 @@ Key attributes of an `AgentSkill` (defined in `a2a.types`):
- `tags`: Keywords for categorization and discovery.
- `examples`: Sample prompts or use cases.
- `inputModes` / `outputModes`: Supported Media Types for input and output (e.g., "text/plain", "application/json").
- `inputFields` / `outputFields`: Structured input/output fields (see `FieldDefinition`).


In `__main__.py`, you can see how a skill for the Helloworld agent is defined:

Expand All @@ -25,6 +27,20 @@ In `__main__.py`, you can see how a skill for the Helloworld agent is defined:

This skill is very simple: it's named "Returns hello world" and primarily deals with text.

### FieldDefinition: Describing Structured Inputs and Outputs

A **FieldDefinition** describes a structured input or output field for an agent skill. This is useful when a skill expects (or produces) more than just free-form text—such as a JSON object, a file, or a set of named parameters.

Key attributes of a `FieldDefinition` (from `a2a.types`):

- `name`: (optional) The name of the field.
- `kind`: (optional) The type of content: `"text"`, `"file"`, or `"data"`.
- `mimeTypes`: (optional) List of supported MIME types for this field (e.g., `["application/json"]`).
- `schema`: (optional) A JSON schema describing the expected structure for `"data"` fields.
- `description`: (optional) Human-readable description of the field.
- `optional`: (optional) Whether this field is optional (`True` or `False`).


## Agent Card

The **Agent Card** is a JSON document that an A2A Server makes available, typically at a `.well-known/agent.json` endpoint. It's like a digital business card for the agent.
Expand Down
4 changes: 4 additions & 0 deletions specification/grpc/a2a.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -435,6 +435,10 @@ message AgentSkill {
repeated string input_modes = 6;
// Possible output modalities produced
repeated string output_modes = 7;
// Structured input fields expected by this skill.
repeated FieldDefinition input_fields = 8;
// Structured output fields produced by this skill.
repeated FieldDefinition output_fields = 9;
}

message TaskPushNotificationConfig {
Expand Down
53 changes: 53 additions & 0 deletions specification/json/a2a.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -323,6 +323,13 @@
"description": "Unique identifier for the agent's skill.",
"type": "string"
},
"inputFields": {
"description": "Structured input fields expected by this skill.",
"items": {
"$ref": "#/definitions/FieldDefinition"
},
"type": "array"
},
"inputModes": {
"description": "The set of interaction modes that the skill supports\n(if different than the default).\nSupported media types for input.",
"items": {
Expand All @@ -334,6 +341,13 @@
"description": "Human readable name of the skill.",
"type": "string"
},
"outputFields": {
"description": "Structured output fields produced by this skill.",
"items": {
"$ref": "#/definitions/FieldDefinition"
},
"type": "array"
},
"outputModes": {
"description": "Supported media types for output.",
"items": {
Expand Down Expand Up @@ -666,6 +680,45 @@
],
"type": "object"
},
"FieldDefinition": {
"description": "Describes an expected input or output field for an agent skill.",
"properties": {
"description": {
"description": "Optional description of the field.",
"type": "string"
},
"kind": {
"description": "The kind of content for this field: text, file, or data.",
"enum": [
"data",
"file",
"text"
],
"type": "string"
},
"mimeTypes": {
"description": "Optional list of supported mime types for this field.",
"items": {
"type": "string"
},
"type": "array"
},
"name": {
"description": "Optional name of the field.",
"type": "string"
},
"optional": {
"description": "Whether this field is optional.",
"type": "boolean"
},
"schema": {
"additionalProperties": {},
"description": "Optional schema for data parts (structured data).",
"type": "object"
}
},
"type": "object"
},
"FileBase": {
"description": "Represents the base entity for FileParts",
"properties": {
Expand Down
28 changes: 28 additions & 0 deletions types/src/types.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,6 +48,26 @@ export interface AgentExtension {
}
// --8<-- [end:AgentExtension]

// --8<-- [start:FieldDefinition]
/**
* Describes an expected input or output field for an agent skill.
*/
export interface FieldDefinition {
/** Optional name of the field. */
name?: string;
/** The kind of content for this field: text, file, or data. */
kind?: "text" | "file" | "data";
/** Optional list of supported mime types for this field. */
mimeTypes?: string[];
/** Optional schema for data parts (structured data). */
schema?: { [key: string]: any };
/** Optional description of the field. */
description?: string;
/** Whether this field is optional. */
optional?: boolean;
}
// --8<-- [end:FieldDefinition]

// --8<-- [start:AgentSkill]
/**
* Represents a unit of capability that an agent can perform.
Expand Down Expand Up @@ -81,6 +101,14 @@ export interface AgentSkill {
inputModes?: string[];
/** Supported media types for output. */
outputModes?: string[];
/**
* Structured input fields expected by this skill.
*/
inputFields?: FieldDefinition[];
/**
* Structured output fields produced by this skill.
*/
outputFields?: FieldDefinition[];
}
// --8<-- [end:AgentSkill]

Expand Down