defineAgent and per-run assembly

defineAgent describes how to build a Glove agent for one run. Almost every field can be a function of the instance, the conversation and the new message, so one definition can serve many customers with different prompts, models and tools — without branching inside the prompt.

A complete agent in one file

Save this as agents/support/agent.ts and the route support exists. Every instance of it gets the lookup_order tool.

import { createAdapter } from "glove-core/models/providers";
import { defineAgent } from "glove-foundry";
import { z } from "zod";
import { FileStore } from "../../lib/file-store.js"; // durable transcript — see Persistence

export default defineAgent({
  description: "Answers customer questions about orders",
  store: ({ conversationId }) => FileStore.open(conversationId),
  model: () =>
    createAdapter({
      provider: "openrouter",
      model: process.env.OPENROUTER_MODEL ?? "openai/gpt-4.1-mini",
      stream: true,
    }),
  systemPrompt: "You are a concise, friendly customer-support agent.",
  tools: [
    {
      name: "lookup_order",
      description: "Look up an order by its id",
      inputSchema: z.object({ orderId: z.string() }),
      async do({ orderId }) {
        // your code: query the order system
        return { status: "success" as const, data: { orderId, status: "shipped" } };
      },
    },
  ],
});

defineAgent validates the definition when the module loads:

• It must define model, run or spawn.
• Defining model requires systemPrompt.
• inboxes must be a function.
• input and output keys are rejected: requests and results use Foundry's fixed contracts. Use request.payload or defineCall for typed data.

The value-or-resolver rule

Lazy fields have the type FoundryResolver<T>:

type Resolvable<T> = T | Promise<T> | Effect.Effect<T, unknown, never>;

type FoundryResolver<T, TInput> =
  | T
  | ((agent: FoundryAgentDefinition, ctx: AgentAssemblyContext<TInput>) => Resolvable<T>);

• A literal is used as is for every run. Any function is treated as a resolver and called once per run.
• A resolver may return the value, a Promise, or an Effect with no requirements (Foundry runs it with Effect.runPromise). A literal cannot be a Promise.
• The first argument is the frozen definition itself (agent.id, agent.description), not a Glove instance.
• Resolvers in the same assembly step run concurrently and see the same read-only context; do not rely on order between them. A thrown error fails the run.
• store, inboxes, mcpAdapter, configure, build, spawn and run have their own signatures, listed below.

Every field

Identity, catalogue and adapters

Glove configuration

Mounted surfaces

Installable shared tools, apps and MCP servers are not fields: they live in components and mount only when the instance installs them. See Tools, MCP & memory. Guidance fields are covered in Goals, facts & forms, schedules and playbooks in Playbooks, schedules & sleep, and workingEnvironment/repl in Working environments.

Lifecycle hooks

id and handler still type-check but are deprecated: the file path owns identity, and run replaces handler. An agent.ts may also use named exports (export const description, export const run, …) instead of a default defineAgent.

The assembly context

Every resolver and build receive an AgentAssemblyContext:

The execution context

configure, spawn, run and call handlers receive a FoundryExecutionContext instead. It shares the identity and message fields (definitionId through messages, request, installations) and adds:

Assembly order for one run

Before a run starts, the host reloads the instance and conversation from the data adapter, checks they belong together and share a workspace, and enqueues the run. Inside the run process Foundry then:

1. Loads foundry.application.ts, calls store (or the application's conversationStore), reads history, and builds the assembly context.
2. Resolves model, systemPrompt, displayManager, compactionLimit, compactionInstructions and maxTurns concurrently, then constructs the Glove agent.
3. Resolves tools, hooks, skills, subagents, memory, inboxes, layers, subscribers, calls, playbooks, schedules, mesh, workingEnvironment and repl concurrently.
4. Reconciles schedules (every run) and playbooks (when the field is defined) onto the instance.
5. Folds the built-in glove_foundry_* tools, then outbound-transmission tools of installed apps, then your tools, hooks, skills and subagents.
6. Mounts the working environment and REPL. A REPL with programmaticTools waits until step 12.
7. Resolves facts, goals, forms and contextProviders and mounts them.
8. Registers calls, folding each as a tool unless exposeToAgent: false.
9. Mounts subscribers, then runs each layer's setup.
10. Mounts the instance's installations — shared tools and app contributions in installation order, then every installed MCP server through mcpAdapter — followed by memory profiles, inbox items and mesh.
11. Calls configure(agent, ctx).
12. Mounts the programmatic REPL, so it sees every tool mounted so far.
13. Calls build(agent, ctx); its return value (or the same agent) is what runs.
14. Executes run if defined, otherwise spawn, otherwise Glove's processRequest with the inbound message.
15. Finishes: a run that called sleep ends suspended; onCleanup callbacks run in reverse, then layer and subscriber teardown.

Each resolver emits foundry.assembly.resolve.start/complete events, so slow assembly is visible in the run trace in the inspector.

Message-dependent assembly

The same definition picks a vision model only when an image is attached, writes its prompt from instance data, and exposes a refund tool only to instances whose context allows it — and only on turns that mention refunds.

import { type GloveFoldArgs } from "glove-core";
import { createAdapter } from "glove-core/models/providers";
import { Effect } from "effect";
import { defineAgent } from "glove-foundry";
import { z } from "zod";
import { FileStore } from "../../lib/file-store.js"; // durable transcript — see Persistence

const lookupOrder: GloveFoldArgs<{ orderId: string }> = {
  name: "lookup_order",
  description: "Look up an order by its id",
  inputSchema: z.object({ orderId: z.string() }),
  async do({ orderId }) {
    return { status: "success", data: { orderId, status: "shipped" } };
  },
};

const issueRefund: GloveFoldArgs<{ orderId: string; amountCents: number }> = {
  name: "issue_refund",
  description: "Refund part or all of an order",
  inputSchema: z.object({ orderId: z.string(), amountCents: z.number().int().positive() }),
  requiresPermission: true, // pauses the run for an approval
  async do({ orderId, amountCents }) {
    return { status: "success", data: { orderId, refundedCents: amountCents } };
  },
};

export default defineAgent({
  description: "Answers customer questions about orders",
  store: ({ conversationId }) => FileStore.open(conversationId),

  model: (_agent, { message }) => {
    const hasImage = message.content?.some((part) => part.type === "image") ?? false;
    return createAdapter({
      provider: "openrouter",
      model: hasImage ? "openai/gpt-4.1" : "openai/gpt-4.1-mini",
      stream: true,
    });
  },

  systemPrompt: (_agent, { agentInstance, conversation, history }) =>
    [
      `You are the support agent for ${String(agentInstance.context.brand ?? "our store")}.`,
      `Conversation "${conversation.title ?? conversation.id}" has ${history.length} earlier messages.`,
    ].join("\n"),

  tools: (_agent, { agentInstance, messageText, controls }) => {
    const tools: GloveFoldArgs<any>[] = [lookupOrder];
    if (agentInstance.context.canRefund === true && /refund/i.test(messageText)) {
      tools.push(issueRefund);
    }
    // Custom events land in the run trace as agent.support.tools.selected
    controls.emit({ type: "support.tools.selected", data: { names: tools.map((t) => t.name) } });
    return tools;
  },

  // Resolvers may return a Promise or an Effect.
  compactionLimit: (_agent, { history }) =>
    Effect.succeed(history.length > 200 ? 60_000 : 100_000),
  maxTurns: 25,
});

agentInstance.context is whatever you stored when creating the instance ({ brand: "Acme", canRefund: true }); change it with configureAgent and the next run assembles differently. See Definitions & instances. Data passed to emit is retained in observability as is, so never emit secrets.

configure, calls and a custom run

configure mounts anything a field cannot express and registers its teardown. run takes over execution: here a typed payload takes a deterministic fast path with no model call, and everything else goes through the normal loop with an enriched user turn.

import { createAdapter } from "glove-core/models/providers";
import { defineAgent, defineCall } from "glove-foundry";
import { z } from "zod";
import { FileStore } from "../../lib/file-store.js"; // durable transcript — see Persistence

// your code: a client that holds a connection open for one run
function connectCrm(workspaceId: string) {
  return {
    async findCustomer(email: string) { return { email, plan: "pro", workspaceId }; },
    async close() {},
  };
}

const statusRequest = z.object({ kind: z.literal("order-status"), orderId: z.string() });

export default defineAgent({
  description: "Support agent with a deterministic fast path",
  store: ({ conversationId }) => FileStore.open(conversationId),
  model: () => createAdapter({ provider: "openrouter", model: "openai/gpt-4.1-mini", stream: true }),
  systemPrompt: "You are a concise customer-support agent.",

  calls: (_agent, { agentInstance }) => [
    defineCall({
      name: "order_status",
      description: "Return the status of one order",
      input: z.object({ orderId: z.string() }),
      output: z.object({ orderId: z.string(), status: z.string(), region: z.string() }),
      // Closes over assembly-time instance data.
      handler: ({ orderId }) => ({
        orderId,
        status: "shipped",
        region: String(agentInstance.context.region ?? "us"),
      }),
    }),
  ],

  configure: async (agent, ctx) => {
    const crm = connectCrm(ctx.workspaceId);
    ctx.onCleanup(() => crm.close()); // register right after acquiring
    agent.fold({
      name: "find_customer",
      description: "Find a customer in the CRM by email",
      inputSchema: z.object({ email: z.string() }),
      async do({ email }) {
        return { status: "success", data: await crm.findCustomer(email) };
      },
    });
    agent.addContextProvider(() => `Current time: ${new Date().toISOString()}`);
  },

  run: async (_agent, ctx) => {
    const status = statusRequest.safeParse(ctx.request.payload);
    if (status.success) {
      ctx.emit({ type: "support.fast-path", data: { orderId: status.data.orderId } });
      return ctx.invoke("order_status", { orderId: status.data.orderId });
    }
    return ctx.defaultRun([
      { type: "text", text: `${ctx.messageText}\n\n(arrived via ${ctx.request.source?.kind ?? "direct"})` },
    ]);
  },
});

• defaultRun(message?) runs Glove's processRequest; without an argument it uses the inbound message. Its return value is the final assistant text.
• Whatever run returns becomes the run's output (JSON-serialized). A fast path that skips defaultRun writes nothing to the conversation store.
• Inside run, ctx.spawn(message?) calls your spawn hook when one is defined and falls back to defaultRun.
• onCleanup callbacks run after the run finishes, fails or is cancelled. A failing callback does not stop the others; the errors are reported together.

build

build(agent, ctx) runs after everything is mounted and receives the assembly context. Return a wrapped or different IGloveRunnable to change what executes, or return nothing to keep the assembled agent. Prefer configure for mounting; reach for build only when you need to replace the runnable itself.

Splitting the definition across files

Larger agents keep agent.ts small by importing colocated pieces — tools/*.tool.ts, apps/*.app.ts, mcp/*.mcp.ts, memory/*.memory.ts, layers/*.layer.ts, subscribers/*.subscriber.ts — and passing them to composeAgent(...) in components. File names become ids; see Project structure for the conventions and Tools, MCP & memory for how each piece is mounted.