Skip to main content

Getting Started

Protocol Overview​

Core Features:

  • Single endpoint serves multiple agents via targetAgent routing
  • Stateless RPC design with JSON serialization
  • Workflow tracing via traceId propagation
  • Quantum-safe hybrid TLS (X25519 + Kyber-768)
  • Server-Sent Events (SSE) for real-time streaming

Transport: HTTPS
Content-Type: application/arc+json
Authentication: OAuth2 Bearer Token

Protocol Structure​

Request Format​

{
  "arc": "1.0",
  "id": "unique-request-id",
  "method": "task.create",
  "requestAgent": "client-id",
  "targetAgent": "destination-agent",
  "params": { /* method-specific parameters */ },
  "traceId": "workflow-trace-id"
}

Response Format​

{
  "arc": "1.0",
  "id": "unique-request-id",
  "responseAgent": "destination-agent",
  "targetAgent": "client-id",
  "result": { /* method-specific result */ },
  "error": null,
  "traceId": "workflow-trace-id"
}

Error Format​

{
  "arc": "1.0",
  "id": "unique-request-id",
  "responseAgent": "server",
  "targetAgent": "client-id",
  "result": null,
  "error": {
    "code": -41001,
    "message": "Agent not found",
    "details": { /* error-specific details */ }
  }
}

Available Methods​

Task Methods​

Asynchronous operations for long-running work:

MethodPurpose
task.createCreate new task with initial message
task.sendSend additional message to existing task
task.infoQuery task status and history
task.cancelCancel running task
task.subscribeSubscribe to task status notifications
task.notificationServer-initiated notification (server-to-client)

Chat Methods​

Real-time streaming for interactive conversations:

MethodPurpose
chat.startBegin new chat session with initial message
chat.messageSend message in active chat session
chat.endTerminate active chat session

Quick Start with Python SDK​

Installation​

pip install arc-sdk

# With quantum-safe TLS support
pip install arc-sdk[pqc]

Client Example​

from arc import ARCClient

client = ARCClient(
    endpoint="https://api.example.com/arc",
    token="your-oauth2-token"
)

# Create a task
response = await client.task_create(
    target_agent="booking-agent",
    initial_message={
        "role": "user",
        "parts": [{"type": "text", "content": "Book flight to Paris"}]
    }
)

task_id = response["result"]["task"]["taskId"]

Server Example​

from arc import ARCServer

server = ARCServer(server_id="booking-server")

@server.task_handler("booking-agent")
async def handle_booking(params, context):
    message = params["initialMessage"]
    
    # Process booking logic
    task_id = create_booking_task(message)
    
    return {
        "type": "task",
        "task": {
            "taskId": task_id,
            "status": "SUBMITTED",
            "createdAt": datetime.utcnow().isoformat() + "Z"
        }
    }

server.run(host="0.0.0.0", port=8000)

Next Steps​

Implementation Guides:

Core Concepts:

  • Protocol Design - Stateless RPC, single-endpoint architecture, error handling
  • Architecture - Multi-agent patterns, supervisor/router, workflow composition
  • Security - OAuth2 authentication, quantum-safe TLS, authorization

SDK Documentation:

Specification: