Client & HTTP API

One Foundry process serves everything over HTTP on 127.0.0.1:4141: a typed control plane for your own TypeScript code, an OpenAI-compatible API for existing SDKs and chat UIs, and an asynchronous run API for automation. All three drive the same persisted instances, conversations and runs, and every request shows up in the inspector.

Three ways to talk to Foundry

The typed client

createFoundryClient<FoundryRoutes>() is a thin, dependency-free fetch wrapper. FoundryRoutes is generated into .foundry/routes.d.ts by glove foundry dev/start, so foundry.agent("support") fails to compile if agents/support/agent.ts does not exist.

import { createFoundryClient } from "glove-foundry/client";
import type { FoundryRoutes } from "../.foundry/routes.js";

const foundry = createFoundryClient<FoundryRoutes>({
  baseUrl: process.env.FOUNDRY_URL ?? "http://127.0.0.1:4141",
  // Optional: only needed when foundry.application.ts sets requestAuthorization.
  authorization: {
    identifier: "foundry-api-token",
    headers: () => ({ authorization: `Bearer ${process.env.FOUNDRY_API_TOKEN}` }),
  },
});

// 1. Persist an instance of agents/support/agent.ts (the route is type-checked).
const support = await foundry.agent("support").create({
  id: "support-acme",
  workspaceId: "acme",
  context: { tenant: "acme", tier: "pro" },
});

// 2. Open a durable conversation owned by that instance.
const conversation = await foundry.createConversation(support.id, {
  title: "Order 1042",
});

// 3. Every message becomes a run. send() returns as soon as the run is queued.
const handle = await foundry.send(support.id, conversation.id, "Where is order 1042?");
console.log(`trace: http://127.0.0.1:4141/runs/${handle.id}`);

// 4. Wait for a terminal status: completed, failed or cancelled.
const run = await handle.wait({ timeoutMs: 120_000 });
if (run.status === "completed") {
  console.log(run.output?.value); // the final assistant text
} else {
  console.error(run.status, run.error);
}

Every method throws an Error whose message is the server's error field when the response is not 2xx. create throws if the instance id already exists — look it up with agentInstances("support") first if your script is re-runnable.

foundry.agent(route)

Returns exactly two functions bound to a definition route:

• create(options?) → POST /api/agent-instances with definitionId: route. Options: id, workspaceId (default "default"), context, installations, playbooks.
• request(request: FoundryRequest) → POST /api/agents/:route/runs, returning a FoundryRunHandle. You must pass agentId, conversationId and workspaceId; Foundry rejects the run unless the instance uses this route's definition, the conversation belongs to the instance and all three share the workspace. Over this endpoint message must be a non-empty string.

// continues scripts/ask-support.ts above (foundry, support, conversation)
const summary = await foundry.agent("support").request({
  agentId: support.id,
  conversationId: conversation.id,
  workspaceId: support.workspaceId,
  message: "Summarise this conversation for the ticket.",
  payload: { ticketId: "T-77" }, // reaches the agent as request.payload
});
await summary.wait();

For everyday chat, prefer send(agentId, conversationId, message, { payload?, context? }): it looks up the definition and workspace for you and accepts multimodal content parts.

Run handles

send, agent(route).request and handle.steer return a FoundryRunHandle:

Client method reference

Every public FoundryClient method, grouped by what it manages.

The client has no wrapper for /v1/*, /health/detailed, GET /api/agents or GET /api/transmissions; call those with fetch.

Native HTTP API

These are the routes the typed client and the inspector use. Request and response bodies are JSON. Errors are always { "error": "message" }: 401 from authorization, 404 for an unknown path or run, 413 for an oversized body, and 400 for everything else — including unknown instance, conversation or definition ids.

Live event streams

GET /api/events returns the latest 500 matching events as JSON (limit up to 5 000). Send Accept: text/event-stream and the same URL first replays matching retained events, then pushes new ones as they happen:

curl -N -H 'accept: text/event-stream' \
  'http://127.0.0.1:4141/api/events?runId=RUN_ID'

: glove-foundry

id: 412
data: {"id":"…","sequence":412,"timestamp":"…","type":"agent.text_delta","category":"model","agent":"support","runId":"RUN_ID","data":{"text":"Order 1042 "}}

• Each frame carries id: <sequence>. To resume after a disconnect, pass ?after=<last sequence>; the Last-Event-ID header is not read.
• A : heartbeat comment is written every 15 s. /api/events streams stay open; /v1/runs/:id/events streams close after the run's terminal event.
• Events live in memory (observability.maxEvents, default 10 000) and are not persisted across restarts. Durable history is the conversation store; see Inspector & WebChat.
• FoundryEvent fields: id, sequence, timestamp, type, category (agent, run, model, tool, extension, application, inbox, memory, mcp, activation, system, log), agent?, runId?, data. Events emitted inside an agent process are prefixed agent..

Health checks

GET /health returns FoundryHealth: { ok, execution, environment, activations, agents, capabilities, surfaces }. ok is true when the execution daemon, its environment and the activation scheduler all answer a ping; the last three fields are counts. GET /health/detailed adds connections and the full retained runs list, so keep it off public load-balancer probes. Both answer 200 when ok is true and 503 with the same body when it is false; client.health() returns the body either way. Both pass through requestAuthorization when it is configured.

/v1/runs automation API

Fire work from anything that can send HTTP, get a run id back immediately, and check on it later. Runs land in a durable conversation, so a nightly job can keep one conversation per job name.

An x-foundry-conversation-id request header overrides both keys. The response header always carries the real conversation id; send it back to continue.

# 1. Start a run. 202 Accepted; the body is the FoundryRun.
curl -si http://127.0.0.1:4141/v1/runs \
  -H 'content-type: application/json' \
  -d '{"model":"support-acme","input":"Check every open order for delays.","conversation_id":"nightly-audit","context":{"trigger":"cron"}}'

# 2. Poll it.
curl -s http://127.0.0.1:4141/v1/runs/RUN_ID

# 3. Or follow it live; the stream closes after run.completed / run.failed / run.cancelled.
curl -N -H 'accept: text/event-stream' http://127.0.0.1:4141/v1/runs/RUN_ID/events

# 4. Change direction, or stop.
curl -s -X POST http://127.0.0.1:4141/v1/runs/RUN_ID/steer \
  -H 'content-type: application/json' -d '{"input":"Only check orders placed this week."}'
curl -s -X POST http://127.0.0.1:4141/v1/runs/RUN_ID/stop

{
  "object": "foundry.capabilities",
  "protocols": {
    "native": true,
    "openaiChatCompletions": { "streaming": true, "multimodalInput": true },
    "openaiResponses": { "streaming": true, "multimodalInput": true },
    "runControl": {
      "create": true, "status": true, "events": true, "stop": true, "steer": true,
      "steeringMode": "interrupt-and-restart"
    },
    "approvals": { "list": true, "resolve": true, "default": "deny" }
  },
  "runtime": { "ok": true, "execution": true, "environment": true, "activations": true, "agents": 1, "capabilities": 3, "surfaces": 0 }
}

Request, run and result contracts

FoundryResult is { status: "completed" | "suspended", value, agentId, conversationId, workspaceId, suspension? }. For a normal model loop value is the final assistant message text; with a run or spawn handler it is whatever the handler returned, JSON-serialized. status is "suspended" with suspension: { commandId, wakeAt } when the agent put itself to sleep (see Playbooks, schedules & sleep).

Messages: Glove content parts

Foundry accepts exactly what Glove.processRequest accepts: a string, or an array of parts { type: "text" | "image" | "video" | "document", text?, name?, source?: { type: "base64" | "url", media_type, data?, url? } }. Media parts may carry a human-facing name. Inside the run, text parts are joined with newlines into the message text; a media-only message gets the text [multimodal message]. The whole history, including media, reaches lazy assembly as native Glove messages.

import { readFile } from "node:fs/promises";
// foundry, support and conversation as in the first example on this page

const invoice = (await readFile("invoice-1042.pdf")).toString("base64");

const handle = await foundry.send(support.id, conversation.id, [
  { type: "text", text: "The customer sent a photo of the box and the invoice." },
  {
    type: "image",
    name: "damaged-box.jpg",
    source: { type: "url", media_type: "image/jpeg", url: "https://example.com/damaged-box.jpg" },
  },
  {
    type: "document",
    name: "invoice-1042.pdf",
    source: { type: "base64", media_type: "application/pdf", data: invoice },
  },
]);

JSON bodies are capped at 1 MB (1 048 576 bytes) by default. Set server.messageBodyBytes in foundry.config.ts (an integer from 1 048 576 to 134 217 728) to accept larger base64 media. The raised limit applies only to message-bearing endpoints: POST /api/conversations/:id/messages, /api/runs/:id/steer, /v1/chat/completions, /v1/responses, /v1/runs and /v1/runs/:id/steer. Everything else, including /api/agents/:route/runs, stays at 1 MB.

Custom run handlers

Give a route deterministic behaviour — an order-status lookup, an ingestion step, a wrapper that post-processes the model's answer — by setting run on defineAgent (or exporting run from a convention module). It runs after lazy assembly with the assembled runnable and a handler context; its return value becomes run.output.value. Without a model, the agent is model-free: calling the standard loop throws, so the handler must not.

import { defineAgent } from "glove-foundry";
import { z } from "zod";

const Payload = z.object({ orderId: z.string() });

export default defineAgent({
  description: "Deterministic order-status endpoint; no model is configured",
  run: async (_agent, { input, emit }) => {
    // input is the FoundryRequest; payload arrives untouched from send(..., { payload }).
    const { orderId } = Payload.parse(input.payload);
    const status = orderId === "1042" ? "shipped" : "processing"; // your code: query the order system
    emit({ type: "order-status.checked", data: { orderId, status } });
    return { orderId, status }; // becomes run.output.value
  },
});

Call it like any other agent: foundry.send(agent.id, conversation.id, "status", { payload: { orderId: "1042" } }). To keep the model and add logic around it, call ctx.defaultRun(message?) (the normal Glove loop) inside run and return what you like. The full field list is on defineAgent & assembly.

Embedding the runtime

glove foundry dev and start do this for you. For tests or a custom host process, both classes are public exports of glove-foundry:

import { resolve } from "node:path";
import { FoundryRuntime, FoundryServer } from "glove-foundry";
import application from "../foundry.application.js";
import config from "../foundry.config.js";

const rootDir = process.cwd();
const runtime = await FoundryRuntime.discover({
  rootDir,
  agentsDir: resolve(rootDir, "agents"),
  application,
  // Lets agent processes load the application's conversationStore and data adapter.
  applicationFilePath: resolve(rootDir, "foundry.application.ts"),
  config,
});
await runtime.start();

const server = new FoundryServer(runtime, {
  host: "127.0.0.1",
  port: 4141, // 0 picks a free port
  messageBodyBytes: 8 * 1024 * 1024,
});
const { url } = await server.listen();
console.log(`Foundry listening on ${url}`);

// The runtime exposes the same operations in-process.
const agent = await runtime.createAgent("support", { workspaceId: "acme" });
const conversation = await runtime.createConversation(agent.id);
const run = await runtime.send(agent.id, conversation.id, "Where is order 1042?");
const done = await runtime.waitForRun(run.id, { timeoutMs: 120_000 });
console.log(done?.status, done?.output);

await server.close();
await runtime.stop();

FoundryServerOptions is { host?, port?, branding?, messageBodyBytes? }. listen() resolves { host, port, url } and throws on a non-loopback host without requestAuthorization. Agent turns always run in a separate managed execution daemon, not in this process; see Browser & sandbox for the execution model.