Skip to main content
A reference of the agents.json schema, providing context and explanations for each element. This reference can be used by implementers and consumers (including LLMs and developers) to better understand how to configure and use agents.json in a workflow. 
{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "description": "This schema uses key words such as \"MUST\", \"MUST NOT\", \"REQUIRED\", \"SHALL\", \"SHALL NOT\", \"SHOULD\", \"SHOULD NOT\", \"RECOMMENDED\", and \"OPTIONAL\" as defined in [RFC 2119](https://tools.ietf.org/html/rfc2119) and [RFC 8174](https://tools.ietf.org/html/rfc8174) to indicate requirement levels.",
    "type": "object",
    "required": ["agentsJson", "info", "sources", "flows"],
    "properties": {
        "agentsJson": {
            "type": "string",
            "description": "MUST specify the version of the `agents.json` specification being used. Adheres to Semantic Versioning (SemVer) as outlined at [https://semver.org/](https://semver.org/)."
        },
        "info": {
            "type": "object",
            "required": ["title", "version", "description"],
            "properties": {
                "title": {
                    "type": "string",
                    "description": "MUST provide the title of the `agents.json` specification file. This title serves as a human-readable name for the specification file."
                },
                "version": {
                    "type": "string",
                    "description": "MUST follow the Semantic Versioning (SemVer) format as defined in [https://semver.org/](https://semver.org/). This version identifier ensures strict version control and compatibility management."
                },
                "description": {
                    "type": "string",
                    "description": "MUST include a comprehensive description of the `agents.json` specification file. This description should outline its purpose, functionality, and key features, facilitating understanding and implementation by users and Large Language Models (LLMs)."
                }
            },
            "additionalProperties": true
        },
        "sources": {
            "type": "array",
            "description": "MUST include an array of API sources available for use within flows. Each source references an OpenAPI 3+ specification, enabling the chaining of multiple APIs.",
            "items": {
                "type": "object",
                "required": ["id", "path"],
                "properties": {
                    "id": {
                        "type": "string",
                        "description": "MUST provide a unique, human-readable identifier for the API source. Identifiers MUST be in snake_case format and globally unique within the `agents.json` context, ensuring clear reference and invocation. **Example**: `user_service`"
                    },
                    "path": {
                        "type": "string",
                        "description": "MUST specify the file path or URL to the OpenAPI 3+ specification of the API source. The path SHOULD follow a structured format using dot notation and array indices where necessary (e.g., `components.schemas.User`)."
                    }
                },
                "additionalProperties": true
            }
        },
        "overrides": {
            "type": "array",
            "description": "OPTIONAL. An array of overrides that allow customization of specific API operations. Overrides can modify fields within operations based on the specified `fieldPath`, enabling tailored behavior without altering the original API definitions.",
            "items": {
                "type": "object",
                "required": ["sourceId", "operationId", "fieldPath", "value"],
                "properties": {
                    "sourceId": {
                        "type": "string",
                        "description": "MUST correspond to an `id` in the `sources` array. This ensures the override targets a valid API source."
                    },
                    "operationId": {
                        "type": "string",
                        "description": "MUST match an `operationId` in the referenced OpenAPI specification. This ensures accurate targeting of the operation to be overridden."
                    },
                    "fieldPath": {
                        "type": "string",
                        "description": "MUST be a JSON path expression that specifies the exact field within the operation to modify. The path SHOULD traverse the OpenAPI operation hierarchy using dot notation and array indices (e.g., `parameters.0.required`), treating the OpenAPI operation as the root."
                    },
                    "value": {
                        "oneOf": [
                            { "type": "string" },
                            { "type": "object" },
                            { "type": "array" },
                            { "type": "boolean" },
                            { "type": "integer" },
                            { "type": "number" }
                        ],
                        "description": "MUST assign a new value to the specified field. Supports multiple data types to allow for flexible and comprehensive overrides of operation fields."
                    }
                },
                "additionalProperties": true
            }
        },
        "flows": {
            "type": "array",
            "description": "MUST include an array of flows that define sequences of API operations to be executed. Each flow represents a cohesive workflow involving multiple actions, data links, and user interactions.",
            "items": {
                "type": "object",
                "required": ["id", "title", "description", "actions", "fields"],
                "properties": {
                    "id": {
                        "type": "string",
                        "description": "MUST provide a unique, human-readable identifier for the flow. Identifiers MUST be in snake_case format and globally unique within the `agents.json` context, ensuring clear reference and invocation. **Example**: `process_order_flow`"
                    },
                    "title": {
                        "type": "string",
                        "description": "MUST provide the title of the flow. This title serves as a human-readable name for the flow, facilitating easy identification and selection."
                    },
                    "description": {
                        "type": "string",
                        "description": "MUST include a detailed description of the flow. This description should explain its purpose, the sequence of operations it performs, and its overall functionality. Essential for LLMs to determine the appropriate flow to execute based on user intent."
                    },
                    "actions": {
                        "type": "array",
                        "description": "MUST include an array of actions that define the API operations to be executed in the flow. Each action corresponds to a specific API operation from a defined source, orchestrating the overall workflow.",
                        "items": {
                            "type": "object",
                            "required": ["id", "sourceId", "operationId"],
                            "properties": {
                                "id": {
                                    "type": "string",
                                    "description": "MUST provide a unique, human-readable identifier for the action within the flow. Identifiers MUST be in snake_case format and unique within the flow, enabling precise reference in links. **Example**: `validate_payment`"
                                },
                                "sourceId": {
                                    "type": "string",
                                    "description": "MUST reference the `id` of an API source defined in the `sources` array. Indicates which API the action is associated with, ensuring correct operation execution."
                                },
                                "operationId": {
                                    "type": "string",
                                    "description": "MUST identify the specific operation within the API source to execute. Must match an `operationId` in the referenced OpenAPI specification, ensuring accurate and intended operation invocation."
                                }
                            },
                            "additionalProperties": true
                        }
                    },
                    "links": {
                        "type": "array",
                        "description": "MUST include an array of links that define how data flows between sources and destinations within the flow. Links connect data providers to data consumers, ensuring accurate data transfer.",
                        "items": {
                            "type": "object",
                            "required": ["origin", "target"],
                            "properties": {
                                "origin": {
                                    "type": "object",
                                    "required": ["fieldPath", "actionId"],
                                    "properties": {
                                        "actionId": {
                                            "type": ["string", "null"],
                                            "description": "REQUIRED. The identifier of the action or flow providing the data. If the data is coming from this flow at the top level, the value should be this flow's `id`."
                                        },
                                        "fieldPath": {
                                            "type": "string",
                                            "description": "MUST be a JSON path expression specifying the source field from which to extract data. The path SHOULD traverse the OpenAPI operation hierarchy using dot notation and array indices (e.g., `response.data.items.0.name`), treating the OpenAPI operation as the root."
                                        }
                                    },
                                    "description": "MUST specify the data origin for the link, which can be an action's response or the flow's input parameters."
                                },
                                "target": {
                                    "type": "object",
                                    "required": ["fieldPath", "actionId"],
                                    "properties": {
                                        "actionId": {
                                            "type": ["string"],
                                            "description": "REQUIRED. The identifier of the action or flow receiving the data. If the data is going to this flow at the top level, the value should be this flow's `id`."
                                        },
                                        "fieldPath": {
                                            "type": "string",
                                            "description": "MUST be a JSON path expression specifying the destination field where the data should be placed. The path SHOULD traverse the OpenAPI operation hierarchy using dot notation and array indices (e.g., `parameters.userId`), treating the OpenAPI operation as the root."
                                        }
                                    },
                                    "description": "MUST specify the destination location for the mapped data, targeting an action's parameters or the flow's response fields."
                                }
                            },
                            "additionalProperties": false
                        }
                    },
                    "fields": {
                        "type": "object",
                        "description": "MUST define the parameters, request body, and responses for the flow. These fields serve as the interface for interaction with the flow, ensuring structured and clear data handling.",
                        "required": ["parameters", "responses"],
                        "properties": {
                            "parameters": {
                                "type": "array",
                                "description": "MUST include an array of parameters that define the inputs required or accepted by the flow. These parameters serve as the interface for user-provided data, enabling dynamic and flexible flow interactions.",
                                "items": {
                                    "type": "object",
                                    "required": ["name"],
                                    "properties": {
                                        "name": {
                                            "type": "string",
                                            "description": "MUST provide the name of the parameter. This name is used to reference the parameter in links and user interactions, ensuring consistency and clarity."
                                        },
                                        "description": {
                                            "type": "string",
                                            "description": "OPTIONAL. A detailed description of the parameter, explaining its purpose, usage, and any constraints. This aids users in understanding what is expected when providing input."
                                        },
                                        "required": {
                                            "type": "boolean",
                                            "description": "OPTIONAL. Indicates whether the parameter is mandatory (`true`) or optional (`false`) when invoking the flow.",
                                            "default": false
                                        },
                                        "type": {
                                            "type": "string",
                                            "description": "The type of the parameter. This can be a primitive type (e.g., `string`, `number`, `boolean`, `array`, `object`) or a complex type (e.g., `array`, `object`). If not provided, the type is inferred from the context."
                                        }
                                    },
                                    "additionalProperties": false,
                                    "description": "Defines a parameter that users must or can provide when invoking the flow. Parameters are used to input data into the flow, enabling interaction and customization."
                                }
                            },
                            "requestBody": {
                                "type": "object",
                                "description": "OPTIONAL. Describes the structure of the request payload that the flow expects. Aligns with OpenAPI's `requestBody` specification as per [RFC 7231](https://tools.ietf.org/html/rfc7231), ensuring standardized data formats and communication.",
                                "properties": {
                                    "content": {
                                        "type": "object",
                                        "description": "MUST include a map of MIME types to their corresponding schemas defining the request body. Each key MUST conform to the media type format as per [RFC 7231](https://tools.ietf.org/html/rfc7231), enabling content negotiation and proper data handling.",
                                        "additionalProperties": {
                                            "type": "object",
                                            "properties": {
                                                "schema": {
                                                    "type": "object",
                                                    "description": "MUST provide the schema defining the structure of the request body for the specified MIME type. Follows JSON Schema specifications as per [RFC 7159](https://tools.ietf.org/html/rfc7159), enabling precise data validation and formatting."
                                                },
                                                "example": {
                                                    "type": "object",
                                                    "description": "OPTIONAL. An example of the request body content for the specified MIME type. Provides practical illustrations of expected data formats and structures."
                                                }
                                            },
                                            "additionalProperties": false
                                        }
                                    },
                                    "required": {
                                        "type": "boolean",
                                        "description": "OPTIONAL. Specifies whether the request body is required (`true`) or optional (`false`) for the flow.",
                                        "default": false
                                    }
                                },
                                "additionalProperties": false
                            },
                            "responses": {
                                "type": "object",
                                "description": "MUST be an object where that contains a `success` property that describes the response for a successful operation.",
                                "required": ["success"],
                                "properties": {
                                    "success": {
                                        "type": "object",
                                        "description": "MUST provide the schema defining the structure of the response body for the specified MIME type. Follows JSON Schema specifications as per [RFC 7159](https://tools.ietf.org/html/rfc7159), enabling accurate data validation and formatting."
                                    },
                                    "example": {
                                        "type": "object",
                                        "description": "OPTIONAL. An example of the response body content for the specified MIME type. Provides practical illustrations of expected data formats and structures."
                                    }
                                },
                                "additionalProperties": false
                            }
                        },
                        "additionalProperties": true
                    },
                    "additionalProperties": true
                }
            }
        },
        "additionalProperties": true
    }
}

​
Overview

The schema defines a JSON-based configuration known as agents.json. The file contains:
  1. A specification version
  2. Info object describing title, version, and description
  3. A list of API sources (“sources”)
  4. Optional overrides to modify specific fields in any source operation
  5. A set of flows, each representing a chain of API calls and data mappings
Use this schema to create cohesive, multi-step workflows that orchestrate API calls, perform data transformations, and manage input/output parameters in a standardized, documented manner.

​
Top-Level Structure

The agents.json schema is an object with the following required properties:
  • agentsJson
  • info
  • sources
  • flows
Additionally, it may include optional overrides and other properties as needed.

​
1. agentsJson

Example: 
{
  "agentsJson": "1.0.0"
}

​
2. info

  • Type: object
  • Required Properties:
    • title (string)
    • version (string)
    • description (string)
  • Description: Basic metadata for the agents.json file.

​
Properties

  • info.title
    • Type: string
    • Description: The full name or headline of this agents.json specification
  • info.version
  • info.description
    • Type: string
    • Description: High-level summary or explanation of what this agents.json file accomplishes
Example: 
{
  "info": {
    "title": "Order Processing Agent",
    "version": "1.0.0",
    "description": "A set of flows for handling order submissions and payment validations."
  }
}

​
3. sources

  • Type: array
  • Description: An array declaring external API specifications. Each source references an OpenAPI 3+ spec to allow chaining multiple APIs.
  • Required Properties (per item):
    • id (string)
    • path (string)

​
Properties

  • source.id
    • Type: string
    • Description: A unique, human-readable identifier in snake_case. Used to reference the source from flows or overrides.
  • source.path
    • Type: string
    • Description: The file path or URL to the OpenAPI specification for this source.
Example: 
{
  "sources": [
    {
      "id": "user_service",
      "path": "openapi/user_service.yaml"
    },
    {
      "id": "payment_gateway", 
      "path": "openapi/payment_api.yaml"
    }
  ]
}

​
4. overrides (Optional)

  • Type: array
  • Description: An optional array of objects allowing you to override or customize specific fields in any API operation.
  • Required Properties (per override):
    • sourceId (string)
    • operationId (string)
    • fieldPath (string)
    • value (string | object | array | boolean | integer | number)
Example: 
{
  "overrides": [
    {
      "sourceId": "payment_gateway",
      "operationId": "processPayment",
      "fieldPath": "parameters.0.required",
      "value": true
    }
  ]
}

​
5. flows

  • Type: array
  • Description: Each item in flows defines a workflow that consists of multiple API calls (“actions”) and data links between them.
  • Required Properties (per flow):
    • id (string)
    • title (string)
    • description (string)
    • actions (array)
    • fields (object)

​
5.1 Flow Identification

  1. flow.id
    • Type: string
    • Description: A unique identifier in snake_case for referencing the flow
  2. flow.title
    • Type: string
    • Description: A short, human-readable title for the flow
  3. flow.description
    • Type: string
    • Description: Explains the purpose, sequence, and expected outcome of the flow
Example: 
{
  "flows": [
    {
      "id": "process_order_flow",
      "title": "Process Order Flow",
      "description": "Handles all steps from order creation to payment confirmation.",
      "...": "..."
    }
  ]
}

​
5.2 actions

  • Type: array
  • Required Properties (per action):
    • id (string)
    • sourceId (string)
    • operationId (string)
  • Description: Each action corresponds to an API call within a flow.
Example: 
"actions": [
  {
    "id": "create_order",
    "sourceId": "user_service",
    "operationId": "createOrder"
  },
  {
    "id": "charge_card",
    "sourceId": "payment_gateway",
    "operationId": "chargeCreditCard"
  }
]
  • Type: array
  • Description: Describes how data should flow between actions or from the flow’s inputs to any action parameters.
  • Required Properties (per link):
    • origin (object)
    • target (object)
Properties
  • origin
    • Must contain:
      • actionId (string or null)
      • fieldPath (string; JSON path expression)
  • target
    • Must contain:
      • actionId (string)
      • fieldPath (string; JSON path expression)
Example: 
{
  "origin": {
    "actionId": "create_order",
    "fieldPath": "response.data.orderId"
  },
  "target": {
    "actionId": "charge_card",
    "fieldPath": "parameters.orderId"
  }
}

​
5.4 fields

  • Type: object
  • Description: Describes the interface for a flow, including its parameters, optional requestBody, and responses.
5.4.1 fields.parameters
  • Type: array
  • Description: Defines the input parameters for the flow.
Example: 
"parameters": [
  {
    "name": "customer_id",
    "description": "The ID of the customer placing the order",
    "required": true,
    "type": "string"
  }
]
5.4.2 fields.requestBody (Optional)
  • Type: object
  • Description: Specifies the schema for the request body if required.
  • Keys:
    • content (object): A map of MIME type to an object with “schema” and optional “example”
    • required (boolean): Whether this request body is mandatory
Example: 
"requestBody": {
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "items": { "type": "array" }
        }
      },
      "example": {
        "items": ["item1", "item2"]
      }
    }
  },
  "required": true
}
5.4.3 fields.responses
  • Type: object
  • Required: success (object)
  • Description: Contains the schema that describes the successful flow’s output.
Example: 
"responses": {
  "success": {
    "type": "object",
    "properties": {
      "orderId": { "type": "string" }
    }
  },
  "example": {
    "orderId": "abc123"
  }
}

​
Practical Example

Let’s look at a complete example that demonstrates how these components work together. This example shows an agents.json implementation for a weather service that chains together location and weather APIs: 
{
  "agentsJson": "1.0.0",
  "info": {
    "title": "Weather Service Agent",
    "version": "1.0.0",
    "description": "Fetches weather data based on user location"
  },
  "sources": [
    {
      "id": "locationAPI",
      "path": "openapi/location_service.yaml"
    },
    {
      "id": "weatherAPI",
      "path": "openapi/weather_service.yaml"
    }
  ],
  "flows": [
    {
      "id": "get_weather_flow",
      "title": "Fetch Weather Based on Location",
      "description": "Gets the current weather using the user's location.",
      "actions": [
        {
          "id": "getLocation",
          "sourceId": "locationAPI",
          "operationId": "getUserLocation"
        },
        {
          "id": "getWeather",
          "sourceId": "weatherAPI",
          "operationId": "getCurrentWeather"
        }
      ],
      "links": [
        {
          "origin": {
            "actionId": "getLocation",
            "fieldPath": "response.latitude"
          },
          "target": {
            "actionId": "getWeather",
            "fieldPath": "parameters.lat"
          }
        },
        {
          "origin": {
            "actionId": "getLocation",
            "fieldPath": "response.longitude"
          },
          "target": {
            "actionId": "getWeather",
            "fieldPath": "parameters.lon"
          }
        }
      ],
      "fields": {
        "parameters": [
          {
            "name": "lat",
            "description": "Latitude for weather data",
            "type": "number",
            "required": true
          },
          {
            "name": "lon",
            "description": "Longitude for weather data",
            "type": "number",
            "required": true
          }
        ],
        "responses": {
          "success": {
            "type": "object",
            "properties": {
              "temperature": { "type": "number" },
              "conditions": { "type": "string" }
            }
          }
        }
      }
    }
  ]
}
This example demonstrates several key concepts:
  1. API Chaining: The flow connects two different APIs (location and weather) in sequence
  2. Data Mapping: The links section shows how data from the first API call (latitude/longitude) flows into the second API call
  3. Parameter Definition: The fields.parameters section defines the expected input format
  4. Response Schema: The fields.responses section specifies the structure of the successful response
  5. Clear Identification: Each component (flows, actions, sources) has clear, descriptive IDs and titles

​
Summary

An agents.json file adhering to this schema enables a detailed definition of your orchestration logic. It supports:
  • Strict versioning via agentsJson
  • Clear metadata via info
  • Reusable API sources via sources
  • Fine-grained customization via overrides
  • Configurable workflows (flows), which contain:
    • Actions to invoke APIs
    • Links to bind data between steps
    • Fields to define input parameters, optional request bodies, and expected response schemas
For the full schema specification, please refer to our GitHub repository.
⌘I