# Choose an agent interface

Decide whether an agent task belongs to the HTTP generation API, the Studio Browser API or the Markdown docs, with worked examples for common requests.

Glyphfield offers agents three interfaces: the HTTP routes, the Studio Browser API (`window.glyphfield.studio`, available in an open `/studio` page) and the documentation as Markdown. Choose the interface before writing a request.

## Routing table [#routing-table]

| Task                                                                                                                               | Interface                                                       | Reason                                                    |
| ---------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | --------------------------------------------------------- |
| Find tool, identity, shader, surface or element IDs, schemas or policies                                                           | HTTP discovery routes such as `/api/agent` and `/api/materials` | Structured, versioned JSON                                |
| Generate a slide, blog cover, OpenGraph image, terminal card, partnership lockup, background, element brief or Design Lab document | `POST /api/generate`                                            | Validated input and a portable response without a browser |
| Render Canvas or WebGL output, use local fonts or files, place layers visually, or export PNG, JPG, GIF, MP4 or Lottie             | `window.glyphfield.studio`                                      | Uses the Studio renderer and the open project             |
| Read one topic                                                                                                                     | `/docs/<path>.md`                                               | One processed Markdown page                               |
| Load all documentation                                                                                                             | `/llms-full.txt`                                                | Every page in one file                                    |
| Find an unknown topic or capability                                                                                                | `/api/search?query=<text>` or `/api/catalog`                    | Ranked documentation results or structured capabilities   |

<DocsFeatureGrid>
  <DocsFeature icon="api" label="HTTP" title="Plan and generate">
    Source-controlled SVG, JSON briefs, repeatable requests and starting documents for Design Lab.
  </DocsFeature>

  <DocsFeature icon="render" label="Browser API" title="Operate and render">
    Work that depends on the open canvas, WebGL, browser codecs, local files or a visual check.
  </DocsFeature>

  <DocsFeature icon="document" label="Markdown" title="Learn the contract">
    Instructions, workflows, examples, edge cases and exact source formats.
  </DocsFeature>

  <DocsFeature icon="verify" label="Studio UI" title="Check the artifact">
    The visible workspace shows placement, contrast, clipping, timing and motion.
  </DocsFeature>
</DocsFeatureGrid>

## Decision order [#decision-order]

1. Read `/llms.txt` and `/api/agent`.
2. Look up the exact tool ID or generation kind in the discovery routes. Do not guess IDs.
3. Use `POST /api/generate` when it can express the whole result.
4. Open `/studio` and use the Browser API when the result depends on Canvas, WebGL, browser codecs, local files or visual placement.
5. Pass `response.document` from a `design-sequence` response to `applySource` yourself. An HTTP request does not change the open Studio.
6. Inspect the canvas and export through the active tool.
7. Treat the downloaded file or the returned Blob as the end of the task.

## Examples [#examples]

### Static agenda slide [#static-agenda-slide]

Use HTTP. The slide renderer returns SVG and needs no open project.

### Gem Smoke poster with motion [#gem-smoke-poster-with-motion]

Generate a `design-sequence` document over HTTP, then apply and export it in the browser. The server returns the composition, and the browser renders the shader pixels.

### Change to an existing local project [#change-to-an-existing-local-project]

Use the Browser API. Read the open tool's source, apply the smallest change, and save or export in that project. An HTTP request cannot tell which browser-local project the user means.

### Brand element brief [#brand-element-brief]

Find the element ID in `/api/elements` and send `POST /api/generate` with `kind: "element-brief"`. Open the Studio only when the user also wants a rendered proof.

## Interface boundaries [#interface-boundaries]

* A source document from the Studio source drawer is not a `/api/generate` request body.
* A discovery record is not a rendered artifact.
* A successful HTTP response does not update a browser-local design.
* Activating a control does not mean that an export finished.
* A material preview does not grant the right to redistribute a third-party asset.

See [Connect an agent](/docs/agents/connect), [Studio Browser API](/docs/reference/browser-api) and [Capability matrix](/docs/reference/capability-matrix).