SuperOptiX AI
Agent-to-Agent (A2A) Interoperability and Optimization Layer
Make the agents you already run A2A-compliant, and get them discovered.
What it does
Agents built on different frameworks cannot call each other. A2A is the protocol that lets them, and SuperOptiX gives an agent an A2A interface without asking you to rewrite it.
Point it at an agent you already run. SuperOptiX reads its structure, works out the skills a calling agent would route on, and writes an Agent Card and a conformant server. Your code is not modified.
Being reachable is only half the problem. Whether another agent chooses to call yours depends on how its card describes it, so SuperOptiX also measures that and improves it.
Install
Requires Python 3.11+ and uv.
uv tool install superoptix
To adapt or serve agents over A2A:
uv tool install superoptix --with "superoptix[a2a]"
To add SuperOptiX to an existing project:
uv add superoptix
Adapt an existing agent
super a2a adapt --entrypoint mycrew:crew --framework crewai
This writes three files to ./a2a:
| File | Contents |
|---|---|
agent-card.json |
A2A 1.0 Agent Card, advertising both the 1.0 and 0.3 spec lines |
a2a_server.py |
ASGI application that imports your agent and serves it |
agentspec.json |
The generated intermediate representation |
Serve it with any ASGI host:
uvicorn a2a.a2a_server:app --port 8000
curl localhost:8000/.well-known/agent-card.json
The framework is detected when you omit --framework. Use --url to set the
address the card advertises, and --out to choose the output directory.
Supported runtimes
| Runtime | --framework |
Skills derived from |
|---|---|---|
| DSPy | dspy |
Signature instructions, inputs and outputs |
| CrewAI | crewai |
Crew tasks, or agent roles when there are none |
| OpenAI Agents SDK | openai |
Tool names and descriptions |
| Pydantic AI | pydantic-ai |
Function toolset entries |
| Google ADK | google-adk |
Agent description, plus sub-agents |
| Claude Agent SDK | claude-sdk |
Agent definition or system prompt |
| DeepAgents | deepagents |
Subagent names and descriptions |
| Microsoft Agent Framework | microsoft |
Agent description and instructions |
Install the matching extra to work with a runtime, for example
uv tool install superoptix --with "superoptix[frameworks-openai]".
CrewAI installs separately, because it requires chromadb~=1.1.0 while the
vector store extras require chromadb>=1.5.5:
uv tool install superoptix --with "crewai>=1.15"
Conformance
Measured against the official A2A Technology Compatibility Kit:
| Level | Compliance |
|---|---|
| MUST | 100% |
| SHOULD | 100% |
| MAY | 100% |
The suite runs in CI on every change to the protocol layer, and the build fails if compliance regresses. An adapted agent scores 86.3% MUST, which matches the published SuperOptiX endpoint. The difference is a set of TCK scenario hooks that a production agent should not implement.
A live endpoint runs at a2a.superoptix.ai, with its Agent Card published at superoptix.ai/.well-known/agent-card.json.
Protocol surface
All eleven A2A 1.0 methods answer. Push notification configuration and the extended agent card return the errors the specification defines for an agent that does not offer them.
Both the JSON-RPC 2.0 and HTTP+JSON bindings are served. One endpoint handles
A2A 1.0 and 0.3, selected with the A2A-Version request header, because five of
the eight supported runtimes declare no A2A dependency and the three that do sit
below 1.0.
gRPC and signed Agent Cards are not implemented.
Agents adapted by SuperOptiX keep using their MCP tools. SuperOptiX changes how an agent is reached rather than how it works, and exposing an agent as an MCP server is not supported.
Discoverability
A calling agent decides whether to invoke yours by reading skills[].description
on your card. Those strings are the routing interface.
Four sibling skills, identical queries, differing only in how each describes itself:
| Catalogue | Invocation | Discovery |
|---|---|---|
| Vague | 12.5% | 75% |
| Specific | 100% | 100% |
superoptix.protocols.a2a.routing scores this, and GEPA improves it by
rewriting the descriptions. On the vague catalogue above it raises invocation
from 12.5% to 75%.
Compiling from a specification
SuperOptiX also compiles agents from SuperSpec, a declarative YAML format, into native code for any supported runtime.
super agent pull developer
super agent compile developer --framework dspy
super agent run developer --framework dspy --goal "Design a migration strategy"
GEPA optimization is available on the compiled agent:
super agent compile developer --framework dspy --optimize
super agent optimize developer --framework dspy --auto light
Documentation
- Adapting an existing agent
- A2A conformance
- Routing quality
- Quick start
- CLI reference
- Runtime feature matrix
- Troubleshooting
Full documentation is at superagenticai.github.io/superoptix.
Telemetry
SuperOptiX collects anonymous usage data. Disable it with:
export SUPEROPTIX_TELEMETRY=false
Links
- Website: superoptix.ai
- Package: pypi.org/project/superoptix
- Source: github.com/SuperagenticAI/superoptix
- Changelog: CHANGELOG.md
License
Apache License 2.0. See LICENCE.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file superoptix-0.3.1.tar.gz.
File metadata
- Download URL: superoptix-0.3.1.tar.gz
- Upload date:
- Size: 5.5 MB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.12.7
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
4a4f6e2bd99a37bdac5dab4d173aff2620a177346c9f297d3ce51d2d61c2803f
|
|
| MD5 |
9b3864d31468a17e83ab114dbe9e752b
|
|
| BLAKE2b-256 |
c2b214806c4d9c69d8466d7d5f6a8425cdb4be9e654136b2e9973ff117315b2a
|
File details
Details for the file superoptix-0.3.1-py3-none-any.whl.
File metadata
- Download URL: superoptix-0.3.1-py3-none-any.whl
- Upload date:
- Size: 1.3 MB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.12.7
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
8c7af643a0c4ff7c36b13577da3fecbb3aa19c3fef9a3c08241750daec35b75e
|
|
| MD5 |
0b34edd96bf2c9fce040ff5e514df1ed
|
|
| BLAKE2b-256 |
f9c9dd73587bb8ecdc21cf49b66ab1897c6b7b4e6c4ba58cd9396b456a95ddf6
|
