Operate / 09

Runtime and HTTP API

The development server and production runtime expose stable agent-system operations over HTTP while Effect services coordinate discovery, persistence, execution, activation, scheduling, connections, and observation underneath.

Application adapters

foundry.application.tstypescript

export default defineApplication({
  name: "Brand workforce",
  data: durableFoundryData,
  conversationStore: ({ conversationId }) => storeFor(conversationId),
  provisioner: customInstanceProvisioner,
  services: productionServiceLayer,
  accounts: [supportAccount],
  routes: [supportInbound, supportOutbound],
  bindings: [supportBinding],
});

Only configure services you own. Development defaults use memory adapters. A production application should select durability and concurrency explicitly and validate adapter health before accepting traffic.

Primary activation endpoints

Endpoint	Purpose
`POST /api/agent-instances`	Provision an instance from a discovered definition route.
`PATCH /api/agent-instances/:id`	Update instance context and installed runtime data.
`POST /api/conversations`	Create a durable conversation for an instance.
`POST /api/conversations/:id/messages`	Append a Glove-compatible message and enqueue a run.
`POST /api/transmissions/:routeId/fire`	Deliver a normalized inbound event through playbook subscriptions.
`GET /api/events?runId=:id`	Read the correlated event timeline for a run.

Use the generated client routes

client.tstypescript

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

const foundry = createFoundryClient<FoundryRoutes>();
const analyst = foundry.agent("analyst"); // checked against the file routes
const handle = await analyst.request({
  message: "Compare the three campaign directions.",
});
const run = await handle.wait({ timeoutMs: 120_000 });

Custom handlers

If a route exports a typed run handler, Foundry validates its payload and result without assembling a model loop. Use this for deterministic endpoints, ingestion, or orchestration glue. defineAgent itself never defines request input or output; those are runtime route concerns.

Glove message parity

Foundry accepts the native Glove message content model: text plus typed content parts and attachments. The current message and complete history flow into lazy assembly, so tools, prompts, memory, inboxes, and workbenches can respond to media as well as text.

Typed failure, explicit retry

Runtime adapters expose typed failures through Effect. Retry policy belongs at the failing boundary: provider pressure may retry a model pass, while an inbound delivery claim prevents the external event from provisioning the same instances twice. Cancellation interrupts scoped work and records the transition.