Connect an agent · Glyphfield Docs

Connection sequence

An agent should follow this sequence for every new deployment origin:

Fetch /llms.txt for the concise operating router. Fetch /llms-full.txt when the task needs the complete product model.
Fetch /api/agent for the current version, policies, resources, and contract.
Fetch /api/labs to discover the current Studio plugin surface.
Fetch /api/catalog when selecting a deterministic background or tactile surface recipe; its surfaceLibrary contains every preset, attribution record, and physical control.
Fetch /api/materials when selecting a shader or editing shared material controls.
Fetch /api/identities when using any built-in preset.
Fetch /api/elements when choosing a brand application.
Fetch GET /api/generate immediately before constructing a request.
POST application/json to /api/generate.
Save the returned artifact, or apply a returned Design Lab document through window.glyphfield.studio for browser-native Canvas/WebGL export.

Do not infer undocumented enum values. Do not scrape the client bundle when a structured endpoint provides the same information.

Shell connection check

BASE_URL=http://localhost:3012

curl -fsS "$BASE_URL/llms.txt"
curl -fsS "$BASE_URL/api/agent" | jq '{ version, schemaVersion, resources, interfaces, execution }'
curl -fsS "$BASE_URL/api/labs" | jq '{ count, plugins: [.plugins[].id] }'
curl -fsS "$BASE_URL/api/catalog" | jq '{ surfaces: .surfaceLibrary.count, surfaceControls: (.surfaceLibrary.controls | keys) }'
curl -fsS "$BASE_URL/api/materials" | jq '{ count, engines, sharedBy }'
curl -fsS "$BASE_URL/api/generate" | jq '.kinds | keys'

For a deployed instance, replace BASE_URL with its origin.

TypeScript discovery client

const baseUrl = 'http://localhost:3012';

const [manifest, labs, materials, generation, identities, elements] = await Promise.all([
  fetch(`${baseUrl}/api/agent`).then((response) => response.json()),
  fetch(`${baseUrl}/api/labs`).then((response) => response.json()),
  fetch(`${baseUrl}/api/materials`).then((response) => response.json()),
  fetch(`${baseUrl}/api/generate`).then((response) => response.json()),
  fetch(`${baseUrl}/api/identities`).then((response) => response.json()),
  fetch(`${baseUrl}/api/elements`).then((response) => response.json()),
]);

console.log(manifest.version, labs.count, materials.count, generation.schemaVersion);
console.log(identities.identities.length, elements.elements.length);
console.log(manifest.studioBrowserApi.global);

Independent discovery requests can run concurrently. Fetch the generation contract again if substantial time passes before generation.

Minimal generation call

const response = await fetch(`${baseUrl}/api/generate`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    kind: 'template',
    template: 'slides',
    slideLayout: 'title',
    texture: 'white',
    title: 'Code is the source of truth.',
    identity: { preset: 'gt' },
    output: 'raw',
  }),
});

if (!response.ok) throw new Error(await response.text());
const svg = await response.text();

The raw response is a complete SVG string.

Programmatic Design Lab sequence

The HTTP API creates the exact source document; the browser API renders it through the same live shader canvases and compositor as the UI.

const response = await fetch(`${baseUrl}/api/generate`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    kind: 'design-sequence',
    identity: { preset: 'gt' },
    shader: { materialId: 'paper-gem-smoke' },
    sequence: { cutCount: 10, finalHoldMs: 5000, pace: 'accelerating' },
    effect: { kind: 'bayer', opacity: 0.76 },
    texts: [{ value: 'Open Source', weight: 500 }],
    export: { width: 1920, fps: 30, quality: 'best' },
  }),
});
const generated = await response.json();

// Run inside the open /studio page after selecting Design Lab.
const studio = window.glyphfield.studio;
if (studio.activeTool() !== 'material') throw new Error('Open Design Lab first.');
await studio.applySource(generated.document);
const artifact = await studio.invoke('design.export', {
  format: 'mp4',
  mode: 'shader-sequence',
  download: true,
});

Use studio.describe() before invoking tool-specific actions. studio.controls() and the accessible-label activate/set methods make every visible UI operation programmatically available, including tools without a headless renderer. Export with PNG, JPG, GIF, or MP4; omit download when the caller wants only the returned Blob, or call studio.download(artifact) later.

Prompting an agent

Point an LLM at the runbook rather than reproducing the full schema in a prompt:

Read https://YOUR_ORIGIN/llms.txt and the linked agent manifest.
Generate a white GT agenda slide titled “One system, every market.”
Save the raw SVG response as gt-agenda.svg.
Do not use undocumented enum values.

This keeps the deployment’s current contract authoritative.

For broad implementation work, replace /llms.txt with /llms-full.txt. For a focused task, load one page such as /api/docs/studio/design-lab or /api/docs/reference/browser-api.

Browser source workflow

When a task requires an artifact that the public generation API cannot fully express, open the matching Studio tool and use window.glyphfield.studio. Prefer readSource/applySource for exact documents and controls/activate/set for visible operations. The Code drawer remains the human-facing version of the same source workflow.

Do not paste an arbitrary Studio source document into POST /api/generate. The drawer is the browser-local document for an open tool; the generation route is a separate versioned HTTP contract. design-sequence explicitly returns an apply-ready document. See Browser workflow, Source code editing, and Source formats.