How A2A Generates Agents from OpenAPI Specs
A look inside the A2A OpenAPI generator: how it reads a spec, turns routes into tools, wires auth and egress, and deploys an editable agent.
How A2A Generates Agents from OpenAPI Specs
OpenAPI specs are usually treated as documentation for humans or as input for SDK generators. In A2A, they can become something more direct: an editable agent that understands a natural-language goal, chooses the right API operation, calls the live service, and returns a real result.
The key design choice is that A2A does not turn the spec into a hidden wrapper. The generator emits a normal A2APack project: agent.py, a2a.yaml, requirements.txt, a vendored openapi.json, and, for large APIs, route-group skill files. The output is intended to be read, changed, checked in, and redeployed.
From URL to source files
The control plane starts with one OpenAPI URL or a list of URLs. It fetches each document, accepts JSON or YAML, and requires a real paths object before generation continues. Multiple URLs can be combined into one composite OpenAPI-backed agent.
build_openapi_agent_source is the core generator. It reads info.title, info.version, and info.description to derive the agent name, Python class name, version, and description. It resolves the API server from an explicit base URL, OpenAPI servers, Swagger 2 host and basePath, or the source spec URL. That server becomes default runtime configuration, while OPENAPI_BASE_URL remains available as consumer setup so operators can point the same generated agent at another compatible environment.
Next, A2A walks the callable HTTP operations under paths. For each operation it preserves the method, path, operation ID, summary, description, tags, parameters, request body schema, security requirements, and whether the method is destructive. Path-level parameters are merged with operation-level parameters. Local $ref parameters are resolved. Missing path variables are inferred from {name} segments. OpenAPI 3 request bodies and Swagger 2 body or form parameters are normalized into a JSON body shape.
That normalized operation map becomes the generated agent contract. Small APIs expose a direct A2A skill for each operation, plus an auto skill that lets a caller ask for the desired outcome in natural language. The generated blog API agent is a concrete example: it exposes skills such as list_blog_posts, create_blog_post, get_blog_post, upsert_blog_post, and delete_blog_post.
Large APIs use route-group delegation. Once a spec passes the direct-operation threshold, A2A groups operations by route family, writes skills/<route-group>/SKILL.md, and gives the DeepAgents graph route-specific subagents. The public surface stays simple, usually just auto, while the runtime delegates to the subagent that owns the relevant routes.
Auth, egress, and live requests
OpenAPI security schemes become A2A consumer setup fields. API keys become secrets sent in the declared header or query location. HTTP bearer, basic auth, OAuth2, and OpenID Connect schemes become secret fields with the right authorization header behavior. Composite agents namespace conflicting security schemes so one generated agent can safely talk to several services.
The generated agent also gets an egress policy from the API server hosts. A spec-generated agent should not silently gain arbitrary network reach; it should call the service it was generated for.
At runtime, the agent builds the request from the operation definition. It substitutes path parameters, collects query parameters, applies header and cookie parameters, loads credentials from consumer setup, and calls the live service with httpx. Responses come back as structured results with ok, status_code, operation_id, and either result or error. If a live API starts returning stale-contract signals such as 404, 405, 410, or validation errors, the generated agent can tell the caller it may need to be refreshed from the latest OpenAPI spec.
Preview and deploy use the same generator
The preview endpoint and the full generation endpoint use the same source generator. Preview returns the agent name, version, server URLs, operation count, operation previews, setup fields, security schemes, source files, routing mode, route groups, source OpenAPI URLs, and warnings. That is what the dashboard shows before generation.
When the user generates the agent, the control plane packages the files into a source tarball, commits them to Gitea, commits the runtime bundle, creates a deployment record, and starts the build and ArgoCD deployment flow. The result is a normal A2APack repo, not a one-off platform artifact.
That matters because the generated agent is only the first draft. Developers can tune prompts, rename operations, remove risky endpoints, adjust grouping, harden auth labels, and add domain-specific instructions. OpenAPI gets A2A to a working agent quickly; source ownership lets the team make it production-grade.