Hosted Hermes Agents

A hosted Hermes agent is a NousResearch Hermes instance that Divinci runs for you in its own isolated Cloudflare Sandbox container — one container per agent, addressed by a stable per-agent key. You get a tool-using, self-improving agent without operating a server, and divinci.hermesAgents is how you manage the fleet.

Each agent has:

• a model — a Divinci-paid platform model or a bring-your-own-key model,
• an optional persona (system prompt) applied to every turn,
• an optional linked Release whose knowledge base grounds every turn (RAG),
• an hsk- proxy key that lets any OpenAI-compatible client drive it.

Choosing a model

Platform models are hosted and paid for by Divinci — no provider key needed:

Model id	Notes
vertex_ai/gemini-2.5-flash	Default. Fast, tool-capable Gemini on Vertex AI.
vertex_ai/gemini-2.5-pro	Most capable Gemini.
cloudflare/@cf/meta/llama-3.3-70b-instruct-fp8-fast	Open-weight Llama on Cloudflare Workers AI.

Or bring your own key for openai, anthropic, openrouter, or gemini (Google AI Studio) with any <provider>/<model> id — e.g. anthropic/claude-sonnet-4-5. BYOK keys are field-encrypted at rest and never returned by the API: reads expose only the provider name and a hasProviderApiKey boolean.

Creating an agent

// Platform model — works immediately, no key required
const agent = await divinci.hermesAgents.create("ws_123", {
  title: "Support Bot",
  hermesModel: "vertex_ai/gemini-2.5-flash",
  systemPrompt: "You are a concise, friendly support agent.",
});

console.log(agent._id);         // agent id for the management API
console.log(agent.proxyApiKey); // hsk-… — for OpenAI-compatible clients

// BYOK — provider spend lands on your own account
const byok = await divinci.hermesAgents.create("ws_123", {
  title: "Claude Agent",
  hermesModel: "anthropic/claude-sonnet-4-5",
  provider: "anthropic",
  providerApiKey: process.env.ANTHROPIC_API_KEY!, // encrypted at rest
});

Creation is lazy — no container spins until the first chat, so an unused agent costs nothing. There is a per-workspace cap on agents (default 10).

Grounding an agent in a Release (RAG)

Link a Release and every turn retrieves relevant context from that Release’s knowledge base before the model answers. The agent keeps its own model and persona — the Release contributes only grounding content.

const grounded = await divinci.hermesAgents.create("ws_123", {
  title: "Docs-Grounded Agent",
  releaseId: "rel_abc123", // 24-hex release id in the same workspace
});

// Link, swap, or unlink later:
await divinci.hermesAgents.update("ws_123", grounded._id, { releaseId: "rel_def456" });
await divinci.hermesAgents.update("ws_123", grounded._id, { releaseId: "" }); // unlink

Where the context goes

Retrieved chunks are injected into the user message of each turn — Hermes’ own sanctioned context channel — so the agent’s system prompt stays byte-stable across turns and provider-side prompt caching keeps working. Retrieval is best-effort: if the knowledge base is briefly unavailable, the turn proceeds ungrounded rather than failing.

Chatting

const reply = await divinci.hermesAgents.chat("ws_123", agent._id, [
  { role: "user", content: "Summarize our refund policy." },
]);

console.log(reply.choices?.[0]?.message?.content);

The response is OpenAI-compatible. Each successful turn is metered as a small flat fee to the workspace wallet, escrowed before dispatch and refunded on any failure — you pay per successful turn.

Cold starts

A container that hasn’t chatted recently sleeps. The first turn after a sleep cold-boots it (typically 30–60 seconds). If the boot exceeds the server’s bounded warm-up window you’ll get HTTP 503 {"error": "agent_warming"} with a Retry-After header while the container keeps starting in the background — retry after ~30 seconds and the turn will go through. Nothing is billed for a 503.

Managing the fleet

const agents = await divinci.hermesAgents.list("ws_123");

const one = await divinci.hermesAgents.get("ws_123", agent._id);
// one.status: "provisioned" (never booted) | "active" | "stopped" (idle-reaped)

await divinci.hermesAgents.update("ws_123", agent._id, {
  hermesModel: "vertex_ai/gemini-2.5-pro",
  enabled: false, // disabled agents reject chat with 403
});

await divinci.hermesAgents.delete("ws_123", agent._id); // stops the container too

Idle containers auto-sleep after ~30 minutes and long-idle agents are marked stopped by a background sweep. Both are non-destructive — the next chat re-provisions transparently.

Connecting OpenAI-compatible clients

The proxyApiKey (hsk-…) works with any OpenAI-compatible client — including a locally-installed Hermes — via the per-agent proxy:

export OPENAI_BASE_URL="https://api.divinci.app/api/v1/hermes-proxy"
export OPENAI_API_KEY="hsk-your-agent-proxy-key"

The proxy resolves the agent from the key, server-side — there is no header or path a caller can set to reach a different tenant’s container. Rotate the key to revoke all clients holding the old one:

const rotated = await divinci.hermesAgents.regenerateKey("ws_123", agent._id);
console.log(rotated.proxyApiKey); // new hsk-…; the old key is dead

See also

• divinci hermes CLI commands — the same surface from your terminal.
• MCP tool catalog — hermes_* tools for agentic IDEs.
• Releases — the knowledge-base side of RAG grounding.