Skip to content

Production checklist

What to have in place before an agent in production depends on Venkai.

Checklist

[ ] A dedicated vk_live_ key per service, stored in a secret manager
[ ] VENKAI_BASE_URL set explicitly to https://api.venkai.fr
[ ] Project keys pinned as constants (a typo silently creates a new project)
[ ] Client timeouts set on every call (e.g. 10 s)
[ ] Agent keeps working when Venkai is unreachable (degrade to no context)
[ ] 429 handled with Retry-After
[ ] limit sized to your prompt budget; client-side character budget applied
[ ] importance set deliberately, not left at the default everywhere
[ ] Write-side deduplication for agents that record on every loop
[ ] Full write → read round trip verified with the production key
[ ] External monitoring on /api/health
[ ] Scheduled GET /api/export if you need an independent copy

Keys

Practice Why
One key per service or agent fleet Rotate or revoke one without touching the others
Keys only in a secret manager or runtime env The raw key is shown once; it cannot be read back
Rotate with POST /api/auth/api-keys/{id}/rotate No grace period — deploy the new key first

Failure handling

Venkai is a dependency of your agent, not its host. Design so that a failed call costs context, not the task:

def venkai_context(project: str, task: str, limit: int = 5) -> list[dict]:
    try:
        r = requests.get(f"{BASE}/api/context/{project}/relevant",
                         headers=H, params={"query": task, "limit": limit},
                         timeout=10)
        if r.status_code == 429:
            return []                      # or wait Retry-After and retry once
        r.raise_for_status()
        return r.json()["memories"]
    except requests.RequestException:
        return []                          # degrade: run the task without memory

Writes have no idempotency key: if a request times out after reaching the server, retrying it can store the memory twice. When duplicates matter, check the list endpoint before retrying.

Limits

Limit Value
Rate, authenticated 300 requests / minute per client IP
Rate, anonymous 60 requests / minute per client IP
content length 1–8000 characters
List endpoint page size 200
Memories considered per ranked query Service limit, favouring recent memories — split very large projects (see Retrieval)

Monitoring

Signal Source
Availability GET /api/health from your monitoring
Request volume GET /api/usage
Store growth GET /api/projects → contexts per project
Retrieval latency Time it client-side; the API does not expose it

Security posture

In place:

  • Organization isolation on every read and write.
  • API keys stored hashed; the raw value is returned once.
  • Resources belonging to other organizations return 404, so responses cannot confirm that an id exists.
  • Rate limiting per client IP.
  • Memory content is not written to application logs.

Not available today — plan around it:

Absent Implication
Per-key scopes Any key can read and write everything in its organization
vk_test_ isolation A test key reads and writes real data
Single-memory delete Supersede with a PATCH; delete the organization to remove everything
SSO / SCIM Not implemented

Not production-ready

Do not build a production dependency on these:

Feature Status
/api/security/analyze, venkai_security_gate Experimental — unvalidated scoring; do not use as a blocking CI gate
/api/handoffs Experimental — a record, not a mechanism
venkai_client_accept / _deliver Experimental
Published benchmarks Planned — Evaluation