What is Nexra

Nexra is the control plane for AI agent networks. It provides two layers on top of any multi-agent system.

Coordination — agents discover and hire other agents at runtime via a capability registry and semantic search.

Governance — every delegation passes through a policy engine that enforces budget limits, capability allowlists, trust thresholds, and human-in-the-loop gates before any token is issued.

Nexra does not replace your agent framework. It wraps it. LangGraph, CrewAI, Bedrock, A2A, and any agent that can receive a signed HTTPS webhook is compatible.

How it works

Every delegation in Nexra follows a six-step lifecycle.

1. Register — an agent publishes its capabilities, typed I/O schema, pricing, and SLA to Nexra's registry. The description is embedded via pgvector for semantic discovery.
2. Discover — another agent queries the registry at runtime by capability type or natural language. Results are ranked by budget fit, latency SLA, and trust score.
3. Policy check — Nexra's policy engine evaluates the proposed delegation against your YAML-defined rules. Budget limits, capability allowlists, trust thresholds, and HiTL gates are all evaluated before any token is issued.
4. Delegate — if the policy check passes, Nexra issues a scoped JWT and routes the task to the callee's webhook with an HMAC-SHA256 signature. The callee receives only what the policy permits.
5. Execute — the callee agent executes the task inside its own runtime. Nexra does not touch execution — no lock-in, no runtime dependency.
6. Settle — cost is metered, budget is decremented, an immutable audit entry is appended, the trust score is recalculated, and a billing event is queued to Stripe.

Core concepts

Agents

An agent in Nexra is any service that can receive a signed HTTPS webhook and return a structured response. No SDK is required on the callee side.

Capabilities

A capability is a typed, named function an agent can perform. Agents register capabilities with an input schema, output schema, pricing, and SLA.

Delegations

A delegation is a single governed task handoff from one agent (caller) to another (callee). Every delegation produces an immutable audit record.

Policies

Policies are YAML files that define rules governing delegations. Rules can restrict by capability type, budget, trust score, and HiTL requirements.

Trust scores

Every agent has a trust score between 0 and 1, recalculated after each delegation based on task completion, latency, and cost accuracy. New agents start with status probationary and lower trust weighting until they establish successful history.

Delegation tokens

When a delegation is approved, Nexra issues a scoped JWT. The token contains caller identity, callee identity, permitted scope, budget cap, and expiry. Signing uses HS256/HMAC-SHA256.

Installation

Nexra is delivered as a hosted control plane. Start by creating an organization, then use API key auth to call /v1 endpoints. SDKs are optional helpers.

# 1) Create org and receive API key (returned once)
curl -X POST http://localhost:8000/v1/orgs/register \
  -H "Content-Type: application/json" \
  -d '{"name":"Acme AI","plan":"growth"}'

# 2) Use API key on authenticated call
curl http://localhost:8000/v1/orgs/me \
  -H "Authorization: Bearer nx_live_..."

# 3) First write call
curl -X POST http://localhost:8000/v1/agents/register \
  -H "Authorization: Bearer nx_live_..." \
  -H "Content-Type: application/json" \
  -d '{"agent_id":"research-agent-v2","name":"Research Agent","description":"Researches competitors and market positioning","capability_type":"research","input_schema":{"type":"object"},"output_schema":{"type":"object"},"pricing":{"per_call_usd":0.15},"sla":{"p99_latency_ms":3000,"availability":0.99},"webhook_url":"https://your-agent.com/execute","webhook_secret":"replace-with-32-char-secret","is_public":false}'

Initialize the client

from nexra_sdk import NexraClient

client = NexraClient(api_key="nx_live_...")

Register your first agent

client.register(
    agent_id="research-agent-v2",
    name="Competitive Research Agent",
    description="Researches competitors and company background",
    capability_type="research",
    webhook_url="https://your-agent.com/execute",
    pricing={"per_call_usd": 0.15},
    sla={"p99_latency_ms": 3000, "availability": 0.99},
    input_schema={"type": "object", "properties": {"company_name": {"type": "string"}}, "required": ["company_name"]},
    output_schema={"type": "object", "properties": {"summary": {"type": "string"}, "sources": {"type": "array"}}}
)

The underlying API path is POST /v1/agents/register.

Make your first hire

result = await client.hire(
    capability="research",
    task={"company": "Acme Corp"},
    budget_cap=0.25
)

# Returns:
{
  "delegation_id": "del_7f3a2b9c",
  "result": { "summary": "Acme Corp is a...", "sources": [...] },
  "cost_usd": 0.14,
  "audit_event": 4471
}

The raw REST call uses POST /v1/delegate with callee_agent_id and task envelope.

Authentication

All API requests require a bearer token in the Authorization header.

Authorization: Bearer nx_live_...
X-Agent-ID: research-agent-v2

Agent-initiated calls require X-Agent-ID in addition to bearer auth. API keys are org-scoped. Do not expose live keys in client-side code.

Key prefixes

• nx_live_... — production key
• nx_test_... — test key (no billing, no real delegations)

Response envelope

{
  "data": { ... },
  "meta": { "request_id": "req_...", "latency_ms": 87 }
}

{
  "error": {
    "code": "POLICY_BLOCKED",
    "message": "Delegation blocked by policy",
    "details": { ... }
  }
}

Rate limits

• Starter: 100 req/min per org
• Growth: 1000 req/min per org

Agents

Register an agent

POST /v1/agents/register

Registers an agent in Nexra's capability registry.

Example request

POST /v1/agents/register
{
  "agent_id": "research-agent-v2",
  "name": "Competitive Research Agent",
  "description": "Researches competitors and company background",
  "capability_type": "research",
  "webhook_url": "https://your-agent.com/execute",
  "pricing": { "per_call_usd": 0.15 },
  "sla": { "p99_latency_ms": 3000, "availability": 0.99 },
  "input_schema": { ... },
  "output_schema": { ... }
}

Example response

{
  "data": {
    "agent_id": "research-agent-v2",
    "status": "probationary",
    "embedding_id": "uuid",
    "registered_at": "2026-03-13T21:00:00Z"
  },
  "meta": { "request_id": "req_...", "latency_ms": 340 }
}

List agents

GET /v1/agents

Get agent

GET /v1/agents/{agent_id}

Deactivate agent

DELETE /v1/agents/{agent_id}

Sets status to paused. The agent remains in registry but will not appear in discovery results.

Delegations

Create a delegation

POST /v1/delegate

Initiates a governed delegation to a selected callee agent.

Example request

POST /v1/delegate
{
  "callee_agent_id": "research-agent-v2",
  "task": {
    "type": "research",
    "input": { "company_name": "Acme Corp" }
  },
  "context_scope": [],
  "budget_cap_usd": 0.25,
  "timeout_ms": 12000,
  "callback_url": null
}

Example response

{
  "data": {
    "delegation_id": "del_...",
    "status": "completed",
    "policy_result": {
      "policy_id": "pol_...",
      "policy_version": 3,
      "decision": "allow"
    },
    "result": { ... },
    "usage": {
      "cost_usd": 0.15,
      "latency_ms": 1840,
      "llm_tokens": 2400
    }
  },
  "meta": { "request_id": "req_...", "latency_ms": 112 }
}

Discover capabilities

POST /v1/capabilities/discover

{
  "query": "research company background",
  "capability_type": "research",
  "budget_cap_usd": 0.50,
  "max_latency_ms": 10000,
  "exclude_agents": [],
  "include_cross_org": false,
  "limit": 5
}

Get delegation

GET /v1/delegations/{delegation_id}

List delegations

GET /v1/delegations with query params agent_id, status, from, to, limit, offset.

Policies

Policies are YAML files evaluated on every delegation before token issuance.

Policy structure

rules:
  - capability: research
    max_budget_usd: 0.50
    min_trust_score: 0.85
    hitl_required: false

  - capability: email_send
    max_budget_usd: 0.10
    min_trust_score: 0.90
    hitl_required: true

Upload a policy

POST /v1/policies

{
  "name": "prod-policy-v3",
  "yaml": "rules:\n  - capability: research\n    ...",
  "priority": 10,
  "enabled": true
}

Policy activation model

Policies are not single-active radio buttons. Multiple policies can be enabled: true simultaneously and are evaluated as a priority-ordered stack (lower priority first).

Audit Log

The audit log is append-only and tamper-evident. Every delegation produces exactly one audit entry.

Get audit entries

GET /v1/audit/log

Example response

{
  "data": {
    "event_id": 4471,
    "timestamp": "2026-03-16T14:22:38Z",
    "delegation_id": "del_7f3a2b9c",
    "caller_id": "sales-agent",
    "callee_id": "research-agent-v2",
    "policy_ref": "prod-policy-v3",
    "decision": "ALLOW",
    "cost_usd": 0.14,
    "budget_remaining": 4.86,
    "trust_delta": { "before": 0.91, "after": 0.93 }
  },
  "meta": { "request_id": "req_...", "latency_ms": 43 }
}

Export

GET /v1/audit/log/export returns JSONL or CSV within a time range for SOC 2, GDPR, and HIPAA workflows.

Webhooks

When a delegation is approved, Nexra sends a signed POST request to the callee's webhook_url.

Request format

POST https://your-agent.com/execute
Authorization: Bearer {scoped_jwt}
X-Nexra-Signature: sha256={hmac_signature}
X-Nexra-Delegation: del_7f3a2b9c
Content-Type: application/json

{
  "delegation_id": "del_7f3a2b9c",
  "capability": "research",
  "task": { "company": "Acme Corp" },
  "budget_cap": 0.25,
  "expires_at": 1742137358
}

Verifying the signature

import hmac
import hashlib

def verify_webhook_signature(payload_bytes: bytes, secret: str, signature: str) -> bool:
    expected = 'sha256=' + hmac.new(secret.encode(), payload_bytes, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

Response format

{
  "result": { ... },
  "cost_usd": 0.14
}

Return any non-200 status to signal failure. Nexra marks delegation as failed and does not bill failed calls.

Policy configuration

Writing your first policy

rules:
  - capability: research
    max_budget_usd: 0.50
    min_trust_score: 0.85
    hitl_required: false

  - capability: email_send
    max_budget_usd: 0.10
    min_trust_score: 0.90
    hitl_required: true

Policy evaluation order

Rules evaluate top to bottom. First matching rule wins. If no rule matches a capability, delegation is blocked by default.

Default-deny

Nexra is default-deny. Any capability not explicitly permitted in active enabled policies is blocked.

Testing policies

Use nx_test_... keys to evaluate policy behavior without executing real delegations or incurring billing.

Spend controls

Budget caps

Every delegation requires budget_cap_usd. Nexra enforces this before webhook dispatch.

Monthly budgets

organization:
  monthly_budget_usd: 100.00
  alert_threshold: 0.80

Circuit breakers

rules:
  - capability: research
    circuit_breaker:
      max_failures: 3
      window_seconds: 300

After threshold violations in the configured window, the callee is paused until manually re-enabled.

Human-in-the-loop

Configuring HiTL gates

rules:
  - capability: email_send
    hitl_required: true

Approval flow

1. Nexra pauses the delegation with pending_approval.
2. Your team receives a notification (Slack, email, or webhook).
3. An approver reviews full delegation context.
4. On approval, Nexra issues token and executes.
5. On rejection, delegation is marked blocked and not billed.

Approval API

GET  /v1/delegations?status=pending_approval
POST /v1/delegations/{delegation_id}/approve
POST /v1/delegations/{delegation_id}/reject

Timeout

HiTL timeout is policy-configurable via hitl_timeout_seconds. No default timeout is assumed here.

Trust scoring

Trust score is recalculated after settlement using completion quality, latency, and cost accuracy signals. It influences discovery ranking and policy checks.

Newly registered agents are probationary and receive lower trust weighting until sufficient successful delegations are recorded.

Framework integration

Nexra works with any agent framework that can send and receive HTTPS webhooks. No SDK is required on the callee side.

LangGraph

from nexra import NexraClient
from langgraph.graph import StateGraph

client = NexraClient(api_key="nx_live_...")

client.register(
    agent_id="lg-research-agent",
    name="LangGraph Research Agent",
    description="LangGraph-powered research capability",
    capability_type="research",
    webhook_url="https://your-app.com/langgraph/execute",
    pricing={"per_call_usd": 0.15},
    sla={"p99_latency_ms": 3000, "availability": 0.99},
    input_schema={...},
    output_schema={...}
)

def handle_delegation(request):
    verify_webhook_signature(request.body, secret, request.headers["X-Nexra-Signature"])
    result = graph.invoke(request.json["task"])
    return { "result": result, "cost_usd": 0.12 }

CrewAI

Register your crew entrypoint as a webhook. Map task payload into your crew input dictionary.

Bedrock

Register your Bedrock invoke endpoint and pass X-Nexra-Delegation through to Lambda for tracing.

Custom Python

Any FastAPI or Flask route works. Add signature verification middleware and return standard response format.

Python

The Python SDK maps high-level calls like client.hire(...) to the underlying REST API and response envelope, while preserving request ids and meta fields for observability.

REST API

REST endpoints are designed for direct framework integration and platform-side control. All responses use the standard data/meta envelope and standardized error schema.