Client Integration

In the code that calls your agent, replace the agent URL with the Convoy proxy URL. This is the only change needed on the client side.

What to change

Before	After
Send to your agent URL directly	Send to the Convoy proxy URL from agent settings
—	Add `Session-ID` header
—	Add `Authorization: Bearer <secret>` header

Proxy URL: Get this from your agent settings in the Convoy platform (format: {org}--{agent}.proxy.convoylabs.com)
Session-ID: A unique identifier for this session. Alphanumeric, hyphens, underscores, and dots. Max 255 characters. Convoy uses this to route the same session to the same version consistently.
Authorization: The shared secret from your agent settings, passed as a bearer token. Store it as an environment variable.
Body: Unchanged — send whatever your agent expects.

Convoy routes the request to the correct version (stable or test) and forwards it to your agent backend.

Code examples

const response = await fetch(process.env.CONVOY_PROXY_URL!, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Session-ID": sessionId,
    "Authorization": `Bearer ${process.env.CONVOY_SECRET}`,
  },
  body: JSON.stringify({ input: userMessage }),
});

import httpx

response = await httpx.AsyncClient().post(
    os.environ["CONVOY_PROXY_URL"],
    headers={
        "Session-ID": session_id,
        "Authorization": f"Bearer {os.environ['CONVOY_SECRET']}",
    },
    json={"input": user_message},
)

Environment variables used:

CONVOY_PROXY_URL — the proxy URL from your agent settings
CONVOY_SECRET — the shared secret from your agent settings

Overview

Integration

Platform

Client Integration

Client Integration

What to change

Code examples

​Client Integration

​What to change

​Code examples

Client Integration

What to change

Code examples