BYOA Runtime Contract

Platform Knowledge resources

Agent callers can list the public Platform Knowledge catalog with GET /api/v1/knowledge/index and load a full card with GET /api/v1/knowledge/documents/{documentKey}. Both accept a BCP-47 locale; unavailable locales fall back to English and report localeFallback. These resources are global, read-only, and reject user-session callers.

BYOA (Bring Your Own Agent) uses an external runtime connected to Arinova Chat. The owner supplies and operates the model provider, credentials, deployment, availability, and provider-side cost controls.

SDK ownership

The supported SDK is @arinova-ai/agent-sdk, maintained in arinova-ai/arinova-packages under packages/agent-sdk. This repository owns the server and web protocol surfaces, not a second SDK implementation. Do not recreate or vendor an arinova_agent_sdk tree under libs/python-sdk; protocol or SDK changes must be coordinated with the package repository.

Billing boundary

Dispatching a chat message to an external BYOA runtime does not deduct the platform Agent per-message charge. The BYOA owner pays their model provider or self-hosting costs directly. Platform-hosted Agents remain subject to the selected platform model tier and its per-message point charge.

The task envelope includes billingOwnerUserId. That field identifies the Agent owner whose authorization and billing context applies if the runtime later invokes a platform capability that explicitly has a charge. It is not a request to charge the task itself, and receivers must not infer a per-message charge from its presence.

Protocol source of truth

The server-to-runtime task shape is defined in libs/shared/src/types/ws/agent.ts and built by apps/rust-server/src/ws/commands/chat/dispatch/task_payload.rs. Keep both in sync with the SDK package when changing the wire contract.

Agent memory payload

agentMemories, when present, is available to external runtimes through TaskContext.raw. Its row shape remains { id, category, summary, detail }. The rows are the exact thresholded and budgeted selection rendered into the task’s memory XML, but every structured row retains its full detail even when the XML uses progressive disclosure for details longer than 160 characters. External runtimes must choose one rendering path: independently rendering agentMemories while also forwarding the server-provided memory XML duplicates the same selected memories and defeats the XML token saving. Runtimes must not assume this field is an unfiltered memory catalog. The server performs one bounded embedding attempt and one retrieval query per turn, falling back to keyword-only retrieval when embedding is unavailable.

The external SDK was audited at arinova-packages commit 086ee5cef42a: TaskContext does not declare a typed agentMemories property, the client preserves the complete server frame in raw, and the SDK test covers raw passthrough. Filtering changes therefore do not change the wire shape.