Integration Guide

End-to-end walkthrough for connecting your AI agent to Relex via A2A. After completing this guide, your agent can delegate legal work to Relex — case analysis, document review, compliance checks, and professional marketplace — and return results to your user.

Prerequisites

  • A Relex account (sign up at relex.you)
  • An active case or the ability to create one
  • Your agent must serve an agent card at /.well-known/agent.json over HTTPS

Step 1: Discover Relex Capabilities

Fetch the Relex agent card to understand available skills:

curl https://relex.you/.well-known/agent.json

This returns the full agent card including skills (case_analysis, document_review, case_collaboration), supported content types, and authentication requirements.

Step 2: Register Your Agent

2a. Generate a Registration Token

The Relex user generates a token from their account settings, or your system calls the API:

curl -X POST https://relex.you/v1/agents/registration-token \
  -H "Authorization: Bearer "

2b. Self-Register

Your agent registers itself using the token:

curl -X POST https://relex.you/v1/agents/register \
  -H "Content-Type: application/json" \
  -d '{
    "registration_token": "token_from_step_2a",
    "agent_card_url": "https://your-agent.com/.well-known/agent.json"
  }'

Save the returned shared_api_key securely.

Step 3: Authenticate

Exchange the API key for a bearer token:

curl -X POST https://relex.you/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"api_key": "rlx_sk_your_key"}'

Use the returned bearer_token for all subsequent requests. Tokens last 1 hour.

Step 4: Create a Case

curl -X POST https://relex.you/v1/cases \
  -H "Authorization: Bearer " \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Employment Contract Review",
    "description": "Review a standard employment contract for compliance issues"
  }'

Note the returned caseId.

Step 5: Interact with the Agent

Send a task to the Relex agent via the SSE streaming endpoint:

curl -N -X POST https://relex.you/v1/agent \
  -H "Authorization: Bearer " \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "session-uuid-1",
    "seedPhase": {"phaseId": "phase-uuid-1"},
    "containerId": "",
    "containerType": "case",
    "requestType": "eval_req",
    "prompt": "This is an employment contract for a software engineer in Germany. Please evaluate the case complexity."
  }'

The response is an SSE stream. Key events:

  • status — processing updates
  • content_chunk — streamed text
  • direct_response — complete response JSON
  • phase_end — processing complete

Step 6: Parse SSE Responses

SSE events follow this format:

event: status
data: {"type": "processing"}

event: content_chunk
data: {"text": "Based on my analysis..."}

event: direct_response
data: {"response": "...", "tier": 2, "tierName": "Mid"}

event: phase_end
data: {"phaseId": "phase-uuid-1", "status": "committed"}

Handling Token Refresh

Bearer tokens expire after 1 hour. Implement automatic re-exchange:

import time

class RelexAuth:
    def __init__(self, api_key, base_url="https://relex.you"):
        self.api_key = api_key
        self.base_url = base_url
        self.token = None
        self.expires_at = 0

    def get_token(self):
        if self.token and time.time() < self.expires_at - 300:
            return self.token

        resp = httpx.post(f"{self.base_url}/v1/auth/token",
                         json={"api_key": self.api_key})
        data = resp.json()
        self.token = data["bearer_token"]
        self.expires_at = data["expires_at"]
        return self.token

Error Handling

Always check for error events in the SSE stream:

event: error
data: {"error": "Unauthorized", "message": "Token expired"}

Common errors:

  • 401 — Token expired. Re-exchange API key.
  • 403 — Insufficient permissions for this case.
  • 404 — Case not found.
  • 429 — Rate limit exceeded. Back off and retry.

Health Checks

Periodically verify your agent connection:

curl https://relex.you/v1/agents//health \
  -H "Authorization: Bearer "

Returns {"status": "healthy"} if your agent card is accessible, or {"status": "unhealthy", "error": "..."} if not.