# Agent Studio & authoring

> Compose an agent's tool and data boundary from the live ontology, validate it against the published grammar, test it in a no-write sandbox, and publish it as an immutable version.

Aerandil agents are **data, not code**: a versioned `definition_document` stored on an `agent_registry_entry` object, interpreted by the agent runtime. Agent Studio is the authoring plane over that contract — the Explorer view (and the programmatic surface underneath it) that turns a definition from hand-written JSON into a governed composition.

Authoring has four lanes, each backed by a published contract you can also drive directly:

## 1. Compose — within a declared ceiling

An agent is composed _within_ a registry entry’s declared maxima. The pick-list read returns the catalogue already intersected with your authority:

```plaintext
GET /v1/agent-authoring/pick-list/{registry_entry_id}
```

The response carries the object types, actions, functions, and canonical metrics that are **both** inside the entry’s declared scopes and data classes **and** invocable by your own token. An author cannot wire a capability they do not hold — authoring is a projection of the registry filtered by authority, never a second authority path. The composed boundary is enforced twice more downstream: at installation (the enabled subset must stay inside the declared maxima) and at run time (the installation-bound token).

Each action tool carries a per-tool confirmation mode, `auto` or `confirm`. A `confirm` tool is withheld from direct execution at run time and degrades into a `propose_action` awaiting human confirmation — and actions the registry declares confirm-required cannot be relaxed to `auto` by the author.

## 2. Validate — one published grammar

The definition grammar is a versioned JSON Schema (Draft 2020-12) the runtime owns, serves, and validates its own interpreter input against:

```plaintext
GET /agent/grammar
```

Validate your draft against the served schema before registering it. The first-party Studio and third-party builders share this one contract; there is no second copy to drift. Cross-field semantics the schema cannot express (model membership in `model_allowlist`, no self-delegation) are enforced by the runtime parser as a backstop.

## 3. Preview — the no-write sandbox

A draft runs against the real platform without writing anything:

```plaintext
POST /agent/previews
{ "definition": { …definition_document… }, "task": "…" }
```

The runtime validates the draft against the grammar, then runs it under **your** bearer with every action call forced into `_preview` — the kernel computes the full effect set and rolls the transaction back. Reads are real, effects are visible, nothing durable is written. The response streams the run’s trace as server-sent events (the same enveloped rows the trace store ingests), and the persisted trace is one call away from becoming a graded eval case (`promote_agent_trace_to_eval_case`).

## 4. Publish — an immutable version

Publishing is the same registered action every builder uses:

```plaintext
POST /v1/actions/hospitality.action.register_agent/apply
```

A publish mints a **new immutable version** of the registry entry carrying the composed `definition_document`. The version re-enters review (`review_status: submitted`); only approved versions are installable, and installations pin a version explicitly. Editing a published agent is always a new version, never a mutation.

## In Explorer

The Studio view (**Studio** in the Explorer navigation) wraps all four lanes: pick a registry entry, compose from the authority-filtered pick-list, watch the draft validate live against the served grammar, run a no-write preview in place, and publish — with per-tool confirmation and the delegated-authority (`obo_scopes`) ceiling surfaced as first-class controls.

See also the [MCP server overview](/mcp/overview/) for how a published agent’s runtime reaches the platform — the same governed tool surface, whether the agent is first-party or yours.

---

Source: https://developers.aerandil.com/agents/agent-studio/