Common fields

Every agent manifest starts with the same four-field header, regardless of kind. These are the identity fields surfaced everywhere — in the trace, the runs list, the agent picker, and (on the hosted edition) the version history.

id: my-agent                          # required, unique within the registry
name: My Agent                        # optional, display label
description: Does a thing             # optional, surfaced in UIs
kind: llm                             # llm | tool | sequential | parallel

Field reference

id (required)

The agent's stable identifier. It's what you pass to client.agents.run({ agentId }), what appears in trace spans, and what other agents reference with ref:.

• Must match ^[a-z][a-z0-9-]*$ — lowercase letters, digits, and hyphens.
• Unique within a registry (./agents directory for embedded, your workspace for hosted).
• Inline agents inside pipelines still need an id. It's what the trace span is named after.

name (optional)

A human-readable label. Shown in the hosted UI, the embedded runs.list output, and trace titles. Defaults to a title-cased version of id.

description (optional)

Free-form description. Surfaced in the agent picker and used by some tools (e.g. the agent-as-tool kind passes it to the parent LLM as the tool's description). Keep it tight — one sentence beats three.

kind (required)

Selects the agent type:

See The four agent kinds for examples.

Where to go next

• Input, state, and output — how data flows in and out.
• Templates and conditions — the {{}} mini-language used in nearly every field.
• Resources — provider-backed runtime capabilities such as memory.
• Pipeline steps and looping — fields specific to sequential and parallel kinds.
• Skills, spawnable, reply — extra fields for llm kind.