Your first Project

This is the shortest path from an empty Studio workspace to a Project with an explicit Agent revision running in one Environment. The important boundary is the Project: it owns the Agents and their immutable revisions. An Environment is the target that owns configuration and the active Deployment.

1. Create the Project and grant access

Create or select a Project in Studio. Invite collaborators or grant Project or Environment access before asking them to author or promote changes. A Project grant does not automatically grant access to another Project, and an Environment grant does not become a Project-wide grant. See Organization and members.

Create an API key only for a system that needs programmatic access. Give it the narrow Project, Environment, Agent, and operation scope that the system requires, and set its finite expiry. The secret is shown when the key is created; store it then. See API keys.

2. Author the Agent and Definition

Open the Project's Agents page and create the Agent with its canonical slug and name. Agent metadata can be edited later. Open the Agent detail page to author an immutable revision: enter its instruction and supported runtime/model settings, then preserve any declared skills, tools, delegates, and operation grants. Saving creates a new revision; it never changes an existing revision.

Open Definitions and choose Create a Definition. Select its kind, enter a slug and name, and provide the source and any exact Agent/revision attachments as JSON. The Definition identity is separate from its immutable source revisions. Open the created Definition to update metadata or select a revision to edit as a new revision. Invalid source or attachment JSON is rejected before another revision is created.

For a plain-language starting point, describe what comes in, what the Agent should do, the records it needs, and where a person must approve an operation. For example:

Handle inbound supplier invoices: read the PDF, match it to the purchase order, flag any mismatch, and hold anything over $5,000 for approval.

Review the Definition's records, operations, and rules before promoting it. A revision alone does not activate anything; authoring and deployment are separate steps.

3. Revise and publish exact versions

When the definition or Agent behavior needs a change, describe the change and review the new immutable revision. Do not rely on “latest” when promoting a workflow. A Release records the exact Agent and Definition revision pins you selected.

The Environment already has a configuration head when it is provisioned. Configuration revisions are immutable snapshots: they include the exact variable, connection, and provider-setting versions selected for the Environment. Provider settings are optional; an empty provider-settings collection means the platform default is used. Do not add a credential merely to make the default provider work.

In the Environment's variables panel, create or edit a local non-secret value, or select an Organization variable and pin its exact version. Secret values are shown as metadata only. Variable changes belong to a new configuration revision; they do not silently change an Agent or the active Deployment.

4. Activate the logical Environment, then promote

Project creation atomically creates the Development, Preview, and Production Environments. Select the existing built-in Environment for this workflow; do not create another one. A newly created logical Environment starts in provisioning, even though it already has an initial configuration head. Before creating configuration revisions or submitting a Deployment, transition the selected Environment to active with the canonical update operation:

PATCH /api/v1/projects/{projectId}/environments/{environmentId}
{
  "lifecycle": "active",
  "expectedLifecycle": "provisioning"
}

This is the logical Environment lifecycle transition. It is not Deployment Activation. Runtime Binding remains lazy and provider settings are optional; an Environment using the platform default does not need a fabricated credential or eagerly provisioned runtime resource.

Submit the Release for the target Project Environment with its configuration revision. This creates a queued Deployment. Wait until the Deployment is ready, then activate it with the Environment's current generation. Activation changes the Environment's active pointer; it does not rewrite the Release, Deployment, Agent revision, or configuration snapshot.

Only the activated Deployment receives new runs. If the activation conflicts because another change won the generation check, reload the Environment and choose the exact Deployment you intend to activate rather than silently retrying against a different target.

5. Operate and improve

Use Reading the record to follow runs and revision pins. A rule can complete automatically, wait for an approval, or refuse an operation; Handling approvals explains the human decision path. When behavior needs to change, author a new revision and repeat Release, Deployment, and Activation. Past runs and past promotions remain history; they are not rewritten by the next revision.