Independent Submission M. Gaikwad Internet-Draft 1 December 2025 Intended status: Experimental Expires: 4 June 2026 The Web of Agents (WoA) draft-gaikwad-woa-00 Abstract 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. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at https://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on 4 June 2026. Copyright Notice Copyright (c) 2025 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/ license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Gaikwad Expires 4 June 2026 [Page 1] Internet-Draft WoA December 2025 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 2. Conventions and Terminology . . . . . . . . . . . . . . . . . 3 2.1. Terms . . . . . . . . . . . . . . . . . . . . . . . . . . 3 3. Architecture . . . . . . . . . . . . . . . . . . . . . . . . 4 4. WoA Document Schema . . . . . . . . . . . . . . . . . . . . . 4 4.1. Agent Objects . . . . . . . . . . . . . . . . . . . . . . 5 4.2. JSON Schema Usage for Inputs and Outputs . . . . . . . . 6 4.3. Transport Configurations . . . . . . . . . . . . . . . . 6 4.3.1. REST Transport . . . . . . . . . . . . . . . . . . . 7 4.3.2. MCP Transport . . . . . . . . . . . . . . . . . . . . 7 4.3.3. Private Transports . . . . . . . . . . . . . . . . . 8 5. Invocation . . . . . . . . . . . . . . . . . . . . . . . . . 8 5.1. Invocation Envelope . . . . . . . . . . . . . . . . . . . 8 5.2. REST Transport Invocation . . . . . . . . . . . . . . . . 8 5.3. MCP Transport Invocation . . . . . . . . . . . . . . . . 9 6. Authorization . . . . . . . . . . . . . . . . . . . . . . . . 9 7. Caching . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 8. Security Considerations . . . . . . . . . . . . . . . . . . . 10 8.1. Transport Security . . . . . . . . . . . . . . . . . . . 10 8.2. Server Side Request Forgery and Origin Validation . . . . 10 8.3. Indirect Prompt Injection . . . . . . . . . . . . . . . . 11 8.4. Agent Output Trust . . . . . . . . . . . . . . . . . . . 11 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 9.1. Well Known URI Registration . . . . . . . . . . . . . . . 11 9.2. Media Type Registration . . . . . . . . . . . . . . . . . 11 9.3. WoA Transport Registry . . . . . . . . . . . . . . . . . 12 10. Normative References . . . . . . . . . . . . . . . . . . . . 12 11. Informative References . . . . . . . . . . . . . . . . . . . 14 Appendix A: Example Use with SOUTH (Non-Normative) . . . . . . . 14 Appendix B: Complete Example WoA Flow (Non-Normative) . . . . . . 16 Example WoA Document . . . . . . . . . . . . . . . . . . . . . 16 Client Fetches WoA Document . . . . . . . . . . . . . . . . . . 17 Client Invokes the Agent . . . . . . . . . . . . . . . . . . . 18 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 19 1. 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: Gaikwad Expires 4 June 2026 [Page 2] Internet-Draft WoA December 2025 * 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 [CUI-AGENT-DISCOVERY] 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. 2. 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 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. This document uses the JSON data model defined in [RFC8259] and HTTP terminology from [RFC9110]. 2.1. 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. Gaikwad Expires 4 June 2026 [Page 3] Internet-Draft WoA December 2025 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. 3. 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. +-----------+ GET /.well-known/woa.json +-----------+ | | ---------------------------------------> | | | Client | | Host | | | <--------------------------------------- | | +-----------+ 200 application/woa+json +-----------+ | | Select agent and transport v +-----------+ HTTP POST (REST transport) +-----------+ | | ---------------------------------------> | | | Client | | Host | | | <--------------------------------------- | | +-----------+ JSON response +-----------+ Figure 1: High Level WoA Architecture 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. 4. 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 Section 4.1. Gaikwad Expires 4 June 2026 [Page 4] Internet-Draft WoA December 2025 * transports: An object whose keys are transport names and whose values are transport configuration objects as defined in Section 4.3. 4.1. 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 [RFC5234]): 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 Section 8). * 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 Section 4.2. * 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: Gaikwad Expires 4 June 2026 [Page 5] Internet-Draft WoA December 2025 * 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. 4.2. 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 [JSON-SCHEMA-CORE] [JSON-SCHEMA-VAL]. 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. 4.3. 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 Section 9.3). Gaikwad Expires 4 June 2026 [Page 6] Internet-Draft WoA December 2025 4.3.1. 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 [RFC8446]. * 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 Section 5. Hosts using the REST transport MUST respond with JSON and SHOULD use the application/problem+json media type for errors as specified in [RFC9457]. 4.3.2. MCP Transport A mcp transport configuration object describes how an agent is exposed via a Model Context Protocol (MCP) server [MCP]. 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 [MCP]. For example, if tool_field is "agent", the client MAY pass the value of the envelope's agent field as the tool name. Gaikwad Expires 4 June 2026 [Page 7] Internet-Draft WoA December 2025 4.3.3. 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. 5. 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. 5.1. 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. 5.2. REST Transport Invocation When using the REST transport, the client constructs the invocation URL as described in Section 4.3.1 and sends an HTTP POST request with media type application/json and a request body containing the invocation envelope. Gaikwad Expires 4 June 2026 [Page 8] Internet-Draft WoA December 2025 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 [RFC9457] with media type application/problem+json. Problem type URIs and error code taxonomies are deployment specific. 5.3. 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 [MCP] 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 Section 8 still apply to the host that publishes the WoA document. 6. 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 [RFC6749], mutual TLS, or other mechanisms to protect invocation endpoints. Gaikwad Expires 4 June 2026 [Page 9] Internet-Draft WoA December 2025 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 [I-D.gaikwad-south-authorization] might include an authz object with pointers to policy endpoints. Such metadata is deployment specific and out of scope for the core WoA specification. 7. 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. 8. 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. 8.1. Transport Security Hosts that serve WoA documents and implement REST transports MUST use HTTPS. The underlying TLS version SHOULD be TLS 1.3 [RFC8446]. 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. 8.2. 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 [RFC1918], 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. Gaikwad Expires 4 June 2026 [Page 10] Internet-Draft WoA December 2025 8.3. 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. 8.4. 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. 9. IANA Considerations 9.1. Well Known URI Registration This document requests registration of a new well known URI suffix in the "Well Known URIs" registry as defined in [RFC8615]. The registration template is: URI suffix: woa.json Change controller: IETF Specification document: This document Status: permanent Related information: none 9.2. Media Type Registration This document requests registration of the application/woa+json media type in the "Media Types" registry according to [RFC6838]. The registration template is: Gaikwad Expires 4 June 2026 [Page 11] Internet-Draft WoA December 2025 Type name: application Subtype name: woa+json Required parameters: none Optional parameters: none Encoding considerations: binary WoA documents are encoded as UTF-8 JSON text. Security considerations: See Section 7 of this document. Interoperability considerations: none Published specification: This document. Applications that use this media type: WoA hosts and clients that exchange WoA documents. Fragment identifier considerations: none Additional information: none Person & email address to contact: Madhava Gaikwad Intended usage: COMMON Restrictions on usage: none Author: Madhava Gaikwad Change controller: IETF 9.3. 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 [RFC8126]. This document registers the following initial entries: Transport name: rest Reference: This document Transport name: mcp Reference: Model Context Protocol specification [MCP] 10. Normative References Gaikwad Expires 4 June 2026 [Page 12] Internet-Draft WoA December 2025 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, . [RFC8259] Bray, T., "The JavaScript Object Notation (JSON) Data Interchange Format", STD 90, RFC 8259, DOI 10.17487/RFC8259, December 2017, . [RFC9110] Fielding, R., Nottingham, M., and J. Reschke, "HTTP Semantics", STD 97, RFC 9110, DOI 10.17487/RFC9110, June 2022, . [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, . [RFC8615] Nottingham, M., "Well-Known Uniform Resource Identifiers (URIs)", RFC 8615, DOI 10.17487/RFC8615, May 2019, . [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type Specifications and Registration Procedures", BCP 13, RFC 6838, DOI 10.17487/RFC6838, January 2013, . [RFC9457] Nottingham, M., Wilde, E., and S. Dalal, "Problem Details for HTTP APIs", RFC 9457, DOI 10.17487/RFC9457, July 2023, . [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC 6749, DOI 10.17487/RFC6749, October 2012, . [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", STD 68, RFC 5234, DOI 10.17487/RFC5234, January 2008, . [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for Writing an IANA Considerations Section in RFCs", BCP 26, RFC 8126, DOI 10.17487/RFC8126, June 2017, . Gaikwad Expires 4 June 2026 [Page 13] Internet-Draft WoA December 2025 [RFC1918] Rekhter, Y., Moskowitz, B., Karrenberg, D., de Groot, G., and E. Lear, "Address Allocation for Private Internets", BCP 5, RFC 1918, DOI 10.17487/RFC1918, February 1996, . [JSON-SCHEMA-CORE] Wright, A., Andrews, H., Hutton, B., and G. Dennis, "JSON Schema: A Media Type for Describing JSON Documents", December 2020, . [JSON-SCHEMA-VAL] Wright, A., Andrews, H., and B. Hutton, "JSON Schema Validation: A Vocabulary for Structural Validation of JSON", December 2020, . [I-D.gaikwad-south-authorization] Gaikwad, M., "SOUTH: Stochastic Authorization for Agent and Service Requests", Work in Progress, Internet-Draft, draft-gaikwad-south-authorization, October 2025, . 11. Informative References [CUI-AGENT-DISCOVERY] Cui, Y., Chao, Y., and C. Du, "HTTP-Based AI Agent Discovery and Invocation Protocol", Work in Progress, Internet-Draft, draft-cui-ai-agent-discovery-invocation, October 2025, . [MCP] Anthropic, "Model Context Protocol Specification", November 2024, . Appendix A: Example Use with SOUTH (Non-Normative) This appendix sketches how a deployment might combine WoA with the SOUTH stochastic authorization protocol [I-D.gaikwad-south-authorization]. 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: Gaikwad Expires 4 June 2026 [Page 14] Internet-Draft WoA December 2025 { "woa_version": "1", "agents": [ { "id": "summarizer", "name": "Document Summarizer", "description": "Summarizes English text.", "version": "1.0.0", "capabilities": [ "https://example.com/capability/summarization" ], "inputs": { "...": "JSON Schema elided" }, "outputs": { "...": "JSON Schema elided" }, "transports": ["rest"], "authz": { "scheme": "south", "policy_uri": "https://authz.example.com/south/policies/summarizer", "token_header": "Authorization" } } ], "transports": { "rest": { "base": "https://api.example.com", "invoke_path": "/agents/{agent_id}/invoke" } } } A client that understands SOUTH could first obtain a token from the SOUTH authorization server according to [I-D.gaikwad-south-authorization] and then include it as a SOUTH token in the HTTP request: POST /agents/summarizer/invoke HTTP/1.1 Host: api.example.com Content-Type: application/json Authorization: SOUTH eyJhbGciOi... { "agent": "summarizer", "operation": "default", "input": { "text": "Long document text here..." } } Gaikwad Expires 4 June 2026 [Page 15] Internet-Draft WoA December 2025 The details of how SOUTH evaluates policies and issues tokens are defined in [I-D.gaikwad-south-authorization] 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. { "woa_version": "1", "agents": [ { "id": "summarizer", "name": "Document Summarizer", "description": "Summarizes English text.", "version": "1.0.0", "capabilities": [ "https://example.com/capability/summarization" ], "inputs": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "text": { "type": "string", "description": "Input document text in English." }, "max_words": { "type": "integer", "minimum": 10, "maximum": 500, "description": "Maximum number of words in the summary." } }, "required": ["text"] }, "outputs": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { Gaikwad Expires 4 June 2026 [Page 16] Internet-Draft WoA December 2025 "summary": { "type": "string", "description": "The generated summary." } }, "required": ["summary"] }, "transports": ["rest"], "operations": [ { "name": "default", "description": "Default summarization operation." } ] } ], "transports": { "rest": { "base": "https://api.example.com", "invoke_path": "/agents/{agent_id}/invoke" } } } Client Fetches WoA Document A client fetches the WoA document: GET /.well-known/woa.json HTTP/1.1 Host: api.example.com Accept: application/woa+json, application/json The host responds: HTTP/1.1 200 OK Content-Type: application/woa+json ETag: "abc123" Cache-Control: max-age=300 { ... JSON from previous section ... } The client parses the JSON, locates the agent with id "summarizer", and notes that it supports the rest transport. Gaikwad Expires 4 June 2026 [Page 17] Internet-Draft WoA December 2025 Client Invokes the Agent The client constructs the invocation URL by concatenating the base and invoke_path values and substituting "{agent_id}" with "summarizer": https://api.example.com/agents/summarizer/invoke The client then builds an invocation envelope that conforms to the agent's inputs schema: { "agent": "summarizer", "operation": "default", "input": { "text": "The IETF is an open community of designers.", "max_words": 40 } } The client sends the HTTP request: POST /agents/summarizer/invoke HTTP/1.1 Host: api.example.com Content-Type: application/json Accept: application/json { "agent": "summarizer", "operation": "default", "input": { "text": "The IETF is an open community of designers.", "max_words": 40 } } The host validates the request against the JSON Schema in inputs, performs the summarization, and returns a response that matches the outputs schema: HTTP/1.1 200 OK Content-Type: application/json { "summary": "The IETF is a community focused on Internet evolution." } Gaikwad Expires 4 June 2026 [Page 18] Internet-Draft WoA December 2025 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. Author's Address Madhava Gaikwad Email: gaikwad.madhav@gmail.com Gaikwad Expires 4 June 2026 [Page 19]