REST API / Local Engine

What you'll learn: How to integrate non-Python agents with Kyvvu using the local HTTP server (kyvvu serve).

---

kyvvu serve (local engine)

For agents written in JavaScript, Go, Rust, or any language, kyvvu serve runs the engine as a local HTTP server. Your agent makes HTTP calls to evaluate steps — same engine, same sub-millisecond policies, no Python needed in your agent code.

Start the server

pip install kyvvu
kyvvu serve --host 127.0.0.1 --port 8080 --agent-key my-agent

The server needs API credentials to fetch policies. Provide them via flags or environment variables:

export KV_API_URL=https://platform.kyvvu.com
export KV_API_KEY=KvKey-...
export KV_AGENT_KEY=my-agent
kyvvu serve

Endpoints

Method	Path	Purpose
GET	/health	Liveness probe — returns policy status.
POST	/evaluate	Preflight evaluation of an intended behaviour.
POST	/record	Record a completed step into task history.
POST	/end_task	Close a task — evict history and flush logs.
POST	/register_agent	Evaluate agent-registration policies.

Health check

curl http://127.0.0.1:8080/health

{
  "policy_count": 8,
  "last_fetch_at": "2026-04-29T10:00:00+00:00",
  "last_fetch_succeeded": true,
  "instance_id": "worker-3-a8f92",
  "ttl_remaining_seconds": 280.5
}

Evaluate a step

curl -X POST http://127.0.0.1:8080/evaluate \
  -H "Content-Type: application/json" \
  -d '{
    "intended": {
      "agent_id": "agent-123",
      "task_id": "task-abc",
      "scope": "step",
      "step_type": "step.model",
      "verb": "POST",
      "step_name": "chat_gpt-4o",
      "input": {"user_message": "Hello"}
    },
    "context": {
      "agent_id": "agent-123",
      "task_id": "task-abc",
      "environment": "production",
      "risk_classification": "limited"
    }
  }'

Response:

{
  "action": "allow",
  "risk_score": 0.0,
  "policies": [
    {
      "policy_id": 1,
      "name": "pii_in_request",
      "severity": "critical",
      "violated": false,
      "violation_details": null
    }
  ],
  "blocked": false
}

When a policy blocks, blocked is true and action is "block". The server always returns HTTP 200 for policy decisions — read the blocked field to decide whether to proceed.

Record a completed step

curl -X POST http://127.0.0.1:8080/record \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent-123",
    "task_id": "task-abc",
    "scope": "step",
    "step_type": "step.model",
    "verb": "POST",
    "step_name": "chat_gpt-4o",
    "input": {"user_message": "Hello"},
    "output": {"response": "Hi there!"}
  }'

Response: {"step": 1, "task_id": "task-abc"}

End a task

curl -X POST http://127.0.0.1:8080/end_task \
  -H "Content-Type: application/json" \
  -d '{"task_id": "task-abc"}'

Response: {"status": "ok", "task_id": "task-abc"}

Integration pattern

The typical flow for a non-Python agent:

1. POST /evaluate  → check if step is allowed
2. If blocked=false: execute the step
3. POST /record    → record the completed step with output
4. Repeat for each step
5. POST /end_task  → flush logs and clean up

---

Next steps

• kyvvu serve — CLI reference for the serve command

• Configuration Reference — all environment variables

• Architecture — why in-process evaluation is preferred