Optimize agents. Connect over A2A. Ship with quality.
SuperOptiX is an optimization and quality layer for AI agents. Improve how agents behave and get discovered, connect them over A2A for interop across frameworks, and ship with measurable quality.
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.
One line, on macOS, Linux and WSL. It installs uv if it is missing, then installs SuperOptiX into an isolated tool environment. It never uses sudo.
curl -fsSL https://superoptix.ai/install.sh | shExtras and an exact version can be selected with environment variables:
curl -fsSL https://superoptix.ai/install.sh | SUPEROPTIX_EXTRAS=a2a sh
curl -fsSL https://superoptix.ai/install.sh | SUPEROPTIX_VERSION=0.3.5 shIf you already have uv and would rather run it yourself:
uv tool install superoptixTo adapt or serve agents over A2A:
uv tool install superoptix --with "superoptix[a2a]"To add SuperOptiX to an existing project:
uv add superoptixsuper a2a adapt --entrypoint mycrew:crew --framework crewaiThis 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.jsonThe framework is detected when you omit --framework. Use --url to set the
address the card advertises, and --out to choose the output directory.
| 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"Measured against the official A2A Technology Compatibility Kit:
| Level | Passed / exercised | Not exercised |
|---|---|---|
| MUST | 73 / 73 | 21 |
| SHOULD | 7 / 7 | 4 |
| MAY | 4 / 4 | 0 |
Zero failures. Every requirement the TCK is able to exercise against the conformance harness passes.
The TCK also prints a headline percentage, currently 77.7% at MUST. That figure counts the 25 requirements it cannot exercise here as non-compliant. They break down as 13 for authentication and TLS, 4 for Agent Card JWS signatures, 4 for cross-binding equivalence, 3 for version negotiation probes and 1 for the gRPC binding. None of them are failures, and none can be exercised until those features exist. Authentication, card signing and a gRPC binding are not implemented today.
Run it yourself with super a2a adapt, the TCK SUT harness and
.github/workflows/a2a-conformance.yml, which is a manual workflow that fails
on any conformance failure rather than on a percentage.
An adapted agent scores lower on the headline figure than the SuperOptiX endpoint because the TCK drives protocol states through magic messageId prefixes that a production agent should not honour.
A live endpoint runs at a2a.superoptix.ai, with its Agent Card published at superoptix.ai/.well-known/agent-card.json.
The A2A project publishes an official command-line client,
a2a (a2aproject/a2a-cli). Use it as a
standardized third-party or CI client against any A2A agent, including the public
SuperOptiX endpoint. SuperOptiX product surfaces stay super a2a adapt,
super a2a serve, and the FastAPI bridge. The Go CLI is not vendored into
SuperOptiX.
Install from the a2a-cli releases (Homebrew, WinGet, or a prebuilt binary). Then:
# Discover the public Agent Card
a2a card get -a https://a2a.superoptix.ai
# Call a catalogue skill
a2a send -a https://a2a.superoptix.ai "Does CrewAI support A2A?"Add -o json for protocol-native JSON suitable for scripts. Verified with
a2a v0.2.0 against https://a2a.superoptix.ai. The CLI specification is still
in Review; treat command details as evolving with upstream releases.
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.
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%.
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 lightsuper agent evaluate can write an Agent Quality Record: what was measured,
what held, and the way back.
super agent evaluate developer --gauge-out record.yamlThe format is SuperGauge. The
record carries the playbook digest, the scenario manifest, the agent's declared
capabilities, and interop.routing_invocation, which reports how often a calling
agent selects yours from a catalogue. That becomes a quality dimension once
agents route work to one another.
See Agent Quality Records.
- Adapting an existing agent
- A2A conformance
- Routing quality
- Quick start
- CLI reference
- Runtime feature matrix
- Troubleshooting
Full documentation is at superagenticai.github.io/superoptix.
SuperOptiX collects anonymous usage data. Disable it with:
export SUPEROPTIX_TELEMETRY=false- Website: superoptix.ai
- Package: pypi.org/project/superoptix
- Source: github.com/SuperagenticAI/superoptix
- Changelog: CHANGELOG.md
Apache License 2.0. See LICENCE.