Agent Studio & authoring

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:

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:

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:

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:

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 for how a published agent’s runtime reaches the platform — the same governed tool surface, whether the agent is first-party or yours.