SuperOptiX AI

Agent-to-Agent (A2A) Interoperability and Optimization Layer

Make the agents you already run A2A-compliant, and get them discovered.

A2A 1.0 at full conformance, an adapt path for eight agent runtimes, and GEPA optimization of how agents are discovered.

Quick Install

Recommended CLI install with uv

uv tool install superoptix
super --help

Add framework dependencies in the same tool environment

# OpenAI Agents SDK
uv tool install superoptix --with "superoptix[frameworks-openai]"

# Claude Agent SDK
uv tool install superoptix --with "superoptix[frameworks-claude-sdk]"

# Google ADK
uv tool install superoptix --with "superoptix[frameworks-google]"

# Pydantic AI
uv tool install superoptix --with "superoptix[frameworks-pydantic-ai]"

# DeepAgents
uv tool install superoptix --with "superoptix[frameworks-deepagents]"

# Microsoft Agent Framework
uv tool install superoptix --with "superoptix[frameworks-microsoft]"

CrewAI

CrewAI installs alongside SuperOptiX rather than as an extra:

uv tool install superoptix --with "crewai>=1.15"

Use a CrewAI-only environment for this: CrewAI requires chromadb~=1.1.0, while SuperOptiX's chromadb / turboagents / vectordb extras require chromadb>=1.5.5. The older DSPy/CrewAI json-repair conflict no longer applies — CrewAI 1.15+ and DSPy 3.3 co-install cleanly.

Adding SuperOptiX to an existing project

uv add superoptix

Requirements: Python 3.11+ and uv.

Framework Support

SuperOptiX supports compiling and running agents across:

Two upper bounds are upstream constraints, not choices:

• OpenAI Agents SDK is held at <0.21. 0.22+ requires openai>=3.0, while LiteLLM (a DSPy dependency) still requires openai<3.0.
• Pydantic AI is held at <2.32. 2.36 requires opentelemetry-api==1.44, while Google ADK 2.x caps it at <=1.42.1.

Core Workflow

# Pull
super agent pull developer

# Compile minimal pipeline
super agent compile developer --framework dspy

# Run
super agent run developer --framework dspy --goal "Design a migration strategy"

# Optional optimization path
super agent compile developer --framework dspy --optimize
super agent optimize developer --framework dspy --auto light

Featured Capabilities

• Adapt agents built outside SuperOptiX to A2A 1.0 without modifying them
• A2A 1.0 server at 100% conformance against the official Technology Compatibility Kit
• Routing-quality measurement and GEPA optimization over the Agent Card
• GEPA optimization flow across frameworks
• TurboAgents-backed GEPA vector stores for Chroma, FAISS, LanceDB, and SurrealDB
• Minimal runtime pipelines by default with optional optimization lifecycle

TurboAgents Reference Integration

SuperOptiX is now the first full reference integration for turboagents.

Current validated state:

• turboagents-chroma is wired into the shared RAG layer and covered by focused runtime tests
• turboagents-lancedb is validated through the real rag_lancedb_demo flow
• turboagents-surrealdb is validated through the real OpenAI Agents and Pydantic AI SurrealDB demo flows
• the DSPy SurrealDB path is still blocked by a local LiteLLM and Ollama compatibility issue, not by the TurboAgents retrieval layer itself

Current backends exposed through SuperOptiX are:

• turboagents-chroma
• turboagents-faiss
• turboagents-lancedb
• turboagents-surrealdb

Read more:

• TurboAgents integration guide: https://superagenticai.github.io/superoptix/guides/turboagents-integration/
• Chroma demo: https://superagenticai.github.io/superoptix/examples/agents/rag-chroma-demo/
• LanceDB demo: https://superagenticai.github.io/superoptix/examples/agents/rag-lancedb-demo/
• SurrealDB frameworks guide: https://superagenticai.github.io/superoptix/examples/agents/surrealdb-frameworks-demo/

A2A Support

SuperOptiX implements the A2A 1.0 protocol directly over FastAPI. The a2a-sdk package is not a dependency.

Conformance

Measured with the official A2A TCK:

The suite runs in CI on every change to the protocol layer, with a floor that fails the build if compliance regresses.

Adapting an existing agent

Agents built before you adopted SuperOptiX can be given an A2A endpoint without being rewritten:

super a2a adapt --entrypoint mycrew:crew --framework crewai
uvicorn a2a.a2a_server:app --port 8000

This reads the agent's structure, derives the skills a calling agent would route on, and writes an Agent Card and a server. Your code is not modified. Introspectors ship for all eight supported frameworks; the framework is detected when not specified.

Protocol surface

• All eleven A2A 1.0 methods answer. Push-notification configuration and the extended agent card return the errors the spec defines for an agent that does not offer them, rather than a 404
• JSON-RPC 2.0 and HTTP+JSON bindings
• 0.3 and 1.0 served from one endpoint, selected with the A2A-Version header, so agents on the pre-1.0 line remain reachable
• Serving compiled agents with super agent serve <name> --protocol a2a
• Calling remote A2A agents through the SuperOptiX A2A client

gRPC and signed Agent Cards are not implemented.

MCP

Agents adapted by SuperOptiX keep using their MCP tools. SuperOptiX changes how an agent is reached, not how it works. Exposing an agent as an MCP server is not supported.

Install the optional A2A extra:

uv tool install superoptix --with "superoptix[a2a]"

For the full packaged demo set:

uv tool install superoptix --with "superoptix[a2a,frameworks-pydantic-ai,frameworks-google]"

For demo details:

• DSPy demo: no model API key required
• Pydantic AI demo: no model API key required
• Google ADK demo: requires GOOGLE_API_KEY

Read more:

• A2A introduction: https://superagenticai.github.io/superoptix/guides/a2a-introduction/
• Adapting an existing agent: https://superagenticai.github.io/superoptix/guides/a2a-adapt/
• A2A conformance: https://superagenticai.github.io/superoptix/guides/a2a-conformance/
• Routing quality: https://superagenticai.github.io/superoptix/guides/a2a-routing/
• A2A guide: https://superagenticai.github.io/superoptix/guides/a2a-guide/
• A2A demo guide: https://superagenticai.github.io/superoptix/guides/a2a-demo-guide/

Documentation

• Docs home: https://superagenticai.github.io/superoptix/
• Golden workflow: https://superagenticai.github.io/superoptix/guides/golden-workflow/
• Framework feature matrix: https://superagenticai.github.io/superoptix/guides/framework-feature-matrix/
• TurboAgents integration: https://superagenticai.github.io/superoptix/guides/turboagents-integration/
• Troubleshooting by symptom: https://superagenticai.github.io/superoptix/guides/troubleshooting-by-symptom/

SuperOptiX Lite (Companion Repo)

For a lightweight, MIT-licensed starter kit focused on OpenAI Agents SDK + GEPA:

git clone https://github.com/SuperagenticAI/superoptix-lite-openai.git

Support

• Website: https://superoptix.ai
• GitHub: https://github.com/SuperagenticAI/superoptix
• PyPI: https://pypi.org/project/superoptix/

Telemetry

SuperOptiX collects anonymous usage data to improve the tool.

To disable telemetry:

export SUPEROPTIX_TELEMETRY=false

License

Apache License 2.0. See LICENCE.