Valar

API Documentation

Connect your agents to Valar

Interactive Docs

Getting Started

The Valar API lets you register agents, log events, track inter-agent messages, collect feedback, and monitor usage. Any agent you build — regardless of language or framework — can connect by making standard HTTP requests.

Quick start in 3 steps

  1. Get your API key — set API_KEY in your .env file and pass it as the X-API-Key header with every request.
  2. Register your agent — POST to /agents with a name and type.
  3. Start logging events — POST to /events each time something noteworthy happens.
bash
# 1. Register your agent
curl -X POST http://localhost:8100/agents \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-agent",
    "type": "assistant",
    "icon": "🤖",
    "platform": "python"
  }'

# 2. Log an event (use the agent id from step 1)
curl -X POST http://localhost:8100/events \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "<agent-uuid>",
    "event_type": "task_completed",
    "source": "agent_core",
    "level": "info",
    "payload": {"task": "summarize_meeting"}
  }'

Authentication

All endpoints except /health require the X-API-Key header. Requests without a valid key receive 401 Unauthorized.

http
GET /agents HTTP/1.1
Host: localhost:8100
X-API-Key: your-api-key-here

Generating a key

bash
openssl rand -hex 32

Add the generated value as API_KEY in your .env file. The same key must be sent by every client connecting to the API.

Rate limiting

The API enforces a default rate limit of 100 requests per minute per IP. Exceeding this returns 429 Too Many Requests.

Agents

Register, list, update, and manage your agents. Each agent has a unique name, type, status, and optional metadata.

Events

Events are the primary telemetry primitive. Every meaningful action your agent performs should be logged as an event.

Event fields

  • event_type — what happened (e.g. task_completed, api_call)
  • source — which subsystem emitted it (e.g. scheduler, slack)
  • level — info | warning | error | critical
  • trace_id — flat correlation ID across related events
  • parent_event_id — hierarchical linking for sub-tasks
  • payload — arbitrary JSON with extra context

Agent Messages

Log and query inter-agent communication. Useful for tracing how agents collaborate on tasks.

Feedback

Collect user feedback on agents, events, or messages. Feedback powers the satisfaction metrics on the dashboard.

Usage & Costs

Record and query token usage, API call counts, latency, and cost metrics per agent.

Python SDK

The project includes a Python SDK (in the sdk/ directory) for async agent integration. It wraps every API endpoint with type-safe methods, automatic retries, and idempotent agent registration.

Installation

bash
# From your agent project, install the SDK dependencies
pip install httpx pydantic

Then copy or symlink the sdk/ directory into your project, or add it to your Python path.

Basic usage

python
from sdk import AgentManagementClient

async with AgentManagementClient(
    base_url="http://localhost:8100",
    api_key="your-api-key",
) as client:
    # Register (idempotent — returns existing agent on conflict)
    agent = await client.register_agent(
        "my-bot",
        type="assistant",
        icon="🤖",
        platform="python",
        description="My first agent",
    )

    # Log events
    await client.log_event(
        agent.id,
        "task_started",
        source="scheduler",
        payload={"job": "daily_report"},
    )

    # Fire-and-forget (non-blocking, errors suppressed)
    client.log_event_fire_and_forget(
        agent.id,
        "heartbeat",
        source="health_check",
    )

    # Batch events
    await client.log_events_batch([
        {"agent_id": str(agent.id), "event_type": "step_1", "level": "info"},
        {"agent_id": str(agent.id), "event_type": "step_2", "level": "info"},
    ])

    # Inter-agent messaging
    other = await client.register_agent("summarizer", type="analyst", icon="📊", platform="python")
    await client.send_message(
        agent.id,
        other.id,
        "request",
        payload={"task": "summarize"},
    )

    # Feedback
    await client.submit_feedback(
        "agent", str(agent.id), "thumbs_up", rating=5,
    )

    # Cleanup old events
    result = await client.cleanup_events(30, agent_name="my-bot")
    print(f"Deleted {result.deleted} old events")

Error handling

python
from sdk.exceptions import (
    AgentManagementError,  # Base exception
    AuthenticationError,   # 401
    NotFoundError,         # 404
    ConflictError,         # 409 (duplicate agent name)
    ValidationError,       # 422
    ServerError,           # 5xx
)

try:
    agent = await client.register_agent("my-bot", ...)
except ConflictError:
    # Agent already exists — register_agent handles this
    # automatically, but you can catch it if needed
    pass
except AuthenticationError:
    print("Check your API key")
except AgentManagementError as e:
    print(f"API error: {e}")

SDK methods reference

MethodDescription
register_agent()Register or get existing agent
list_agents()List agents with filters
get_agent()Get agent by ID
update_agent()Update agent fields
delete_agent()Delete agent
log_event()Log a single event
log_event_fire_and_forget()Non-blocking event log
log_events_batch()Log up to 500 events
list_events()Query events with filters
cleanup_events()Delete old events
send_message()Log inter-agent message
list_messages()Query messages
submit_feedback()Submit feedback
list_feedback()Query feedback
health()Health check (no auth)