> ## Documentation Index
> Fetch the complete documentation index at: https://docs.archetypeai.app/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Start with /introduction/getting-started. Use the Inference API's Direct Query endpoint (POST /api/inference/query) with the newton-c-2.6 or newton-fusion-1.0 model (text, image, and video reasoning) or the omega-embedding encoder (time-series embeddings). ATAI_API_ENDPOINT is the base URL https://platform.u1.archetypeai.app with no version path; every endpoint path begins with /api. Pages whose descriptions are marked (Archived) document the legacy Lens runtime — do not use them for new projects.

# Migrating from Bundles and Instances

> Move agent code from bundles and instances to projects, packages, deployments, and sessions, and what to watch for along the way.

Applies to [version 2.0.1](https://docs.archetypeai.app/release-notes/2.0.x.md#v2-0-1) or later of the Archetype platform.

Version 2.0.1 changes how an agent is run. Bundles and instances are removed; an agent now lives
in a **project** and runs as a **package** on a **deployment**, with each run a **session**. This
page maps the old calls to the new ones, walks through moving a script, and lists what changed in
practice, from moving the agent examples' own code. If you have seen the two models called Agent
Lifecycle 1.0 and 2.0, this is the move from one to the other.

> [!WARNING]
>
> Calls to `/api/agents/bundles` and `/api/agents/instances` no longer work. Optimizations, evals,
> blueprints and files work as before, apart from the project requirement below.

To check whether the platform you call serves the new endpoints, list one session. A `200` means
it does; a `404` means it doesn't yet.

```bash theme={"system"}
curl -s -o /dev/null -w "%{http_code}\n" "$ATAI_API_ENDPOINT/agents/sessions?limit=1" \
  -H "Authorization: Bearer $ATAI_API_KEY"
```

## What Changed

```mermaid theme={"system"}
flowchart TB
  subgraph before["Before: bundles and instances"]
    direction TB
    a1["blueprint"] --> a2["bundle<br/>blueprint + values"]
    a2 -->|"run (batch)"| a3["instance per run"]
    a2 -->|"run (serving)"| a4["serving instance, /query"]
  end
  subgraph after["After: inside a project"]
    direction TB
    b0["project"] --> b1["blueprint"] --> b2["package<br/>no values"]
    b2 --> b3["batch deployment"] --> b4["session per run"]
    b2 --> b5["serving deployment"] --> b6["session, /query"]
  end
  before ~~~ after
```

| Object | What it is |
| - | - |
| **Project** | Where agent work lives. Every new blueprint, optimization, eval, package and deployment is in one, and each object takes its project from the one it was made from. |
| **Package** | One or more blueprints, with their models resolved once when it is built. It takes **no values**: it runs the blueprint exactly as stored. |
| **Deployment** | A package placed to run, as `batch` or `serving`. A `serving` deployment loads the agent on a worker and holds it until it is stopped. |
| **Session** | A run on a deployment. On `batch`, one run over its input files. On `serving`, a handle on the loaded agent that answers queries. See [Batch and Serving Modes](https://docs.archetypeai.app/core-concepts/agents/batch-and-serving.md) for more information. |

| Before | After | Why |
| - | - | - |
| A canonical blueprint, used directly | A copy of the blueprint in your project | Creating an optimization, eval, package or deployment from a blueprint outside a project returns `400 project_required` |
| A bundle: a blueprint plus per-run `values` | A package: a blueprint as stored | Models are resolved once, at build time |
| A batch instance per run | A batch deployment, and a session per run | The deployment is set up once and each run is a session |
| A serving instance | A serving deployment, and a session on it | The deployment holds the loaded agent; sessions are clients of the deployment |
| `/logs` | Session `status`, `error`, and `/events` | A session always reaches a terminal status and says why it failed |

## Old Calls, New Calls

All paths are relative to `ATAI_API_ENDPOINT`, which is
`https://platform.u1.archetypeai.app/api` for standard production accounts or
`https://try.archetypeai.app/api` for free trial accounts.

| Before | After |
| - | - |
| — | [`POST /projects`](https://docs.archetypeai.app/api-reference/projects/create-project) `{name, description}` |
| A canonical blueprint by its key | [`POST /agents/blueprints/{reference}/copy`](https://docs.archetypeai.app/api-reference/agents/blueprints/copy-blueprint) `{project_id, blueprint_key}` |
| `POST /agents/bundles` `{blueprint, values}` | [`POST /agents/packages`](https://docs.archetypeai.app/api-reference/agents/packages/create-package) `{blueprint_ids, target: {kind: "platform"}, name}`, then poll [Get Package](https://docs.archetypeai.app/api-reference/agents/packages/get-package.md) until `ready` |
| `POST /agents/bundles/{id}/run` `{connectors}` | [`POST /agents/deployments`](https://docs.archetypeai.app/api-reference/agents/deployments/create-deployment) `{package_id, kind: "batch"}`, then [`POST /agents/sessions`](https://docs.archetypeai.app/api-reference/agents/sessions/create-session) `{deployment_id, connectors}` |
| `POST /agents/bundles/{id}/run` `{mode: "serving"}` | `POST /agents/deployments` `{package_id, kind: "serving"}`, poll until `ready`, then `POST /agents/sessions` `{deployment_id}` and poll until `running` |
| `GET /agents/instances/{id}` | [`GET /agents/sessions/{id}`](https://docs.archetypeai.app/api-reference/agents/sessions/get-session) |
| `GET /agents/instances/{id}/events`, `/logs` | [`GET /agents/sessions/{id}/events`](https://docs.archetypeai.app/api-reference/agents/sessions/list-session-events); there is no `/logs` |
| `GET /agents/instances/{id}/results` | [`GET /agents/sessions/{id}/results`](https://docs.archetypeai.app/api-reference/agents/sessions/get-session-results) |
| `POST /agents/instances/{id}/query` | [`POST /agents/sessions/{id}/query`](https://docs.archetypeai.app/api-reference/agents/sessions/query-session), with the same body and the same `response` |
| `POST /agents/instances/{id}/cancel`, `DELETE /agents/instances/{id}` | [`POST /agents/sessions/{id}/cancel`](https://docs.archetypeai.app/api-reference/agents/sessions/cancel-session), [`DELETE /agents/sessions/{id}`](https://docs.archetypeai.app/api-reference/agents/sessions/delete-session) |
| `DELETE /agents/bundles/{id}` | [Stop](https://docs.archetypeai.app/api-reference/agents/deployments/stop-deployment.md) and [delete](https://docs.archetypeai.app/api-reference/agents/deployments/delete-deployment.md) each deployment, then [delete the package](https://docs.archetypeai.app/api-reference/agents/packages/delete-package.md) |
| `GET /agents/instances?bundle_id=` | [`GET /agents/deployments?package_id=`](https://docs.archetypeai.app/api-reference/agents/deployments/list-deployments), [`GET /agents/sessions?deployment_id=`](https://docs.archetypeai.app/api-reference/agents/sessions/list-sessions) |

Statuses: a package goes `building` → `ready` or `failed`; a deployment `deploying` → `ready` →
`stopping` → `stopped`, or `failed`; a session `pending` → `running` → `completed`, `failed` or
`cancelled`.

## Moving a Script

The steps below run a batch agent on one CSV file, end to end. Each step is a call or two; the
Python version is one script.

**1. Create a project, or reuse one**

```bash theme={"system"}
curl -X POST "$ATAI_API_ENDPOINT/projects" \
  -H "Authorization: Bearer $ATAI_API_KEY" -H "Content-Type: application/json" \
  -d '{"name": "Pump line 3", "description": "Operational state monitoring"}'
```

**2. Copy the blueprint you start from into it**

A canonical blueprint such as `osm` is outside every project, so copy it in. Optimize and
promote the copy as before: the optimization, its promoted blueprints, and their packages all
land in the project.

```bash theme={"system"}
curl -X POST "$ATAI_API_ENDPOINT/agents/blueprints/osm/copy" \
  -H "Authorization: Bearer $ATAI_API_KEY" -H "Content-Type: application/json" \
  -d '{"project_id": "prj_...", "blueprint_key": "pump-osm"}'
```

**3. Move every per-run value into the blueprint**

A package, a deployment and a batch session take no values. Anything you set on a bundle
now has to be in the blueprint the package is built from. See [Values](#values) for where.

**4. Build a package and deploy it**

Package the blueprint (a promoted trial, or your copy), wait until it is `ready`, then deploy
it as `batch`.

```bash theme={"system"}
curl -X POST "$ATAI_API_ENDPOINT/agents/packages" \
  -H "Authorization: Bearer $ATAI_API_KEY" -H "Content-Type: application/json" \
  -d '{"blueprint_ids": ["blp_..."], "target": {"kind": "platform"}, "name": "Pump line 3"}'

curl -X POST "$ATAI_API_ENDPOINT/agents/deployments" \
  -H "Authorization: Bearer $ATAI_API_KEY" -H "Content-Type: application/json" \
  -d '{"package_id": "pkg_...", "kind": "batch"}'
```

**5. Run a session per input, where you ran the bundle**

The `connectors` are the ones you passed to the bundle's run.

```bash theme={"system"}
curl -X POST "$ATAI_API_ENDPOINT/agents/sessions" \
  -H "Authorization: Bearer $ATAI_API_KEY" -H "Content-Type: application/json" \
  -d '{"deployment_id": "dpl_...",
       "connectors": {"source": [{"type": "file", "id": "fil_...", "format": "csv"}]}}'
```

**6. Poll the session and download its results**

Follow `status` until it is terminal, then page through `/results`. See
[Result references](#result-references) for how to fetch each one.

**7. Clean up**

Delete the session, stop and delete the deployment, then delete the package. See
[Cleanup](#cleanup).

The same flow in Python:

```python theme={"system"}
import os
import time
from urllib.parse import urljoin

import requests

endpoint = os.environ["ATAI_API_ENDPOINT"]          # e.g. https://platform.u1.archetypeai.app/api
headers = {"Authorization": f"Bearer {os.environ['ATAI_API_KEY']}"}


def call(method, path, **kwargs):
    r = requests.request(method, f"{endpoint}{path}", headers=headers, timeout=60, **kwargs)
    r.raise_for_status()
    return r.json() if r.content else None


def wait(path, done, every=5):
    while (obj := call("GET", path))["status"] not in done:
        time.sleep(every)
    return obj


project = call("POST", "/projects", json={"name": "Pump line 3"})
copy = call("POST", "/agents/blueprints/osm/copy",
            json={"project_id": project["id"], "blueprint_key": "pump-osm"})
# Optimize the copy and promote a trial, as before. Package the promoted blueprint;
# for a blueprint that fits nothing (mga, tva), package the copy itself.
blueprint_id = "blp_..."

package = call("POST", "/agents/packages", json={
    "blueprint_ids": [blueprint_id], "target": {"kind": "platform"}, "name": "Pump line 3"})
package = wait(f"/agents/packages/{package['id']}", {"ready", "failed"})
if package["status"] != "ready":
    raise SystemExit(f"{package['id']} failed: {package.get('error')}")   # delete it, then build again
deployment = call("POST", "/agents/deployments", json={"package_id": package["id"], "kind": "batch"})
deployment = wait(f"/agents/deployments/{deployment['id']}", {"ready", "failed"})
if deployment["status"] != "ready":
    raise SystemExit(f"{deployment['id']} failed: {deployment.get('error')}")

session = call("POST", "/agents/sessions", json={
    "deployment_id": deployment["id"],
    "connectors": {"source": [{"type": "file", "id": "fil_...", "format": "csv"}]}})
session = wait(f"/agents/sessions/{session['id']}", {"completed", "failed", "cancelled"}, every=15)
if session["status"] != "completed":
    raise SystemExit(f"{session['id']} {session['status']}: {session['error']}")

for result in call("GET", f"/agents/sessions/{session['id']}/results")["data"]:
    ref = result["data"]["ref"]
    url = ref if ref.startswith("http") else urljoin(endpoint, ref)   # see Result References
    with open(result["data"]["filename"], "wb") as f:
        f.write(requests.get(url, headers=headers, timeout=300).content)

call("DELETE", f"/agents/sessions/{session['id']}")
call("POST", f"/agents/deployments/{deployment['id']}/stop")
wait(f"/agents/deployments/{deployment['id']}", {"stopped", "failed"})
call("DELETE", f"/agents/deployments/{deployment['id']}")
call("DELETE", f"/agents/packages/{package['id']}")
```

For a serving agent, deploy the package with `"kind": "serving"`, open a session with only the
`deployment_id`, poll it until it is `running`, and send each query to
`/agents/sessions/{id}/query` with the body you sent to the instance. [Batch and Serving
Modes](https://docs.archetypeai.app/core-concepts/agents/batch-and-serving.md) walks through both.

The [Python client](https://docs.archetypeai.app/libraries/python.md) makes the same move: `client.agents.bundles` and
`client.agents.instances` are removed, and `client.projects`, `client.agents.deployments`, and
`client.agents.sessions` take their place.

## What Changed in Practice

These notes come from moving the agent examples (anomaly discovery, operational state monitoring,
rare event detection, manual generation and task verification) to the new calls. Rerun after the
move, the examples reproduced their optimization and eval scores, and served answers matched
batch. Where the delivery ran at the same step as before, its outputs were identical to the
bundle runs'; where it had to change step (see [Step Size](#step-size)), detection scores came
out within a point.

### Values

A bundle could override any blueprint value for each run. A package runs its blueprint exactly
as stored, and a batch session given `values` is refused with `422`. Where a value goes now
depends on the blueprint:

* **A blueprint that is fitted by an optimization** (`osm`, `ad`, `red`): pin the value in the
  optimization's `overrides.values`. The promoted blueprint keeps it. Pin what later steps need,
  not only what you search: an output switch such as `output_score`, and, for serving,
  `data_columns` and `timestamp_column`, since a served query has no CSV header to read them
  from.
* **A blueprint that fits nothing** (`mga`, `tva`): set the values with `overrides` on [Copy
  Blueprint](https://docs.archetypeai.app/api-reference/agents/blueprints/copy-blueprint.md), one copy per setting. Key each
  copy by its values, find it before making a new one, and reuse its package and deployment for
  every later run at that setting.
* **A value only some runs need**, such as turning on `output_embeddings` for a view while the
  main delivery keeps its outputs small: make a second blueprint for it. A copy of a promoted
  blueprint can't override values, because its trainable node is already fitted, so run a
  1-trial optimization pinned at the winning trial's values plus the extra one, and promote it.
  Make it again after every new promotion.
* **Serving sessions** accept `values`, but only for a node's session fields, such as a fusion
  model's `max_new_tokens`. Anything else has to be in the blueprint.

Two checks are worth adding:

* **A plain copy runs at the blueprint's defaults.** If your bundle set a value, set it on the
  copy, even if it looks like the default: a canonical blueprint's defaults can change between
  releases.
* **A copy checks keys, not wiring.** A bundle stored any key and ignored the ones the blueprint
  didn't use. A copy refuses a key the blueprint doesn't declare with `400`, but still accepts a
  declared value that no node reads. Read the blueprint document if a setting seems to have no
  effect.

### Step Size

`step_size` is a fit setting as well as a run setting, so a package delivers and serves at the
step the trial was fitted and scored at. If a bundle ran at a finer step than the optimization
(for example a score for every sample), either optimize at the step you want to deliver at, or
deliver at the optimized step. To keep fewer windows than the blueprint produces, as a coarser
step did, run at the blueprint's step and subsample the output yourself.

### Result References

`GET /agents/sessions/{id}/results` returns each output's `ref`, which is either a presigned URL
or a path such as `/api/files/fil_.../content`. The path already starts with `/api`, so resolve it
against the host, not against `ATAI_API_ENDPOINT`: appending it to `.../api` gives `/api/api/...`
and a `404`. `urljoin(endpoint, ref)` in Python does this.

### Status and Errors

A session always reaches a terminal status, and a `failed` one carries `error`. Follow `status`
instead of reading logs, and read `/events` (newest first) for what happened: opened,
dispatched, failed with a reason. There is no `/logs`, so the model-load timings and parser
warnings it carried are gone.

`completed` means the job ended, not that its output is whole. An output can still be being
written when the session reports `completed`, or come back short, so check that it covers its
input (its last window ends at the input's end) and download it again until it does; if it
stays short, end that session and open a new one. A run that produced nothing useful also ends
`completed`: for agents whose output can come back empty, such as a manual with no steps or a
verification with no verdicts, check the output itself. A session's `/results` is paged (100
items by default, one per input file): follow `next_cursor`.

### Record IDs Before Waiting

Create Package and Create Deployment return as soon as the platform accepts the request, and a
package that fails to build stays `failed` and never becomes `ready`: delete it and build a new
one, rather than waiting on it again. Save every package, deployment, and session id the
moment you get it, before polling, so a script that dies mid-run can resume and collect instead of
starting again, and your cleanup can find what it left. A session keeps running if your client
stops.

### Promoted Blueprint Keys and Lookups

[Promote Trial](https://docs.archetypeai.app/api-reference/agents/optimizations/promote-trial.md) without a `blueprint_key`, and
the platform keys the blueprint after the blueprint it was optimized from and the trial, for
example `pump-osm-otr_...`. Choosing a key can require the organization admin role, and a rerun
that asks for a key already taken fails. Look blueprints up by their `blp_` id: a key registered
in a project resolves only with `?project_id=`.

### Serving Deployments

A serving deployment holds a worker from the moment it is `ready` until it is stopped, whether or
not a session is querying it. Stop it when you are done, including when your script is
interrupted. A serving session closes after 30 idle minutes by default, and several sessions can
share one deployment; set both with `sessions` on [Create
Deployment](https://docs.archetypeai.app/api-reference/agents/deployments/create-deployment.md).

### Retries

Retry a `GET` or `DELETE` that times out, drops its connection, ends early or answers `502`,
`503` or `504`, including result downloads. A few `POST`s are safe to repeat too: cancelling a
session, stopping a deployment, and a serving query. Don't retry a `POST` that creates
something (a project, a blueprint copy, a package, a deployment, a session): its response may
have been lost after the object was made, and a second one is an object your script never
recorded, such as a serving deployment holding a worker.

### Cleanup

Each object holds the next: a session holds its deployment and a deployment its package, and
deleting a package or project that still has deployments returns `409`. Clean up in that order:

1. Cancel any session still `pending` or `running`, then delete it.
2. Stop the deployment if it is up, then delete it.
3. Delete the package.

Try each step even when one before it fails, and keep the ids of whatever is left, so a later
run can finish the cleanup. A session that won't delete must not leave a serving deployment
holding its worker.

To find what a script never recorded, start from each package: list its deployments with
`GET /agents/deployments?package_id=`, and each deployment's sessions with
`GET /agents/sessions?deployment_id=`. Keep the project, its blueprints, optimizations, and evals
if you want the record; delete the blueprints, then the project, if you don't.

## In the Developer Console

The Console has a [Projects](https://docs.archetypeai.app/developer-console/projects.md) page, and under **Agents** lists of
[packages](https://docs.archetypeai.app/developer-console/agents/packages.md),
[deployments](https://docs.archetypeai.app/developer-console/agents/deployments.md), and
[sessions](https://docs.archetypeai.app/developer-console/agents/sessions.md) across every project. Each view can show the API
requests that do the same thing.

## Related Content

* [Batch and Serving Modes](https://docs.archetypeai.app/core-concepts/agents/batch-and-serving.md)
* [Optimizations and Evals](https://docs.archetypeai.app/core-concepts/agents/optimize-and-eval.md)
* [Release notes for 2.0.1](https://docs.archetypeai.app/release-notes/2.0.x.md#v2-0-1)
* [Example Projects](https://docs.archetypeai.app/code-examples/example-projects.md#agents): the agent examples, each moved this way


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.