Build a chat app

The pattern is four calls: create one instance per user at signup, start one session per chat thread, list sessions for the sidebar, and fetch one session for the open thread.

hermes-chat: this guide as a working app

Everything on this page, runnable: create instances from a table, stream replies token by token, list and reopen threads, cancel a turn. Express plus vanilla JS, no build step. Clone it, add your key, npm start.

One key, two base URLs

Two base URLs, one key, two headers: https://api.agent37.com manages instances and takes the key as Authorization: Bearer; each instance serves its own chat API at https://{instanceId}.agent37.app (the id is the hostname) and takes the same key as X-Agent37-Key, leaving Authorization free for your own app. See Core concepts.

The snippets below use a small shorthand client so the calls stay readable. api is the hosting API; agentOf(id) is one user’s agent.

node

const HOSTING_HEADERS = {
  Authorization: `Bearer ${process.env.AGENT37_API_KEY}`,
  "Content-Type": "application/json",
};

const AGENT_HEADERS = {
  "X-Agent37-Key": process.env.AGENT37_API_KEY,
  "Content-Type": "application/json",
};

function makeClient(base, headers) {
  return {
    get: (path) => fetch(base + path, { headers }).then((r) => r.json()),
    post: (path, body) =>
      fetch(base + path, {
        method: "POST",
        headers,
        body: JSON.stringify(body ?? {}),
      }).then((r) => r.json()),
  };
}

const api = makeClient("https://api.agent37.com", HOSTING_HEADERS);
const agentOf = (id) => makeClient(`https://${id}.agent37.app`, AGENT_HEADERS);

The shape of it

One instance per user, on signup

When a user signs up, create one instance for them, tagged with your own user id. That instance is their agent from then on.

node

const inst = await api.post("/v1/instances", {
  user: "u_882",
  name: "chat-u_882",
  budget: { credit_micros: 1000000 },
});

await db.users.update("u_882", { instanceId: inst.id });
// inst.id is bare, e.g. "ab12cd34ef", and doubles as the hostname:
// https://ab12cd34ef.agent37.app

Omitting template gives you agent37-hermes, the default, on the default 2 vCPU / 4 GB RAM / 6 GB disk shape, billed from your workspace wallet (see Billing). Each create uses the template’s newest published image; for a fleet where every signup must get the identical image, pass a version-pinned template instead ("template": "agent37-hermes@<tag>"). The budget.credit_micros field grants one-time managed-spend headroom so the agent’s LLM calls work from the first message; without it the per-instance budget defaults to $0.The call is synchronous and returns 201 with status: "running": the instance’s computer is up. The agent inside is still booting — usually seconds, but up to a few minutes on a cold host — so before the first message poll GET /v1/health on the instance URL until it answers with "ok": true (see Health and version). Store inst.id on the user row.

A session per chat thread

Each thread is a session on the user’s instance. Send the first turn to the instance URL with no session_id; the reply mints one. Store it on your thread row, then send session_id plus the new input on every later turn. The session keeps the full history, so you never resend a transcript.

node

const agent = agentOf(user.instanceId);

// new thread: first turn, no session_id
const first = await agent.post("/v1/responses", {
  input: "Research the top 3 EV makers, write a memo.",
});
await db.threads.create({ userId: "u_882", sessionId: first.session_id });
// first.session_id, e.g. "7f3e0b6c52a949d2b1c4a8e9d0f31726"

// later turns: session_id and the new input only
const reply = await agent.post("/v1/responses", {
  session_id: thread.sessionId,
  input: "Make it shorter, add a quote.",
});
render(reply.output_text);

Stream every reply so the UI fills in as the agent reasons, calls tools, and writes. Set stream: true and read the Server-Sent Events; see Streaming for the full event list and a client parser.

List threads for the sidebar

GET /v1/sessions on the instance URL lists the harness’s sessions, newest first, without history.

node

const { agent, data } = await agentOf(user.instanceId).get("/v1/sessions");
// Hermes: [{ id, title, model, message_count, started_at, last_active, preview }]
// timestamps are epoch milliseconds

On Hermes the list already carries a title, and you can set it with PATCH /v1/sessions/{id} ({ "title": "..." }) — the first user message usually makes a good default. Harnesses that do not store a title answer 405; for those, keep titles in your own database keyed by session_id.

Load a thread when it opens

GET /v1/sessions/{id} returns the session with its full transcript in history, in order.

node

const session = await agentOf(user.instanceId).get(
  `/v1/sessions/${thread.sessionId}`
);
// session.history: [{ id, session_id, role, content, thinking?, created_at }]
// session.active_response_id: the running response's id, or null when idle

Render each message by role (user, assistant, or system). If active_response_id is set, a turn is still running and its messages are not in history yet — reattach with GET /v1/responses/{id}/stream to render it live (this is how a page reload mid-turn recovers the stream). When a user deletes a thread, DELETE /v1/sessions/{id} removes it; see Sessions.

Handle a busy session

A session runs one response at a time. Posting a new turn while one is in flight returns 409:

{
  "error": {
    "code": "session_busy",
    "message": "A response is already running on this session.",
    "hint": "Reattach with GET /v1/responses/{response_id}/stream, cancel it, or start another session.",
    "response_id": "c91d2a7e84f04b6f9a3d5e1c0b87f4a2"
  }
}

error.response_id is the running response, so even a client that lost its state can reattach to it or cancel it. Three good ways to handle it in a chat UI:

Disable the composer while a turn runs, and re-enable it when the reply arrives (the non-streaming call returning, or the terminal streaming event).
Offer a stop button that calls POST /v1/responses/{id}/cancel on the instance URL. With stream: true the first event, response.created, hands you the response id immediately, which is what makes the button possible. Cancel is best effort: the response ends with status: "cancelled", and whatever the agent already did is not undone.
Reattach instead of erroring: on a 409, GET /v1/responses/{response_id}/stream replays the running turn from its start and follows it live. If error.response_id is absent (a rare race, or an older gateway), read active_response_id from GET /v1/sessions/{id} instead.

The hermes-chat example wires up the first two: the composer locks while a turn is in flight, and the stop button cancels it. Other threads are unaffected: each session has its own lock, so one user can run turns in several threads at once.

Get started

Build with Agent37

Hosting API

Agent API

Reference

hermes-chat: this guide as a working app

One key, two base URLs

The shape of it

Handle a busy session

hermes-chat: this guide as a working app

​One key, two base URLs

​The shape of it

​Handle a busy session

One key, two base URLs

The shape of it

Handle a busy session