Tutorial: your first agent system

npx glove-foundry init support-desk --template minimal
cd support-desk
cp .env.example .env.local      # then set OPENROUTER_API_KEY=... in .env.local
pnpm dev

Glove Foundry

  Local:    http://127.0.0.1:4141
  Agents:   1
  Runtime:  ready
  Types:    .foundry/routes.d.ts

import { FileFoundryDataAdapter, defineApplication } from "glove-foundry";
import { fileURLToPath } from "node:url";

// Instances, conversations, installations and schedules, in one JSON file.
export const data = new FileFoundryDataAdapter({
  file: fileURLToPath(new URL("./.data/foundry.json", import.meta.url)),
});

export default defineApplication({ name: "support-desk", data });

import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
import { join } from "node:path";
import { MemoryStore, type Message } from "glove-core";

/**
 * A MemoryStore that saves the transcript to a JSON file after every append.
 * Each Foundry run executes in its own process, so a plain MemoryStore starts
 * empty on every message; this one reloads the conversation first.
 * The starter's version also saves turn and token counters, tasks and inbox items.
 */
export class FileStore extends MemoryStore {
  private constructor(id: string, private readonly file: string) {
    super(id);
  }

  static async open(id: string, directory = ".data/transcripts"): Promise<FileStore> {
    await mkdir(directory, { recursive: true });
    const store = new FileStore(id, join(directory, `${encodeURIComponent(id)}.json`));
    const saved = await readFile(store.file, "utf8").then(JSON.parse, () => [] as Message[]);
    await MemoryStore.prototype.appendMessages.call(store, saved); // restore without re-saving
    return store;
  }

  override async appendMessages(messages: Message[]): Promise<void> {
    await super.appendMessages(messages);
    const temp = `${this.file}.tmp`;
    await writeFile(temp, JSON.stringify(await this.getMessages()));
    await rename(temp, this.file);
  }
}

import { createAdapter } from "glove-core/models/providers";
import { defineAgent } from "glove-foundry";
import { FileStore } from "../../lib/file-store.js";

export default defineAgent({
  description: "Answers Acme Outfitters customers about orders and refunds",
  // Called per run with the ids of the conversation being served.
  store: ({ conversationId }) => FileStore.open(conversationId),
  model: () =>
    createAdapter({
      provider: "openrouter",
      model: process.env.OPENROUTER_MODEL ?? "openai/gpt-4.1-mini",
      stream: true,
    }),
  // A function is resolved per run from the assembly context.
  systemPrompt: (_agent, ctx) =>
    [
      "You are the customer-support agent for Acme Outfitters. Be brief.",
      "Never invent order details. If you cannot look an order up, say so.",
      `Customer tier: ${String(ctx.agentInstance.context.tier ?? "standard")}.`,
      `Installed for this instance: ${ctx.installations.map((item) => `${item.kind}:${item.id}`).join(", ") || "nothing"}.`,
      `Earlier messages in this conversation: ${ctx.history.length}.`,
    ].join("\n"),
});

import { z } from "zod";

const supportHours = {
  name: "support_hours",
  description: "Say whether the human support desk is open right now (Mon–Fri, 09:00–17:00 UTC).",
  inputSchema: z.object({}),
  async do() {
    const now = new Date();
    const weekday = now.getUTCDay() >= 1 && now.getUTCDay() <= 5;
    const open = weekday && now.getUTCHours() >= 9 && now.getUTCHours() < 17;
    return { status: "success" as const, data: { open, checkedAt: now.toISOString() } };
  },
};

export default defineAgent({
  // ...everything from step 2
  tools: [supportHours],
});

import { Effect } from "effect";
import { defineSharedTool } from "glove-foundry";
import { z } from "zod";

// your code: replace this with a call to your order system.
const ORDERS: Record<string, { region: "eu" | "us"; status: string; total: number }> = {
  "A-1001": { region: "eu", status: "shipped, arriving Thursday", total: 84 },
  "A-1002": { region: "eu", status: "processing", total: 129 },
  "B-2001": { region: "us", status: "delivered", total: 42 },
};

const lookupOrder = defineSharedTool({
  description: "Look up an order in one regional order system",
  // Each instance that installs this tool must supply a region.
  config: z.object({ region: z.enum(["eu", "us"]) }),
  create: ({ config }) =>
    Effect.succeed({
      name: "lookup_order",
      description: `Look up an order in the ${config.region.toUpperCase()} order system by id, e.g. A-1001.`,
      inputSchema: z.object({ orderId: z.string() }),
      async do({ orderId }: { orderId: string }) {
        const order = ORDERS[orderId];
        if (!order || order.region !== config.region) {
          return { status: "error" as const, data: null, message: `No ${config.region} order "${orderId}".` };
        }
        return { status: "success" as const, data: { orderId, status: order.status, total: order.total } };
      },
    }),
});

export default lookupOrder;

import { composeAgent, defineAgent } from "glove-foundry";
import lookupOrder from "./tools/lookup-order.tool.js";

export default defineAgent({
  // ...
  components: composeAgent(lookupOrder),
});

curl -s -X POST http://127.0.0.1:4141/api/agent-instances \
  -H 'content-type: application/json' \
  -d '{"definitionId":"support","id":"support-eu","workspaceId":"acme","context":{"tier":"gold"}}'

curl -s -X PUT http://127.0.0.1:4141/api/installations \
  -H 'content-type: application/json' \
  -d '{"agentId":"support-eu","kind":"tool","id":"lookup-order","config":{"region":"eu"}}'

import {
  FileFoundryDataAdapter,
  defineAgentInstance,
  defineApplication,
  install,
} from "glove-foundry";
import support from "./agents/support/agent.js";
import lookupOrder from "./agents/support/tools/lookup-order.tool.js";

// Seeded once: inserted only if .data/foundry.json has no instance with this id.
const supportUs = defineAgentInstance(support, {
  id: "support-us",
  workspaceId: "acme",
  installations: [install(lookupOrder, { region: "us" })], // config is type-checked
});

export const data = new FileFoundryDataAdapter({
  file: ".data/foundry.json",
  agents: [supportUs],
});

export default defineApplication({ name: "support-desk", data });

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

const foundry = createFoundryClient<FoundryRoutes>({ baseUrl: "http://127.0.0.1:4141" });

// One instance = one persisted support identity with its own installations.
const existing = (await foundry.agentInstances("support")).find((item) => item.id === "support-eu");
const agent = existing ?? await foundry.agent("support").create({
  id: "support-eu",
  workspaceId: "acme",
  context: { tier: "gold" },
  installations: [{ kind: "tool", id: "lookup-order", config: { region: "eu" } }],
});

// Two independent conversations owned by the same instance.
const alice = await foundry.createConversation(agent.id, { title: "Alice" });
const bob = await foundry.createConversation(agent.id, { title: "Bob" });

async function ask(conversationId: string, text: string): Promise<unknown> {
  const run = await foundry.send(agent.id, conversationId, text);
  const done = await run.wait({ timeoutMs: 120_000 });
  if (done.status !== "completed") throw new Error(done.error ?? `run ${done.status}`);
  return done.output?.value;
}

console.log("alice:", await ask(alice.id, "Hi, I'm Alice. Where is order A-1001?"));
console.log("bob:  ", await ask(bob.id, "Hi! What's my name?"));
console.log("alice:", await ask(alice.id, "What's my name, and what was my order?"));

npx tsx src/support-client.ts
# alice: Order A-1001 has shipped and should arrive Thursday.
# bob:   I don't know your name yet — what should I call you?
# alice: You're Alice, and you asked about order A-1001 (shipped, arriving Thursday).

import { composeAgent, defineAgent, defineSchedule } from "glove-foundry";

const followUpSweep = defineSchedule({
  name: "follow-up-sweep",
  description: "Weekday review of anything the agent promised to follow up on",
  timing: { kind: "cron", expression: "0 9 * * 1-5", timezone: "UTC" },
  message: "Review this conversation for promised follow-ups. Re-check those orders and summarize what changed.",
});

export default defineAgent({
  // ...
  // An instance can opt out through its own context.
  schedules: (_agent, ctx) => (ctx.agentInstance.context.followUps === false ? [] : [followUpSweep]),
});

"If you promise to check something later, schedule it with glove_foundry_schedule.",

import type { GloveFoldArgs } from "glove-core";

const refundInput = z.object({
  orderId: z.string(),
  amount: z.number().positive().describe("Amount in USD"),
  reason: z.string(),
});
const issueRefund: GloveFoldArgs<z.infer<typeof refundInput>> = {
  name: "issue_refund",
  description: "Refund all or part of an order. A human approves every refund.",
  inputSchema: refundInput,
  requiresPermission: true, // or (input) => input.amount > 50
  async do({ orderId, amount }) {
    // your code: await payments.refund(orderId, amount)
    return { status: "success", data: { orderId, refunded: amount } };
  },
};

export default defineAgent({
  // ...
  tools: [supportHours, issueRefund],
});

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

const foundry = createFoundryClient<FoundryRoutes>();
const agentId = "support-eu";
const conversation = await foundry.createConversation(agentId, { title: "Refund" });

const run = await foundry.send(agentId, conversation.id, "Order A-1001 arrived broken. Please refund the full $84.");

// The run pauses at issue_refund. Poll until the approval record appears.
let approval = (await foundry.approvals({ runId: run.id, status: "pending" }))[0];
while (!approval) {
  const current = await run.get();
  if (current.status !== "pending" && current.status !== "running") {
    throw new Error(`run ended as ${current.status} without asking for approval`);
  }
  await new Promise((resolve) => setTimeout(resolve, 500));
  approval = (await foundry.approvals({ runId: run.id, status: "pending" }))[0];
}

console.log(approval.toolName, approval.toolInput, "expires", approval.expiresAt);
await foundry.resolveApproval(approval.id, "approve"); // or "deny"

const done = await run.wait({ timeoutMs: 120_000 });
console.log(done.status, done.output?.value);

pnpm add openai

import OpenAI from "openai";

const openai = new OpenAI({
  baseURL: "http://127.0.0.1:4141/v1",
  // The SDK insists on a key. Foundry ignores it on loopback; with
  // requestAuthorization configured, your adapter receives it as a Bearer token.
  apiKey: "unused-on-loopback",
});

// model = an agent instance id. Send only the new user turn: Foundry keeps the history.
const { data: first, response } = await openai.chat.completions
  .create({
    model: "support-eu",
    messages: [{ role: "user", content: "Hi, where is order A-1001?" }],
  })
  .withResponse();
console.log(first.choices[0]?.message.content);

// Continue the same durable conversation.
const conversationId = response.headers.get("x-foundry-conversation-id")!;
const followUp = await openai.chat.completions.create(
  { model: "support-eu", messages: [{ role: "user", content: "Thanks. Is the help desk open right now?" }] },
  { headers: { "x-foundry-conversation-id": conversationId } },
);
console.log(followUp.choices[0]?.message.content);

// Streaming uses the same endpoint.
const stream = await openai.chat.completions.create(
  { model: "support-eu", stream: true, messages: [{ role: "user", content: "Summarize what we discussed." }] },
  { headers: { "x-foundry-conversation-id": conversationId } },
);
for await (const chunk of stream) process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
process.stdout.write("\n");

import type { GloveFoldArgs } from "glove-core";
import { createAdapter } from "glove-core/models/providers";
import { composeAgent, defineAgent, defineSchedule } from "glove-foundry";
import { z } from "zod";
import { FileStore } from "../../lib/file-store.js";
import lookupOrder from "./tools/lookup-order.tool.js";

// Step 3 — always on: every instance gets this tool on every run.
const supportHours = {
  name: "support_hours",
  description: "Say whether the human support desk is open right now (Mon–Fri, 09:00–17:00 UTC).",
  inputSchema: z.object({}),
  async do() {
    const now = new Date();
    const weekday = now.getUTCDay() >= 1 && now.getUTCDay() <= 5;
    const open = weekday && now.getUTCHours() >= 9 && now.getUTCHours() < 17;
    return { status: "success" as const, data: { open, checkedAt: now.toISOString() } };
  },
};

// Step 7 — a risky tool. Foundry turns every call into an approval request.
const refundInput = z.object({
  orderId: z.string(),
  amount: z.number().positive().describe("Amount in USD"),
  reason: z.string(),
});
const issueRefund: GloveFoldArgs<z.infer<typeof refundInput>> = {
  name: "issue_refund",
  description: "Refund all or part of an order. A human approves every refund.",
  inputSchema: refundInput,
  requiresPermission: true,
  async do({ orderId, amount }) {
    // your code: await payments.refund(orderId, amount)
    return { status: "success", data: { orderId, refunded: amount } };
  },
};

// Step 6 — desired recurring work, owned by each instance that runs.
const followUpSweep = defineSchedule({
  name: "follow-up-sweep",
  description: "Weekday review of anything the agent promised to follow up on",
  timing: { kind: "cron", expression: "0 9 * * 1-5", timezone: "UTC" },
  message: "Review this conversation for promised follow-ups. Re-check those orders and summarize what changed.",
});

export default defineAgent({
  description: "Answers Acme Outfitters customers about orders and refunds",
  components: composeAgent(lookupOrder), // step 4: installable, per instance
  store: ({ conversationId }) => FileStore.open(conversationId),
  model: () =>
    createAdapter({
      provider: "openrouter",
      model: process.env.OPENROUTER_MODEL ?? "openai/gpt-4.1-mini",
      stream: true,
    }),
  systemPrompt: (_agent, ctx) =>
    [
      "You are the customer-support agent for Acme Outfitters. Be brief.",
      "Never invent order details. If you cannot look an order up, say so.",
      "If you promise to check something later, schedule it with glove_foundry_schedule.",
      `Customer tier: ${String(ctx.agentInstance.context.tier ?? "standard")}.`,
      `Installed for this instance: ${ctx.installations.map((item) => `${item.kind}:${item.id}`).join(", ") || "nothing"}.`,
      `Earlier messages in this conversation: ${ctx.history.length}.`,
    ].join("\n"),
  tools: [supportHours, issueRefund],
  schedules: (_agent, ctx) => (ctx.agentInstance.context.followUps === false ? [] : [followUpSweep]),
});