Agent Network (2.0) YAML Reference

name

Human-readable name for the agent.

string

Yes

 — 

description

Human-readable description of the agent’s purpose.

string

Yes

 — 

url

Preferred endpoint URL for interacting with the agent. Must support preferredTransport.

string

Yes

for example, https://api.example.com/a2a/v1

version

Agent’s own version number (format defined by provider).

String

Yes

for example, 1.0.0

protocolVersion

Version of the A2A protocol this agent supports.

String

Yes

for example, 1.0

capabilities

Optional capabilities supported by the agent.

AgentCapabilities

Yes

See below

defaultInputModes

Default supported input MIME types for all skills (overridable per skill).

Array of string

Yes

 — 

defaultOutputModes

Default supported output MIME types for all skills (overridable per skill).

Array of string

Yes

 — 

skills

The set of skills or distinct capabilities the agent can perform.

Array of AgentSkills

Yes

See below

preferredTransport

Transport for the main url. Must be available at that URL.

String

No

JSON-RPC, GRPC, HTTP JSON (default: JSON-RPC)

additionalInterfaces

Additional transport+URL combinations for the same agent.

Array of AgentInterface

No

Each: { transport: string, url: string }

additionalInterfaces.transport

The transport protocol for this interface.

String

Yes

JSONRPC, GRPC, HTTP+JSON)

additionalInterfaces.url

The URL for this additional interface.

String (URI)

Yes

Valid URI string

provider

Agent’s service provider.

AgentProvider

No

{ organization: string, url: string }

documentationUrl

Optional URL to the agent’s documentation.

String

No

 — 

iconUrl

Optional URL to an icon for the agent.

String

No

 — 

security

Security requirement objects for all interactions (OpenAPI 3.0 style; OR of ANDs).

Array of object

No

Each object: scheme names → array of scope strings

securitySchemes

Declared security schemes (key \= scheme name). OpenAPI 3.0 Security Scheme Object.

Object

No

apiKey, http, oauth2, openIdConnect, mutualTLS

signatures

JSON Web Signatures for this AgentCard (RFC 7515 JWS).

Array of AgentCardSignature

No

{ protected, signature, header? }

kind

Connection type

mcp, a2a, or llm

Yes

ref

A reference to an asset representing the target system.

Reference Object

Yes

url

The base URL of the target system.

String

No

authentication

The authentication method to use when connecting to the target system.

Authentication Object

No (Yes for llm connections)

policies

Policy bindings to apply to this connection, organized by traffic direction.

Object

No

policies.inbound

Policy bindings applied to inbound traffic.

Array

No

policies.outbound

Policy bindings applied to outbound traffic.

Array

No

kind

The authentication method type.

String

basic

Yes

username

Username for authentication.

String

String

Yes

password

Password for authentication.

String

String

Yes

headerName

The name of the HTTP used for basic credentials. If not specified, Authorization is used.

String

String. Defaults to Authorization.

No

kind

The authentication method type.

String

apiKey

Yes

headerName

The name of the HTTP header that carries the API key. If not specified, Authorization is used.

String

String. Defaults to Authorization.

No

apiKey

The header or parameter name for the API key.

String

String

No

kind

The authentication method type.

String

apikey-client-credentials

Yes

clientId

Description of the client ID to be used.

Object

Object with value and optional name (default header name is client_id).

Yes

clientId.value

The value for the client ID.

String

String

Yes

clientId.name

The header or parameter name.

String

String

No

clientSecret

Description of the client secret to be used.

Object

Object with value and optional name (default header name is client_secret).

No

clientSecret.value

The value for the client secret.

String

String

Yes

clientSecret.name

The header or parameter name.

String

String

No

kind

The authentication method type.

String

oauth2-client-credentials

Yes

clientId

The client ID to authenticate with the OAuth2 provider.

String

String

Yes

clientSecret

The client secret used with client ID.

String

String

Yes

token

Configuration for how to fetch the token.

Object

Token object

Yes

token.url

The URL of the token provider (token endpoint).

String

Valid URL string

Yes

token.timeout

Time in seconds to wait for the token service to respond.

Number

Any number

No

token.bodyEncoding

Content encoding for the request body. (form = application/x-www-form-urlencoded, json = application/json)

String

form or json

No

scopes

Array of scopes to request during token retrieval.

Array

Array of scope strings. Defaults to []

No

kind

Authentication type.

String

in-task-authorization-code

Yes

authorizationEndpoint

OAuth2 authorization endpoint URL. Used to generate the authentication challenge.

String

Valid URL

Yes

tokenEndpoint

OAuth2 token endpoint URL. Used to generate the authentication challenge.

String

Valid URL

Yes

scopes

OAuth2 scopes required for step-up authentication.

String

Space- or comma-separated scope list (for example, openid profile email)

Yes

redirectUri

OAuth2 redirect URI the client uses in the authorization flow.

String

Valid URI

Yes

secondaryAuthProvider

Name of the IdP (for example, okta, auth0). Informational only, for the authentication card.

String

Any string

No

responseType

OAuth2 response type.

String

Typically code. Default: code

No

codeChallengeMethod

PKCE code challenge method.

String

Typically S256. Default: S256

No

tokenAudience

Intended recipient of the token (for example, agent1 or API URL).

String

Any string

No

bodyEncoding

Encoding for the token request body.

String

form, json. Default: form

No

tokenTimeout

Timeout in seconds for token requests.

Integer

Positive integer. Default: 300

No

challengeResponseStatusCode

HTTP status code returned for auth-required challenge responses. Typically 200 for JSON-RPC compatibility.

Integer

HTTP status code. Default: 200

No

distributed

Share token cache across replicas. Required for fully managed gateway or any multi-replica deployment.

Boolean

true or false. Default: false

No

subjectTokenType

The token type identifier for the subject token.

String

Default: urn:ietf:params:oauth:token-type:access_token

No

requestedTokenType

The desired token type for the issued token.

String

Any string

No

kind

Authentication type.

String

oauth2-obo

Yes

flow

Token exchange flow type.

String

oauth2-token-exchange, microsoft-entra-obo

Yes

clientId

OAuth2 client ID for token exchange.

String

String

Yes

clientSecret

OAuth2 client secret for token exchange.

String

String

Yes

tokenEndpoint

OAuth2 token endpoint URL for token exchange.

String

Valid URL

Yes

targetType

Parameter type for specifying the target service (audience for logical name, resource for physical URI). Used for OAuth 2.0 Token Exchange.

String

audience, resource. Default: audience

No

targetValue

Target audience URI or resource URI for the exchanged token. Required for OAuth 2.0 Token Exchange.

String

Valid URI

Required when using oauth2-token-exchange with a target

scope

OAuth scope to request. Required for Microsoft Entra OBO (for example, api://downstream-client-id/.default). Optional for OAuth 2.0 Token Exchange.

String

String

Required for microsoft-entra-obo

timeout

Timeout for token exchange requests in milliseconds.

Integer

Positive integer. Default: 10000

No

cibaEnabled

When true, it uses Client Initiated Backchannel Authentication (CIBA) instead of standard OBO token exchange. Only valid when flow is oauth2-token-exchange.

Boolean

true or false. Default: false

No

cibaEndpoint

Backchannel authorization (bc-authorize) endpoint URL for CIBA.

String

Valid URL

No

cibaLoginHintClaim

JWT claim from the subject token to send as the CIBA login_hint (for example, email, sub).

String

String. Default: email

No

cibaBindingMessage

Optional message shown on the user’s authentication device during CIBA approval.

String

String

No

distributed

Share token cache across replicas. Required for fully managed gateway or any multi-replica deployment.

Boolean

true or false. Default: false

No

ref.name

Name of the declared policy binding. See Policies.

String

Yes

policy

The policy to be applied.

Object

Yes

policy.ref

Reference to the policy definition.

PolicyRef See Policies.

Yes

policy.configuration

Policy-specific configuration.

Object

Yes

MODULE_GRAPH_ERROR_SETTINGS_MAX_HANDOFF_ITERATIONS

Maximum number of node-to-node transitions allowed per turn. Controls how many times execution can move between nodes in the agent network graph during a single conversation turn.

30

MODULE_GRAPH_ERROR_SETTINGS_MAX_REASONING_ITERATIONS

Maximum number of LLM reasoning loops allowed within a single node. Limits how many times the LLM can iterate on its reasoning before producing a result.

20

MODULE_GRAPH_ERROR_SETTINGS_MAX_SUBGRAPH_DEPTH

Maximum nesting depth for subgraphs. Controls how deeply agent networks can be nested within other agent networks.

10

MODULE_GRAPH_ERROR_SETTINGS_MAX_NODE_TOOL_CALL_ITERATIONS

Maximum number of tool executor runs allowed per node. Limits how many times a node can invoke tool execution during its processing.

20

MODULE_GRAPH_ERROR_SETTINGS_MAX_TURN_TOOL_CALL_COUNTS

Total number of tool invocations allowed across all nodes per turn. Provides a global limit on tool usage during a single conversation turn.

50

MODULE_GRAPH_ERROR_SETTINGS_MAX_STATE_SIZE_BYTES

Maximum accumulated state size in bytes. Limits the total amount of state data that can be accumulated during graph execution. Default is 10 MB (10485760 bytes).

10485760