Skip to main content
Applies to version 2.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.
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.

What Changed

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. 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

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.
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 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.
5

Run a session per input, where you ran the bundle

The connectors are the ones you passed to the bundle’s run.
6

Poll the session and download its results

Follow status until it is terminal, then page through /results. See 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.
The same flow in Python:
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 walks through both. The Python client 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), 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, 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. Promote Trial 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.

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 POSTs 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 page, and under Agents lists of packages, deployments, and sessions across every project. Each view can show the API requests that do the same thing.