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

[c-mysec]

Address the need for an OpenAPI and OpenRPC specification of the protocol for a server specification,
This can be used as a template for creating server documentation and model intefaces. 🦕

[holtskinner]

Can the openai.yaml and openrpc.json be auto-generated from the existing a2a.json ?

[c-mysec]

Can the openai.yaml and openrpc.json be auto-generated from the existing a2a.json ?

Not a complete or accurate specification. There are some "SHOULD" clauses in the specification and the agent card doesn't have the information if the agent endpoint supports it, uses it or not. For instance:

• SHOULD use standard HTTP status codes like 401 Unauthorized or 403 Forbidden for authentication challenges or rejections.

The agent card has no information what status code is used and the openapi spec has the field to specify the behavior.
I wonder if a tool that auto-generate a partial/incomplete interface spec would be misleading or used in a wrong way.

[c-mysec]

I see the openapi and openrpc more as a complimentary spec with transport details to a server specification and not as an alternative that can be inferred from the agent card and a2a standard.

[c-mysec]

with a help from gpt4o

Checklist: Information Needed in openapi.yaml Beyond AgentCard

This document outlines all required and recommended fields in an OpenAPI 3.1 specification (openapi.yaml) for an A2A-compliant agent, that cannot be inferred directly from the AgentCard.

---

✅ Checklist of Information NOT in AgentCard but Required/Recommended in openapi.yaml

1. 🔵 info Section (API Metadata)

Field	Required?	Inferred from AgentCard?	Notes
title	✅ Yes	❌ No	The name of the API, not the agent. E.g., "A2A Agent Discovery API"
version	✅ Yes	❌ No	The API spec version, not the agent version
description	✅ Yes	❌ No	Explains the purpose of the API, not the agent’s function
termsOfService	⚠️ Optional	❌ No	Include if available
contact, license	⚠️ Recommended	❌ No	Recommended for public/corporate APIs for governance/compliance

2. 🔵 servers Section (Deployment Info)

Field	Required?	Inferred from AgentCard?	Notes
url	✅ Yes	❌ No	Must specify where the agent is hosted
variables	⚠️ Optional	❌ No	Helps support multi-environment configs (e.g., staging/prod)

3. 🔵 paths Section (REST Endpoints)

Field	Required?	Inferred from AgentCard?	Notes
/well-known/agent.json	✅ Yes	❌ No	But it is specified in the standard
operationId	⚠️ Recommended	❌ No	Useful for codegen and interactive docs
tags	⚠️ Recommended	❌ No	Helps group endpoints in tools like Swagger UI

4. 🔵 responses (Beyond 200)

Status	Inferred from AgentCard?	Notes
401	❌ No	Missing or invalid credentials
403	❌ No	Authenticated but lacks permission
500	❌ No	Unexpected internal errors

5. 🔵 security (at the Operation Level)

Field	Inferred from AgentCard?	Notes
security	⚠️ Partially	AgentCard lists available schemes, but not which ones are required per endpoint — this must be explicitly stated in the spec

6. 🔵 Error Schemas and Examples

Field	Inferred?	Notes
components.schemas.ErrorResponse	❌ No	Recommended for public APIs
examples	⚠️ Partially	If skills[].examples are present, they can be reused — but more full usage examples may be needed for context

7. 🔵 Vendor Extensions (If Applicable)

Extension	Needed?	Inferred?	Notes
x-logo, x-agent-id, x-runtime	⚠️ Optional	❌ No	Useful for visual tools like Stoplight or Redoc
x-a2a-supported-version	⚠️ Recommended	❌ No	Indicates compatibility with A2A protocol version — useful in multi-agent environments

---

✅ Summary — What You Must Provide Beyond the AgentCard

1. API metadata: info.title, info.version, info.description, contact
2. Agent base URL: e.g., https://your-agent.com
3. Required security schemes per endpoint (e.g., Bearer only, or multiple)
4. Expected HTTP status codes beyond 200: 401, 403, 500