docs: Server documentation example and template based on openapi and openrpc standards

Author: c-mysec

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/google/A2A/pull/127)
 - Go example [PR\#52](https://github.com/google/A2A/pull/52)
 - Daytona sandbox running agent [PR\#170](https://github.com/google/A2A/pull/170)
+- Server documentation example and template
 
 ## What is Driving This Excitement?
 

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"]