Bring Your Own Agent

​

How it works

1. You expose an OpenAI-compatible streaming chat-completions endpoint (POST {base_url}/chat/completions with stream: true).
2. You attach it to a scenario (custom_agent_config) or pass it per-meeting.
3. When a meeting starts, Waterr’s pipeline transcribes the participant, calls your endpoint with the running conversation, and speaks your streamed reply into the room.

​

Configuration

curl -X PUT https://api.waterr.ai/v1/scenarios/{scenario_id} \
  -H "Authorization: Bearer wai_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "custom_agent_enabled": true,
    "custom_agent_config": {
      "base_url": "https://agent.yourcompany.com/v1",
      "api_key": "sk-your-endpoint-key",
      "model": "support-bot-v3",
      "timeout_s": 10,
      "extra_headers": {"X-Tenant": "acme"}
    }
  }'

​

Endpoint contract

• Accept POST {base_url}/chat/completions with an OpenAI-shaped body: model, messages (the running meeting conversation, system prompt included), optional tools.
• Stream the reply as SSE chat.completion.chunk deltas (choices[0].delta.content), ending with data: [DONE].
• Answer fast. This is a live conversation: target first token ≤ 1.5s. Waterr masks slow turns with filler audio and retries once after timeout_s, but a sluggish endpoint ruins the conversational feel — that part of the latency budget is yours.

# pip install fastapi uvicorn
import json, time
from fastapi import FastAPI, Request
from fastapi.responses import StreamingResponse

app = FastAPI()

@app.post("/v1/chat/completions")
async def chat(request: Request):
    body = await request.json()
    reply_stream = my_agent.run(body["messages"])   # your existing agent loop

    def sse():
        for token in reply_stream:
            chunk = {
                "id": "chatcmpl-waterr", "object": "chat.completion.chunk",
                "created": int(time.time()), "model": body.get("model"),
                "choices": [{"index": 0, "delta": {"content": token},
                             "finish_reason": None}],
            }
            yield f"data: {json.dumps(chunk)}\n\n"
        yield 'data: {"choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}\n\n'
        yield "data: [DONE]\n\n"

    return StreamingResponse(sse(), media_type="text/event-stream")

​

Platform tools

​

Security

• Waterr never sends any internal credential to your endpoint — only the api_key you configured.
• base_url must be public HTTPS. URLs resolving to private, loopback, or link-local address space are rejected at meeting creation.
• Your api_key is encrypted at rest (AES-256-GCM) and masked in every API response.
• Embed meetings only ever use the scenario’s stored config — an embedded page can never inject its own agent endpoint.

​

Billing

​

Close the loop