Documentation menu

Getting started

Your first Project

Create a Project, author revisions with FDA or the API, then create a Release with revision pins and promote it through Deployment and Activation.

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.

Project → Agent revision → Definition revision → Release → Environment Deployment → Activation. Authoring through FDA or the API creates immutable revisions; Studio lets you review revisions, select exact Agent revisions, and include Definitions at their displayed latest revisions in a Release. Pinning an older exact Definition revision requires the existing Release API. Only Deployment Activation makes the selected versions receive new runs. See the Introduction for the product overview.

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 Agent and Definition revisions with FDA or the API

Open Perstack FDA from the Project's Agents or Definitions page to describe what you want to build. FDA assists authoring through server operations; you can also use the API directly to create Agents and Definitions and their immutable revisions. Agent revisions carry instructions, runtime/model settings, skills, tools, delegates, and operation grants.

A Definition's source is a JSON envelope containing a nonempty dsl string: the business logic is definition text inside that field. Arbitrary JSON business logic is not a valid Definition. Provide the Definition kind, slug, name, and any exact Agent/revision attachments through the authoring API.

Return to Studio to inspect the resulting revisions. The Agent detail page edits identity metadata and displays revisions; it is not a revision editor. Review the revision pins before creating a Release, using the selection limits below.

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.

Enforce the $5,000 ceiling inside pay-invoice itself so a direct call also rejects a larger amount. Use a separate pay-high-value-invoice operation for larger payments and configure manual approval by that operation name. Both operations must validate the required purchase-order match before writing. Workflow routing alone does not enforce the ceiling.

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. Create a Release with revision pins

When the Definition or Agent behavior needs a change, describe the change and review the new immutable revision. In Studio's Release form, the Agent dropdown selects an exact revision. Definition checkboxes include each selected Definition at its displayed latest revision ID; there is no selector for older Definition revisions. Review those displayed IDs before creating the Release. To pin an older exact Definition revision, create the Release through the existing Release API. The resulting Release records exact Agent and Definition revision pins; later revisions do not change those pins.

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. Prepare the Environment, deploy, then activate

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.

Related