superx (Alfinjohnson)

SuperX-代理网关编排器

Open-source infrastructure for multi-agent systems at scale

When to Use • Why SuperX • Features • Quick Start • Architecture • Documentation

______________________________________________________________________

🚀 SuperX（v0.1.0-alpha）简介

像Google ADK、LangGraph和AutoGen这样的代理框架已经帮助开发人员设计复杂的代理工作流、管理会话和添加可观察性。它们使构建和推理多智能体系统变得更加容易 *在给定的堆栈内*.

但随着系统的扩展，团队通常需要 共享基础设施层 坐着 *在...之间* 代理——尤其是当代理使用不同的框架构建、独立部署或单独扩展时。

谷歌的 A2A协议 定义了代理如何通信和交换上下文的通用标准。但是 仅靠协议无法处理运行时问题：路由、背压、弹性、持久性或实时协调。

这就是SuperX正在探索的差距。

你什么时候需要SuperX？

如果满足以下条件，您非常适合SuperX：

• ✅ 你有 多个AI代理 （2+）需要共同努力
• ✅ 代理人是 使用不同的框架构建 （LangGraph、AutoGen、自定义等）
• ✅ 代理人是 独立部署 或单独缩放
• ✅ 你需要 实时可见性 进入代理工作流程和失败
• ✅ 你想要的 内置弹性 --断路器、背压、任务持久性
• ✅ 你需要 动态路由 --没有硬编码哪个代理处理什么

如果你正在管理一个代理，或者所有代理都在一个框架内紧密耦合，那么你还不需要SuperX。

SuperX填补的空白

                    Agent Frameworks              Protocols              Infrastructure
                    ─────────────────             ─────────              ──────────────
                    
                    ✅ LangGraph                  ✅ A2A Protocol        ❓ Routing
                    ✅ AutoGen                    ✅ Standards           ❓ Load Balancing
                    ✅ Google ADK                                        ❓ Backpressure
                    ✅ Custom                                            ❓ Circuit Breakers
                                                                         ❓ Task Persistence
                                                                         ❓ Multi-Agent Coordination
                                                                         
                                           SuperX fills this gap ↑

SuperX扮演着 代理网关和编排器，处理代理逻辑本身之外的基础设施问题：

• 智能路由 --根据技能、可用性和负载将消息路由到代理
• 实时流媒体 --通过服务器发送的事件观察代理的进度
• 内置弹性 --断路器、背压和优雅降级
• 任务持久性 --跟踪多回合对话并处理失败
• 动态代理注册表 --无需重新启动即可注册/注销代理
• A2A协议支持 --完全支持Google的代理到代理协议

如果AI代理像 专业员工SuperX是 共享基础设施 --路由对话、管理故障，并在系统部分减慢或发生故障时保持工作进展。

解决方案

┌─────────────┐      ┌─────────────────────────────────────┐      ┌─────────────┐
│             │      │            SUPERX                   │      │   Agent A   │
│   Your App  │ ───► │  • Routing      • Load Balancing   │ ───► │   Agent B   │
│             │      │  • Failover     • Monitoring       │      │   Agent C   │
└─────────────┘      └─────────────────────────────────────┘      └─────────────┘
                              One endpoint.                        Many agents.
                              Any protocol.                        Hidden complexity.

特性

处理基础设施问题

快速开始

使用Docker Compose（推荐）

# Clone the repository
git clone https://github.com/alfinjohnson/superx.git
cd superx

# Start PostgreSQL and the orchestrator
docker compose up -d

# Check health
curl http://localhost:4000/health

# View logs
docker compose logs -f orchestrator

发展模式

cd orchestrator
mix deps.get
mix compile

# Start PostgreSQL (if not running)
docker compose up -d postgres

# Run database migrations
mix ecto.setup

# Start the server
mix run --no-halt

配置代理

SuperX从YAML配置文件加载代理。创建或修改 agents.yml:

# samples/agents.yml
agents:
  # A2A Protocol Agent
  my_agent:
    url: http://localhost:8001/a2a/my_agent      # A2A RPC endpoint of your agent
    bearer: ""  # Optional: API token for authentication
    protocol: a2a
    protocolVersion: 0.3.0
    metadata:
      agentCard:
        url: http://localhost:8001/a2a/my_agent/.well-known/agent-card.json
        name: my_agent
        description: Description of what this agent does
        skills:
          - id: skill_id
            name: Skill Name
            description: What this skill does

  # Another A2A Agent
  assistant_agent:
    url: http://localhost:8002/a2a/assistant
    protocol: a2a
    protocolVersion: 0.3.0
    metadata:
      agentCard:
        url: http://localhost:8002/a2a/assistant/.well-known/agent-card.json
        name: assistant_agent
        description: General purpose assistant agent

URL配置：

• url：代理服务器的A2A JSON-RPC端点（例如。， http://host:port/a2a/agent_name)
• agentCard.url：代理卡发现端点（通常 {agent_url}/.well-known/agent-card.json)
• bearer：用于保护代理通信的可选身份验证令牌

注： 您需要一个在指定URL上运行的A2A兼容代理服务器。请参阅 谷歌A2A Python示例 例如实现。

设置 SUPERX_AGENTS_FILE 加载代理的环境变量：

# Using environment variable
$env:SUPERX_AGENTS_FILE="./samples/agents.yml"; mix run --no-halt

# Or in docker-compose.yml
environment:
  - SUPERX_AGENTS_FILE=/app/config/agents.yml

看 样品/试剂.yml 举一个完整的例子。

按请求Webhooks

在请求临时通知时直接传递webhook URL，无需预先配置：

curl -X POST http://localhost:4000/rpc \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "id":1,
    "method":"message/send",
    "params":{
      "agentId":"my_agent",
      "message":{"role":"user","parts":[{"text":"Hello"}]},
      "metadata":{
        "webhook":{
          "url":"https://myapp.com/webhook",
          "hmacSecret":"secret123",
          "token":"bearer-token"
        }
      }
    }
  }'

Webhook配置：

• url （必需）：接收通知的端点
• hmacSecret （可选）：HMAC-SHA256签名的秘密
• token （可选）：用于身份验证的承载令牌
• jwtClaims （可选）：自定义JWT声明

根据请求，webhook优先于存储的webhook配置。

验证安装

# List registered agents
curl -X POST http://localhost:4000/rpc \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"agents/list","params":{}}'

# Send a message to an agent
curl -X POST http://localhost:4000/rpc \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "id":1,
    "method":"message/send",
    "params":{
      "agent":"check_prime_agent",
      "message":{"role":"user","parts":[{"text":"Is 17 a prime number?"}]}
    }
  }'

建筑

                              ┌─────────────────────────────────────────┐
                              │            SuperX Gateway               │
                              │                                         │
┌──────────┐                  │  ┌─────────────────────────────────┐   │
│  Client  │ ──── A2A ────────┼─▶│        Router & Load Balancer   │   │
└──────────┘    Protocol      │  └────────────────┬────────────────┘   │
                              │                   │                     │
                              │    ┌──────────────┼──────────────┐     │
                              │    │              │              │     │
                              │    ▼              ▼              ▼     │
                              │ ┌──────┐     ┌──────┐     ┌──────┐    │
                              │ │Agent │     │Agent │     │Agent │    │
                              │ │Worker│     │Worker│     │Worker│    │
                              │ └──┬───┘     └──┬───┘     └──┬───┘    │
                              │    │            │            │        │
                              │    │ Circuit    │ Circuit    │ Circuit│
                              │    │ Breaker    │ Breaker    │ Breaker│
                              └────┼────────────┼────────────┼────────┘
                                   │            │            │
                                   ▼            ▼            ▼
                              ┌──────────┐ ┌──────────┐ ┌──────────┐
                              │ Agent A  │ │ Agent B  │ │ Agent C  │
                              │ (Remote) │ │ (Remote) │ │ (Remote) │
                              └──────────┘ └──────────┘ └──────────┘

关键组件

• 路由器：接收A2A协议请求并路由到适当的代理
• 代理工人：管理每个代理的状态、断路器和背压
• 任务管理器：保持任务状态并处理多回合对话
• 推送通知器：提供具有可配置安全性的webhook通知

部署

存储

SuperX使用 PostgreSQL+ETS混合缓存 具有耐久性和快速读取的架构。

注： PostgreSQL是生产部署所必需的。ETS缓存提供快速读取，而PostgreSQL确保持久性。

码头工人

# Production mode
docker compose up orchestrator

# Development mode with hot reload
docker compose up orchestrator-dev

环境配置

关键环境变量：

生产部署

# Set required environment variables
export PORT=4000
export DATABASE_URL=ecto://user:pass@host/superx_prod
export AGENTS_FILE=/etc/superx/agents.yml
export SECRET_KEY_BASE=$(openssl rand -base64 64)

# Pull and run
docker pull ghcr.io/anthropics/superx:latest
docker run -d \
  --name superx \
  -p 4000:4000 \
  -e PORT \
  -e DATABASE_URL \
  -e AGENTS_FILE \
  -e SECRET_KEY_BASE \
  -v /etc/superx/agents.yml:/home/app/agents.yml:ro \
  ghcr.io/anthropics/superx:latest

代理配置

代理可以通过YAML文件或运行时API进行配置。

YAML配置

创建一个 agents.yml 文件：

agents:
  - name: my_agent
    url: https://agent.example.com/.well-known/agent.json
    # Optional: bearer token for authenticated agents
    bearer: "your-bearer-token"

挂载文件并设置 AGENTS_FILE:

docker run -d \
  -v ./agents.yml:/home/app/agents.yml:ro \
  -e AGENTS_FILE=/home/app/agents.yml \
  -e DATABASE_URL=ecto://user:pass@host/superx \
  ghcr.io/anthropics/superx:latest

运行时代理管理

# Register an agent
curl -X POST http://localhost:4000/rpc \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "id":1,
    "method":"agents/upsert",
    "params":{
      "name":"my_agent",
      "url":"https://agent.example.com/.well-known/agent.json"
    }
  }'

# Check agent health
curl -X POST http://localhost:4000/rpc \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"agents/health","params":{"name":"my_agent"}}'

# Refresh agent card
curl -X POST http://localhost:4000/rpc \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"agents/refreshCard","params":{"name":"my_agent"}}'

项目结构

superx/
├── orchestrator/           # Main Elixir application
│   ├── lib/               # Source code
│   │   └── orchestrator/  # Core modules
│   │       ├── agent/     # Agent management (Store with ETS+PostgreSQL)
│   │       ├── task/      # Task management (Store, PubSub, Streaming)
│   │       ├── schema/    # Ecto schemas (Task, Agent, PushConfig)
│   │       ├── protocol/  # Protocol implementations
│   │       │   └── a2a/   # A2A protocol (Adapter, Proxy, PushNotifier)
│   │       └── web/       # Web layer (Router, Streaming, Handlers)
│   ├── priv/db/           # Database migrations
│   └── test/              # Test suite (430+ tests)
│       ├── protocol/      # Protocol-specific tests
│       └── stress/        # Stress and performance tests
├── docs/                  # Documentation
│   ├── a2a-v030/         # A2A v0.3.0 specification
│   └── roadmap.md        # Development roadmap
├── samples/              # Sample configurations
│   └── agents.yml        # Example agent configuration
└── docker-compose.yml    # Local development setup

文档

用户指南

• 快速开始 -在几分钟内开始跑步
• 建筑 -系统设计概述
• 部署 -生产部署指南
• 路线图 -未来发展规划

开发者文档

• 编排器README -开发设置和贡献指南
• 更新日志 -版本历史和更改
• 贡献 -贡献指南

协议规范

• A2A协议 --Google的代理到代理协议规范
• A2A文件 --正式协议文件
• A2A Python示例 --代理实现示例
• A2A v0.3.0规格 --A2A规范的本地副本

技术栈

内置于 Elixir和OTP --专为我们需要的东西而设计：长时间运行、容错、高度并发的代理工作流。可靠性是头等大事，而不是事后的想法。

贡献

1. 克隆该仓库
2. 创建要素分支(git checkout -b feature/amazing-feature)
3. 运行测试(mix test --exclude stress)
4. 提交更改(git commit -m 'Add amazing feature')
5. 推送到分支(git push origin feature/amazing-feature)
6. 打开拉取请求

许可证

MIT许可证-请参阅 许可证 了解详情。