Skip to main content

Aragora API Quick Start

Get started with the Aragora API in 5 minutes.

Prerequisites

  • Python 3.11+
  • At least one API key: ANTHROPIC_API_KEY or OPENAI_API_KEY

Installation

pip install aragora

Quick Start

1. Start the Server

python -m aragora.server.unified_server --port 8080

2. Create a Debate

curl -X POST http://localhost:8080/api/debates \
-H "Content-Type: application/json" \
-d '{
"task": "What is the best approach to implement rate limiting?",
"agents": ["claude", "gpt4"],
"rounds": 3
}'

Response:

{
"debate_id": "d-abc123",
"status": "created",
"stream_url": "/api/debates/d-abc123/stream"
}

3. Stream the Debate

curl -N http://localhost:8080/api/debates/d-abc123/stream

Event Stream:

event: debate_start
data: {"debate_id": "d-abc123", "task": "What is the best approach..."}

event: agent_message
data: {"agent": "claude", "role": "proposer", "content": "I propose..."}

event: critique
data: {"agent": "gpt4", "target": "claude", "severity": 0.6, "content": "While valid..."}

event: agent_error
data: {"agent": "claude", "error_type": "timeout", "message": "Agent response was empty", "recoverable": true, "phase": "proposal"}

event: vote
data: {"agent": "claude", "choice": "gpt4", "confidence": 0.85}

event: consensus
data: {"reached": true, "confidence": 0.82, "answer": "...", "status": "consensus_reached", "agent_failures": {}}

event: debate_end
data: {"debate_id": "d-abc123", "duration_ms": 12500}

4. Get the Result

curl http://localhost:8080/api/debates/d-abc123

Response:

{
"id": "d-abc123",
"task": "What is the best approach to implement rate limiting?",
"final_answer": "Token bucket algorithm with Redis backend...",
"winner": "gpt4",
"confidence": 0.82,
"consensus_reached": true,
"status": "consensus_reached",
"agent_failures": {},
"rounds_used": 3,
"participants": ["claude", "gpt4"],
"messages": [...],
"votes": [...],
"duration_ms": 12500
}

Python SDK

from aragora import Arena, Environment, DebateProtocol
from aragora.agents.api_agents import AnthropicAgent, OpenAIAgent

# Create agents
agents = [
AnthropicAgent(name="claude"),
OpenAIAgent(name="gpt4")
]

# Configure the debate
env = Environment(task="Design a rate limiter for an API")
protocol = DebateProtocol(rounds=3, consensus="majority")

# Run the debate
async def main():
arena = Arena(env, agents, protocol)
result = await arena.run()

print(f"Winner: {result.winner}")
print(f"Confidence: {result.confidence:.0%}")
print(f"Answer: {result.final_answer}")

import asyncio
asyncio.run(main())

Common Endpoints

EndpointMethodDescription
/api/debatesPOSTCreate a new debate
/api/debates/\{id\}GETGet debate result
/api/debates/\{id\}/streamGETStream debate events (SSE)
/api/debatesGETList recent debates
/api/agentsGETList available agents
/api/agents/\{name\}/statsGETGet agent statistics
/api/healthGETServer health check

Configuration Options

Debate Protocol

{
"task": "Your question or task",
"agents": ["claude", "gpt4", "gemini"],
"rounds": 3,
"consensus": "majority", // "majority" | "unanimous" | "judge"
"early_stopping": true, // Stop if agents converge
"enable_calibration": false, // Track prediction accuracy
"enable_checkpointing": true // Enable resume on failure
}

Available Agents

AgentProviderModel
claudeAnthropicclaude-3-5-sonnet
gpt4OpenAIgpt-4-turbo
geminiGooglegemini-pro
mistralMistralmistral-large
grokxAIgrok-beta

Error Handling

All errors return JSON with this structure:

{
"error": {
"code": "AGENT_TIMEOUT",
"message": "Agent claude timed out after 30s",
"details": {
"agent": "claude",
"timeout_ms": 30000
}
}
}

Common Error Codes

CodeDescriptionResolution
INVALID_REQUESTMalformed request bodyCheck JSON syntax
AGENT_UNAVAILABLEAgent API key missingSet environment variable
AGENT_TIMEOUTAgent response timeoutIncrease timeout or retry
RATE_LIMITEDProvider rate limit hitWait and retry
DEBATE_NOT_FOUNDInvalid debate IDCheck debate ID

WebSocket Events

Connect to /ws for real-time updates:

const ws = new WebSocket('ws://localhost:8080/ws');

ws.onmessage = (event) => {
const data = JSON.parse(event.data);
switch (data.type) {
case 'debate_start':
console.log('Debate started:', data.debate_id);
break;
case 'agent_message':
console.log(`${data.agent}: ${data.content}`);
break;
case 'consensus':
console.log('Consensus:', data.final_answer);
break;
}
};

Next Steps

Support