]>

gaikwad.madhav@gmail.com

Applications and Real-Time Independent Submission This document defines the Web of Agents (WoA), a minimal JSON based description format and invocation convention that allows HTTP hosts to advertise AI agents and for clients to invoke those agents in a uniform way. A WoA document is typically served from a well known location on an HTTP origin and uses JSON Schema to describe agent inputs and outputs. WoA does not define a discovery protocol itself but is designed to be used as a host level primitive by higher level discovery systems.

Introduction AI agents are increasingly exposed as network reachable services, such as text based large language model interfaces, task specific tools, and composite workflows that call other services. Today these agents are typically documented using ad hoc JSON documents or provider specific formats. This makes it difficult for generic clients to discover which agents exist on a given origin and to invoke them in a predictable way. The Web of Agents (WoA) defines:

• a JSON based document format, usually served from a well known path on an origin, that lists agents and their properties
• a JSON Schema based description of agent inputs and outputs
• a small set of transport configuration objects that define how a client constructs an invocation request
• a simple invocation envelope used by some transports

WoA is intentionally small in scope. It does not attempt to define a global discovery system or a capability vocabulary. It is designed to complement such systems by providing a host level primitive that discovery mechanisms can fetch, cache, and index. For example, a cross platform discovery system such as could use WoA documents as one of its inputs when building a search index. This document is targeted at the Independent Submission Stream with category "exp". The intent is to provide a concrete and implementable format that can be experimented with by client and host implementers.

Conventions and Terminology The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here. This document uses the JSON data model defined in and HTTP terminology from .

Terms

WoA document

A JSON document served by an HTTP origin that describes one or more agents and their transport configurations according to this specification.

Agent

A logical AI powered capability exposed by a host. An agent has an identifier, a human readable name and description, a JSON Schema based input and output description, and one or more transport options that describe how to invoke it.

Host

An HTTP origin that serves a WoA document and optionally implements one or more transports for agents described in that document.

WoA Client

A component that retrieves the WoA document and invokes agents. A WoA client may be a user facing application, an orchestration engine, or another independent agent, enabling agent to agent (A2A) interactions.

Transport

A named mechanism that defines how a client constructs and sends an invocation request. This document defines the "rest" and "mcp" transports. Additional transports may be registered in the WoA Transport Registry.

Architecture A typical deployment has an HTTP origin that serves a WoA document at a well known path, and one or more transports that accept invocation requests.

High Level WoA Architecture | | | Client | | Host | | | <--------------------------------------- | | +-----------+ 200 application/woa+json +-----------+ | | Select agent and transport v +-----------+ HTTP POST (REST transport) +-----------+ | | ---------------------------------------> | | | Client | | Host | | | <--------------------------------------- | | +-----------+ JSON response +-----------+ ]]>

A client fetches the WoA document from a host, selects an agent, chooses a transport supported by both client and host, constructs an invocation request according to the transport rules, and processes the response. Higher level discovery systems may crawl or index WoA documents but are out of scope for this specification.

WoA Document Schema A WoA document is a single JSON object with the following top level fields:

• woa_version: A string identifying the WoA document version. For this specification the value MUST be the string "1".
• agents: An array of agent objects as defined in .
• transports: An object whose keys are transport names and whose values are transport configuration objects as defined in .

Agent Objects Each element of the agents array is an object with the following fields:

• id (string, REQUIRED): A token that uniquely identifies the agent within the WoA document. The value MUST match the following ABNF (using ):

agent-id = 1*( ALPHA / DIGIT / "-" / "_" )

• name (string, REQUIRED): A short, human readable name for the agent.
• description (string, REQUIRED): A human readable description of what the agent does. Clients MUST treat this field as untrusted input for security reasons (see ).
• version (string, OPTIONAL): A version identifier for the agent implementation, such as "1.0.0".
• capabilities (array of strings, OPTIONAL): A list of capability identifiers. This specification does not define a controlled vocabulary. Implementations MAY use URIs (for example, "https://example.com/capability/summarization") or URN like identifiers as long as they are stable.
• inputs (object, REQUIRED): A JSON Schema document that describes the expected request body when invoking the agent. See .
• outputs (object, REQUIRED): A JSON Schema document that describes the successful response body produced by the agent.
• transports (array of strings, REQUIRED): Names of transport configurations (keys in the top level transports object) that can be used to invoke this agent.
• operations (array of objects, OPTIONAL): A list of operation descriptors for agents that support multiple logical operations via a single transport endpoint. If operations is not present, the agent is considered to have a single unnamed operation.

Each operation object in the operations array has:

• name (string, REQUIRED): A token naming the operation.
• description (string, REQUIRED): Human readable description of the operation.
• inputs (object, OPTIONAL): JSON Schema overriding the agent level inputs for this operation.
• outputs (object, OPTIONAL): JSON Schema overriding the agent level outputs for this operation.

Clients MUST NOT assume that two agents with the same id on different origins have the same behavior or schema.

JSON Schema Usage for Inputs and Outputs The inputs, outputs, and any operation level inputs or outputs fields MUST be valid JSON Schema documents compliant with the JSON Schema 2020-12 core and validation specifications . At minimum, implementations MUST support JSON Schema documents whose root is an object with:

• a type of "object"
• a properties object describing named properties
• an optional required array naming required properties

More advanced JSON Schema features such as oneOf, allOf, and format MAY be used by hosts and SHOULD be ignored by clients that do not understand them, as long as the client can still construct a conforming request. Hosts SHOULD provide concise and accurate JSON Schema documents to enable static validation and tooling. Clients MAY validate request bodies locally against the inputs schema before sending them and MAY validate successful responses against the outputs schema.

Transport Configurations The top level transports object maps transport names to configuration objects. Transport names are strings. This document defines the rest and mcp transports. Additional transports MAY be defined and registered in the WoA Transport Registry (see ).

REST Transport A rest transport configuration object MUST contain:

• base (string, REQUIRED): An absolute HTTPS URL that identifies the base of the REST API. The URL scheme MUST be "https" and the server SHOULD support TLS 1.3 .
• invoke_path (string, REQUIRED): An absolute path beginning with "/" that, when combined with base, yields the invocation URL template. The path MAY contain a query component. Within the path, the case sensitive substring "{agent_id}" MAY appear as a placeholder.

To construct the invocation URL, the client concatenates the base URL and the invoke_path value. If the invoke_path contains the case sensitive substring "{agent_id}", the client MUST replace it with the target agent's id value. Clients invoking an agent via the REST transport MUST use HTTP POST and MUST send a request body encoded as JSON with media type application/json. The request body for the REST transport is defined in . Hosts using the REST transport MUST respond with JSON and SHOULD use the application/problem+json media type for errors as specified in .

MCP Transport A mcp transport configuration object describes how an agent is exposed via a Model Context Protocol (MCP) server . The configuration object MUST contain:

• server (string, REQUIRED): An identifier or URL for the MCP server endpoint. The exact format is defined by the MCP specification.
• tool_namespace (string, REQUIRED): A string that identifies the logical namespace of tools on the MCP server.
• tool_field (string, REQUIRED): The name of the field in the invocation envelope that contains the tool name for this MCP server.

When using the MCP transport, the client translates the WoA invocation envelope into the appropriate MCP tool invocation as defined by the MCP specification . For example, if tool_field is "agent", the client MAY pass the value of the envelope's agent field as the tool name.

Private Transports Hosts MAY define private transport names for experimental use. Private transport names MUST use a reverse DNS prefix, such as "com.example.mytransport", to avoid collisions with registered transports. Private transports MUST NOT be registered in the WoA Transport Registry.

Invocation This section describes the invocation envelope and how it is used with the REST and MCP transports. Other transports MAY define their own invocation rules.

Invocation Envelope When a transport uses a JSON request body that contains metadata about the invocation in addition to the agent specific input object, this document refers to that JSON object as the "invocation envelope". For the REST transport defined in this document, the invocation envelope is an object with the following fields:

• agent (string, REQUIRED): The agent identifier as listed in the WoA document.
• operation (string, OPTIONAL): The operation name, if the agent defines an operations array. If omitted for an agent that defines operations, the name "default" is RECOMMENDED as the implied operation.
• input (object, REQUIRED): A JSON object that MUST conform to the JSON Schema specified in the selected operation's inputs schema, or to the agent level inputs if there is no per operation override.

Transports MAY add additional fields to the invocation envelope as long as they do not conflict with the fields defined above.

REST Transport Invocation When using the REST transport, the client constructs the invocation URL as described in and sends an HTTP POST request with media type application/json and a request body containing the invocation envelope. The agent field in the envelope MUST match the intended agent's id. If the REST invocation URL template includes an "{agent_id}" placeholder, the host can infer the agent from the URL. In that case:

• If the host derives an agent identifier from the URL and the agent field is absent in the envelope, the host MAY use the identifier from the URL.
• If the host derives an agent identifier from the URL and the envelope contains an agent field with a different value, the host MUST reject the request with HTTP status 400 (Bad Request). The host SHOULD return a application/problem+json body explaining the mismatch.

On success, the host MUST return a 2xx status code and a JSON response body that conforms to the JSON Schema specified in the selected operation's outputs schema, or the agent level outputs schema if there is no per operation override. On error, the host SHOULD return a 4xx or 5xx status code and a response body using the problem details format defined in with media type application/problem+json. Problem type URIs and error code taxonomies are deployment specific.

MCP Transport Invocation When using the MCP transport, the client translates the invocation envelope into the appropriate MCP tool invocation. The exact mapping is defined by the MCP specification and is not repeated here. As a typical pattern, the agent or operation fields of the envelope may map to tool names and the input object may map to MCP tool arguments. WoA does not define the wire protocol for MCP and does not impose additional security requirements beyond those defined by the MCP specification. The security considerations in still apply to the host that publishes the WoA document.

Authorization WoA deliberately separates the question of "which agent exists and how can it be invoked" from "who is allowed to invoke this agent". The WoA document format does not contain access tokens and does not mandate a particular authorization protocol. Hosts MAY use OAuth 2.0 , mutual TLS, or other mechanisms to protect invocation endpoints. A host MAY include additional metadata in the WoA document to help clients understand the authorization expectations for an agent. For example, a deployment using the SOUTH stochastic authorization protocol might include an authz object with pointers to policy endpoints. Such metadata is deployment specific and out of scope for the core WoA specification.

Caching WoA documents are likely to be fetched frequently by clients and discovery systems. Hosts SHOULD include HTTP caching headers, such as ETag, Last-Modified, and appropriate Cache-Control directives, on responses that carry a WoA document to reduce unnecessary network traffic. Clients SHOULD honor these headers when polling for updates.

Security Considerations WoA is a descriptive format and does not execute code by itself, but it is used in contexts where agents may execute untrusted input or perform sensitive actions. Both hosts and clients need to consider the following security aspects.

Transport Security Hosts that serve WoA documents and implement REST transports MUST use HTTPS. The underlying TLS version SHOULD be TLS 1.3 . Clients MUST validate server certificates according to normal HTTPS rules. Plain HTTP MUST NOT be used for WoA documents or REST invocations on the open Internet.

Server Side Request Forgery and Origin Validation A malicious WoA document could advertise transport URLs that point to internal or otherwise sensitive endpoints. Automated clients that unconditionally invoke agents based on WoA documents risk being used as a vector for server side request forgery. Clients SHOULD validate that transport URLs provided in a WoA document resolve to allowed domains or IP address ranges before invoking agents. In particular, clients SHOULD NOT automatically send invocation requests to URLs that resolve to private or link local address ranges, such as those defined in , unless explicitly configured to do so by an administrator. Clients SHOULD also be cautious of HTTP redirects that change the authority component of the URL and SHOULD apply the same validation to the redirect target.

Indirect Prompt Injection The name and description fields of an agent are free form strings controlled by the host. Clients that use a large language model to reason about or select agents based on these fields MUST treat them as untrusted input. A malicious host could embed text that attempts to influence the client side model in ways that bypass user intent, a pattern sometimes referred to as indirect prompt injection. Implementers SHOULD design any agent selection logic that uses LLMs with appropriate input isolation, such as explicit system level instructions that describe which fields are trusted and which are untrusted, and with guardrails that restrict the actions that can be taken based on WoA content.

Agent Output Trust WoA itself does not provide integrity or authenticity guarantees for agent outputs. Clients SHOULD treat agent responses as untrusted data and apply appropriate validation, sandboxing, and authorization checks before using them to take actions such as executing code, issuing network requests, or changing external state.

IANA Considerations

Well Known URI Registration This document requests registration of a new well known URI suffix in the "Well Known URIs" registry as defined in . The registration template is:

Media Type Registration This document requests registration of the application/woa+json media type in the "Media Types" registry according to . The registration template is: Intended usage: COMMON Restrictions on usage: none Author: Madhava Gaikwad Change controller: IETF ]]>

WoA Transport Registry This document requests the creation of a new registry titled "WoA Transport Registry". The registry records transport names used in the top level transports object of WoA documents. Each entry in the registry has the following fields:

• Transport name: a short string identifying the transport.
• Reference: a stable specification that defines the transport.

Registration policy for the WoA Transport Registry is "Specification Required" as defined in . This document registers the following initial entries:

Normative References Informative References Anthropic

Appendix A: Example Use with SOUTH (Non-Normative) This appendix sketches how a deployment might combine WoA with the SOUTH stochastic authorization protocol . It is non-normative and does not modify the core WoA format. A host could add an authz object at the top level of the WoA document or within an agent object that points to a SOUTH policy endpoint. For example: A client that understands SOUTH could first obtain a token from the SOUTH authorization server according to and then include it as a SOUTH token in the HTTP request: The details of how SOUTH evaluates policies and issues tokens are defined in and are not repeated here.

Appendix B: Complete Example WoA Flow (Non-Normative) This appendix provides a complete example showing a WoA document, a client fetching it, invoking an agent via the REST transport, and receiving a successful response.

Example WoA Document Consider a host at https://api.example.com that serves the following WoA document at https://api.example.com/.well-known/woa.json using the application/woa+json media type.

Client Fetches WoA Document A client fetches the WoA document: The host responds: The client parses the JSON, locates the agent with id "summarizer", and notes that it supports the rest transport.

Client Invokes the Agent The client constructs the invocation URL by concatenating the base and invoke_path values and substituting "{agent_id}" with "summarizer": The client then builds an invocation envelope that conforms to the agent's inputs schema: The client sends the HTTP request: The host validates the request against the JSON Schema in inputs, performs the summarization, and returns a response that matches the outputs schema: The client MAY validate the response body against the outputs schema and then present the summary to the user or feed it into subsequent processing.