docs: Server documentation example and template based on openapi and …

.github/actions/spelling/allow.txt

@@ -56,13 +56,15 @@ PLE
 PLW
 PMEEi
 PTH
+Petstore
 RPCs
 RUF
 SLAs
 SLF
 Solax
 TJS
 TMDB
+Tful
 URLTo
 Upserting
 Urke
@@ -179,6 +181,8 @@ objc
 octicons
 ollama
 oneof
+openapis
+openrpc
 oreilly
 pqr
 prefecthq
@@ -204,6 +208,7 @@ styleguide
 svn
 systemctl
 tagwords
+tasksget
 taskssend
 taskstate
 taskstatus

GOVERNANCE.md

@@ -1,3 +1,5 @@
+# Governance
+
 ## **The Agent to Agent project is governed by the Technical Steering Committee. The Committee has seven seats, each held by the following companies:**
 
 1. Google
@@ -7,38 +9,41 @@
 5. Salesforce
 6. ServiceNow
 7. SAP
+
 ## **Mission and Scope of the Project**
+
 1. The mission of the Project is to help AI agents across different ecosystems communicate with each other.  The Project includes collaborative development of the following components:
-    1. the Agent2Agent Protocol (the “Protocol”); 
+    1. the Agent2Agent Protocol (the "Protocol");
     2. a SDK for designing implementations of the Protocol and related software components; and
     3. documentation and other artifacts related to the Project.
 2. The scope of the Project includes collaborative development under the Project License (as defined herein) supporting the mission, including documentation, testing, integration and the creation of other artifacts that aid the development, deployment, operation or adoption of the open source project.
 
-
 ## **Technical Steering Committee**
 
-1. The Technical Steering Committee (the “TSC”) will be responsible for all technical oversight of the open source Project. 
+1. The Technical Steering Committee (the "TSC") will be responsible for all technical oversight of the open source Project.
 2. TSC Composition
-   a. “Startup Phase.”  At the inception of the Project, each organization listed in the [GOVERNANCE.MD](http://GOVERNANCE.MD) file in the governance repository of the Project will have the right to appoint (and remove and replace) one employee to serve as a voting member of the TSC.
-   b. “Steady State.” The TSC will decide upon a “steady state” composition of the TSC (whether by election, sub-project technical leads, or other method as determined by the TSC) for composition of the TSC from the date that is 18 months following the inception of the Project, or at such other point as determined by the TSC.
-The TSC may choose an alternative approach for determining the voting members of the TSC, and any such alternative approach will be documented in the GOVERNANCE file.  Any meetings of the Technical Steering Committee are intended to be open to the public, and can be conducted electronically, via teleconference, or in person. 
-3. TSC projects generally will involve Contributors and Maintainers. The TSC may adopt or modify roles so long as the roles are documented in the CONTRIBUTING file. Unless otherwise documented: 
-            a. Contributors include anyone in the technical community that contributes code, documentation, or other technical artifacts to the Project; 
-            b. Maintainers are Contributors who have earned the ability to modify (“commit”) source code, documentation or other technical artifacts in a project’s repository; and
+   a. "Startup Phase."  At the inception of the Project, each organization listed in the [GOVERNANCE.MD](http://GOVERNANCE.MD) file in the governance repository of the Project will have the right to appoint (and remove and replace) one employee to serve as a voting member of the TSC.
+   b. "Steady State." The TSC will decide upon a "steady state" composition of the TSC (whether by election, sub-project technical leads, or other method as determined by the TSC) for composition of the TSC from the date that is 18 months following the inception of the Project, or at such other point as determined by the TSC.
+The TSC may choose an alternative approach for determining the voting members of the TSC, and any such alternative approach will be documented in the GOVERNANCE file.  Any meetings of the Technical Steering Committee are intended to be open to the public, and can be conducted electronically, via teleconference, or in person.
+3. TSC projects generally will involve Contributors and Maintainers. The TSC may adopt or modify roles so long as the roles are documented in the CONTRIBUTING file. Unless otherwise documented:
+            a. Contributors include anyone in the technical community that contributes code, documentation, or other technical artifacts to the Project;
+            b. Maintainers are Contributors who have earned the ability to modify ("commit") source code, documentation or other technical artifacts in a project's repository; and
             c. A Contributor may become a Maintainer by a vote of the TSC. A Maintainer may be removed by a vote of the TSC.
-            d. Participation in the Project through becoming a Contributor and Maintainer is open to anyone so long as they abide by the terms of this Charter. 
+            d. Participation in the Project through becoming a Contributor and Maintainer is open to anyone so long as they abide by the terms of this Charter.
 4. The TSC may (1) establish work flow procedures for the submission, approval, and closure/archiving of projects, (2) set requirements for the promotion of Contributors to Maintainer status, as applicable, and (3) amend, adjust, refine and/or eliminate the roles of Contributors, and Maintainer, and create new roles, and publicly document any TSC roles, as it sees fit.
 5. The TSC may elect a TSC Chair, who will preside over meetings of the TSC and will serve until their resignation or replacement by the TSC.
 6. Responsibilities: The TSC will be responsible for all aspects of oversight relating to the Project, which may include:
    1. coordinating the technical direction of the Project;
-   2. approving project or system proposals (including, but not limited to, incubation, deprecation, and changes to a sub-project’s scope);
+   2. approving project or system proposals (including, but not limited to, incubation, deprecation, and changes to a sub-project's scope);
    3. organizing sub-projects and removing sub-projects;
    4. creating sub-committees or working groups to focus on cross-project technical issues and requirements;
    5. appointing representatives to work with other open source or open standards communities;
    6. establishing community norms, workflows, issuing releases, and security issue reporting policies;
-   7. approving and implementing policies and processes for contributing (to be published in the CONTRIBUTING file) and coordinating with the series manager of the Project (as provided for in the Series Agreement, the “Series Manager”) to resolve matters or concerns that may arise as set forth in Section 7 of this Charter;
+   7. approving and implementing policies and processes for contributing (to be published in the CONTRIBUTING file) and coordinating with the series manager of the Project (as provided for in the Series Agreement, the "Series Manager") to resolve matters or concerns that may arise as set forth in Section 7 of this Charter;
    8. discussions, seeking consensus, and where necessary, voting on technical matters relating to the code base that affect multiple projects; and
    9. coordinating any marketing, events, or communications regarding the Project.
+
 ## TSC Voting
+
 While the Project aims to operate as a consensus-based community, if any TSC decision requires a vote to move the Project forward, the voting members of the TSC will vote on a one vote per voting member basis.
 Quorum for TSC meetings requires at least fifty percent of all voting members of the TSC to be present. The TSC may continue to meet if quorum is not met but will be prevented from making any decisions at the meeting. Except as provided in Section 7.c. and 8.a, decisions by vote at a meeting require a majority vote of those in attendance, provided quorum is met. Decisions made by electronic vote without a meeting require a majority vote of all voting members of the TSC.

docs/community.md

@@ -41,6 +41,7 @@ The launch of A2A has sparked lively discussions and positive reactions on vario
 - PydanticAI example [PR\#127](https://github.com/a2aproject/A2A/pull/127)
 - Go example [PR\#52](https://github.com/a2aproject/A2A/pull/52)
 - Daytona sandbox running agent [PR\#170](https://github.com/a2aproject/A2A/pull/170)
+- Server documentation example and template [PR\#586](https://github.com/a2aproject/A2A/pull/586)
 
 ## What is Driving This Excitement?
 

docs/index.md

@@ -123,6 +123,5 @@ A2A and the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) are
     [:octicons-arrow-right-24: A2A Python SDK](https://github.com/a2aproject/a2a-python)
     [:octicons-arrow-right-24: A2A JS SDK](https://github.com/a2aproject/a2a-js)
     [:octicons-arrow-right-24: A2A Java SDK](https://github.com/a2aproject/a2a-java)
-
 
 </div>

docs/tutorials/serverdocumentation/agentcard-openapi.yaml

@@ -0,0 +1,269 @@
+openapi: 3.1.0
+info:
+  title: Agent-to-Agent AgentCard Discovery
+  version: 1.0.0
+  description: >
+    Specification for serving an AgentCard at the well-known endpoint
+    /.well-known/agent.json according to the A2A protocol.
+    The AgentCard conveys key information about an A2A Server including its identity,
+    service endpoints, capabilities, authentication requirements, and skills.
+
+servers:
+  - url: https://{server_domain}
+    variables:
+      server_domain:
+        default: example.com
+        description: The domain where the agent is hosted
+
+paths:
+  /.well-known/agent.json:
+    get:
+      summary: Retrieve AgentCard
+      description: >
+        Returns the AgentCard describing the agent's capabilities, skills,
+        and authentication requirements. The AgentCard serves as the primary
+        discovery mechanism for agents in the A2A ecosystem.
+      operationId: getAgentCard
+      responses:
+        '200':
+          description: AgentCard retrieved successfully
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AgentCard'
+              example:
+                name: "Recipe Advisor Agent"
+                description: "Helps users find recipes and plan meals"
+                url: "https://agent.example.com/a2a/api"
+                version: "1.0.0"
+                capabilities:
+                  streaming: true
+                  pushNotifications: false
+                skills:
+                  - id: "recipe-finder"
+                    name: "Recipe Finder"
+                    description: "Finds recipes based on ingredients and dietary restrictions"
+        '401':
+          description: Unauthorized - Authentication failed or was not provided
+        '403':
+          description: Forbidden - Client lacks permission to access the AgentCard
+        '500':
+          description: Server error - Unexpected condition prevented fulfilling the request
+
+      security:
+        - BearerAuth: []
+        - OAuth2: []
+        - ApiKeyAuth: []
+        - BasicAuth: []
+      tags:
+        - Discovery
+
+components:
+  securitySchemes:
+    BearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+      description: Standard JWT Bearer Token authentication
+    BasicAuth:
+      type: http
+      scheme: basic
+      description: Basic HTTP authentication (username/password)
+    ApiKeyAuth:
+      type: apiKey
+      in: header
+      name: X-API-Key
+      description: API key authentication via custom header
+    OAuth2:
+      type: oauth2
+      description: OAuth2 authentication using authorization code flow
+      flows:
+        authorizationCode:
+          authorizationUrl: https://example.com/oauth/authorize
+          tokenUrl: https://example.com/oauth/token
+          scopes:
+            read: Read access to the agent
+            write: Write access to the agent
+
+  schemas:
+    AgentCard:
+      type: object
+      description: >
+        Conveys key information about an A2A Server including its identity,
+        service endpoints, capabilities, authentication requirements, and skills.
+      required: [name, url, version, capabilities, skills]
+      properties:
+        name:
+          type: string
+          description: Human-readable name of the agent (e.g., "Recipe Advisor Agent")
+          example: "Recipe Advisor Agent"
+        description:
+          type: string
+          nullable: true
+          description: >
+            Human-readable description of the agent and its purpose.
+            CommonMark MAY be used for rich text formatting.
+          example: "This agent helps users find recipes, plan meals, and get cooking instructions."
+        url:
+          type: string
+          format: uri
+          description: >
+            The base URL endpoint for the agent's A2A service.
+            Must be an absolute HTTPS URL for production.
+          example: "https://agent.example.com/a2a/api"
+        provider:
+          $ref: '#/components/schemas/AgentProvider'
+          description: Information about the organization or entity providing the agent
+        version:
+          type: string
+          description: >
+            Version string for the agent or its A2A implementation.
+            Format is defined by the provider (e.g., "1.0.0", "2023-10-26-beta").
+          example: "1.0.0"
+        documentationUrl:
+          type: string
+          format: uri
+          nullable: true
+          description: URL pointing to human-readable documentation for the agent
+          example: "https://agent.example.com/docs"
+        capabilities:
+          $ref: '#/components/schemas/AgentCapabilities'
+          description: Specifies optional A2A protocol features supported by this agent
+        authentication:
+          $ref: '#/components/schemas/AgentAuthentication'
+          description: >
+            Authentication schemes required to interact with the agent's endpoint.
+            If null or omitted, no A2A-level authentication is explicitly advertised.
+        defaultInputModes:
+          type: array
+          items:
+            type: string
+          description: >
+            Array of MIME types the agent generally accepts as input across all skills,
+            unless overridden by a specific skill. Defaults to ["text/plain"] if omitted.
+          example: ["text/plain", "application/json"]
+        defaultOutputModes:
+          type: array
+          items:
+            type: string
+          description: >
+            Array of MIME types the agent generally produces as output across all skills,
+            unless overridden by a specific skill. Defaults to ["text/plain"] if omitted.
+          example: ["text/plain", "application/json"]
+        skills:
+          type: array
+          items:
+            $ref: '#/components/schemas/AgentSkill'
+          description: >
+            An array of specific skills or capabilities the agent offers.
+            Must contain at least one skill if the agent is expected to perform actions.
+
+    AgentProvider:
+      type: object
+      description: Information about the organization or entity providing the agent
+      required: [organization]
+      properties:
+        organization:
+          type: string
+          description: Name of the organization or entity
+          example: "Example Corp"
+        url:
+          type: string
+          format: uri
+          nullable: true
+          description: URL for the provider's organization website or relevant contact page
+          example: "https://example.com"
+
+    AgentCapabilities:
+      type: object
+      description: Specifies optional A2A protocol features supported by the agent
+      properties:
+        streaming:
+          type: boolean
+          default: false
+          description: >
+            If true, the agent supports tasks/sendSubscribe and tasks/resubscribe
+            for real-time updates via Server-Sent Events (SSE).
+        pushNotifications:
+          type: boolean
+          default: false
+          description: >
+            If true, the agent supports tasks/pushNotification/set and tasks/pushNotification/get
+            for asynchronous task updates via webhooks.
+        stateTransitionHistory:
+          type: boolean
+          default: false
+          description: >
+            Placeholder for future feature: exposing detailed task status change history.
+
+    AgentAuthentication:
+      type: object
+      description: Describes the authentication requirements for accessing the agent's endpoint
+      required: [schemes]
+      properties:
+        schemes:
+          type: array
+          items:
+            type: string
+          description: >
+            Array of authentication scheme names supported/required by the agent's endpoint
+            (e.g., "Bearer", "Basic", "OAuth2", "ApiKey").
+          example: ["Bearer", "OAuth2"]
+        credentials:
+          type: string
+          nullable: true
+          description: >
+            Optional non-secret, scheme-specific information.
+            MUST NOT contain plaintext secrets (e.g., actual API key values, passwords).
+
+    AgentSkill:
+      type: object
+      description: Describes a specific capability or function the agent can perform
+      required: [id, name]
+      properties:
+        id:
+          type: string
+          description: >
+            Unique identifier for this skill within the context of this agent
+            (e.g., "currency-converter", "generate-image-from-prompt").
+          example: "recipe-finder"
+        name:
+          type: string
+          description: Human-readable name of the skill
+          example: "Recipe Finder"
+        description:
+          type: string
+          nullable: true
+          description: >
+            Detailed description of what the skill does. CommonMark MAY be used for rich text.
+          example: "Finds recipes based on ingredients and dietary restrictions"
+        tags:
+          type: array
+          items:
+            type: string
+          nullable: true
+          description: Array of keywords or categories for discoverability
+          example: ["food", "cooking", "recipes"]
+        examples:
+          type: array
+          items:
+            type: string
+          nullable: true
+          description: Array of example prompts illustrating how to use this skill
+          example: ["Find vegetarian pasta recipes", "Show me quick 30-minute meals"]
+        inputModes:
+          type: array
+          items:
+            type: string
+          nullable: true
+          description: >
+            Overrides defaultInputModes for this specific skill. Accepted MIME types.
+          example: ["text/plain", "application/json"]
+        outputModes:
+          type: array
+          items:
+            type: string
+          nullable: true
+          description: >
+            Overrides defaultOutputModes for this specific skill. Produced MIME types.
+          example: ["text/plain", "application/json"]