Applies to version 2.0.1 or later of the Archetype platform.
200 means
it does; a 404 means it doesn’t yet.
What Changed
Old Calls, New Calls
All paths are relative toATAI_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.
"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 givenvalues 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’soverrides.values. The promoted blueprint keeps it. Pin what later steps need, not only what you search: an output switch such asoutput_score, and, for serving,data_columnsandtimestamp_column, since a served query has no CSV header to read them from. - A blueprint that fits nothing (
mga,tva): set the values withoverrideson 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_embeddingsfor 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’smax_new_tokens. Anything else has to be in the blueprint.
- 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 afailed 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 staysfailed 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 without ablueprint_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 isready 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 aGET 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 returns409. Clean up in that order:
- Cancel any session still
pendingorrunning, then delete it. - Stop the deployment if it is up, then delete it.
- Delete the package.
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.Related Content
- Batch and Serving Modes
- Optimizations and Evals
- Release notes for 2.0.1
- Example Projects: the agent examples, each moved this way