SuperOptiX AI

Optimization and Quality layer for AI agents

Optimize agents. Connect over A2A. Ship with quality.

What it does

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.

Install

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 | sh

Extras 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 sh

If you already have uv and would rather run it yourself:

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:

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

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:

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.

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:

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

Release records

super agent evaluate can write an Agent Quality Record: what was measured, what held, and the way back.

super agent evaluate developer --gauge-out record.yaml

The 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.

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.