> ## Documentation Index > Fetch the complete documentation index at: https://wildcard.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Schema Reference > The complete agents.json schema specification 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 * **Type**: string * **Description**: Specifies the version of the `agents.json` schema being used. Must follow [Semantic Versioning (SemVer)](https://semver.org/). Example: ```json theme={null} { "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** * Type: string * Description: Must follow [Semantic Versioning (SemVer)](https://semver.org) * **info.description** * Type: string * Description: High-level summary or explanation of what this `agents.json` file accomplishes Example: ```json theme={null} { "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: ```json theme={null} { "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: ```json theme={null} { "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: ```json theme={null} { "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: ```json theme={null} "actions": [ { "id": "create_order", "sourceId": "user_service", "operationId": "createOrder" }, { "id": "charge_card", "sourceId": "payment_gateway", "operationId": "chargeCreditCard" } ] ``` #### 5.3 links * **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: ```json theme={null} { "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: ```json theme={null} "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: ```json theme={null} "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: ```json theme={null} "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: ```json theme={null} { "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.