Connect an agent

To connect an agent you change two things: the base URL it sends requests to, and the key it sends. Everything else, including your prompts, tools and streaming, stays the same.

What you needCopy Anchor Link

• Your gateway URL. For Clovie SaaS it is https://gateway.clovie.io. For a self-hosted install, ask your administrator.
• An agent key for the agent, from AI Governance → Agents → Registry. See Agents.
• A model your organization has enabled in AI Governance → Models → Catalog.

AuthenticationCopy Anchor Link

Send the agent key as a bearer token:

Authorization: Bearer YOUR_CLOVIE_AGENT_KEY

For the Messages format, the gateway also accepts the key in the x-api-key header, which is what Anthropic SDKs send.

Chat CompletionsCopy Anchor Link

Works with OpenAI SDKs and most agent frameworks.

from openai import OpenAI

client = OpenAI(base_url="https://gateway.clovie.io/v1", api_key="YOUR_CLOVIE_AGENT_KEY")

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Summarize our refund policy."}],
)

import OpenAI from "openai";

const client = new OpenAI({ baseURL: "https://gateway.clovie.io/v1", apiKey: process.env.CLOVIE_API_KEY });

const response = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: "Summarize our refund policy." }],
});

MessagesCopy Anchor Link

Works with Anthropic SDKs and tools built on them.

import anthropic

client = anthropic.Anthropic(base_url="https://gateway.clovie.io", api_key="YOUR_CLOVIE_AGENT_KEY")

message = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Summarize our refund policy."}],
)

Tools that read ANTHROPIC_BASE_URL and ANTHROPIC_API_KEY from the environment can be pointed at the gateway without code changes.

ResponsesCopy Anchor Link

The gateway also accepts the OpenAI Responses format at /v1/responses, with the same base URL and key as Chat Completions.

StreamingCopy Anchor Link

Streaming works in every format. Ask for it the way your SDK normally does, for example stream=True. If a policy or budget stops a request while it is streaming, the stream ends with an error event that says why.

Group calls into one runCopy Anchor Link

An agent task often makes several model calls. To see them together as one run in AI Governance → Activity → Agent runs, send the same x-clovie-run-id header value on each call of the task.

The Clovie SDK for PythonCopy Anchor Link

The Clovie SDK wraps the gateway and handles approvals for you: when a policy holds a request for approval, the SDK waits for the decision and then retries.

pip install clovie-sdk

from clovie import ClovieClient

client = ClovieClient()  # reads CLOVIE_API_KEY and CLOVIE_GATEWAY_URL

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Summarize our refund policy."}],
)

Set CLOVIE_API_KEY to the agent's key. CLOVIE_GATEWAY_URL defaults to https://gateway.clovie.io; set it if you use a self-hosted install.

When a request is stoppedCopy Anchor Link

If the gateway stops a request, the agent receives a standard error response with a status code, a machine-readable code and a message that explains why. The most common ones:

Signed-in users can find the full list, with what to do for each, in the error code reference inside the product.