Creating a blueprint requires the Admin role. A Developer gets
403 forbidden
(“blueprint creation requires the admin role”). An Admin can
copy a custom blueprint into a
Developer’s project, and the Developer can then package and run that copy.Use Cases
- Combine signals the canonical agents keep apart: for example, Omega embeddings and per-channel statistics joined into one row per window, so a detector sees both shape and level.
- Change the pipeline, not just its settings: add or drop validation steps, change the features, or swap one head for another.
- Ask a different question of video: a Newton C 2.6 or Newton Fusion graph with your own prompt, run as a batch session per video or served a video per query.
- Fit a head of your own design: a graph with an anomaly or classifier head can be optimized, evaluated and promoted on your labelled data.
The Building Blocks
List Node Registry (GET /agents/nodes/registry) returns every node and connector you can use. Each entry has a
key, a description, a contract (its named input and output ports, each with a
type), a config_schema, and a default_config. Registries can differ between
deployments of the platform, so build against the registry of the platform you’ll run on.
Writing a Blueprint
A blueprint is a YAML (or JSON) document with six parts:values (the settings a copy can
override), models (models by name), connectors (one source and one sink), nodes,
graph.edges, and, for a trainable agent, metrics. This one validates each window of a sensor
CSV, sends it both to the Omega encoder and to per-channel statistics, and joins the two into one
row per window:
Omega embeddings + channel statistics
Omega embeddings + channel statistics
- Exactly one source and one sink, named
sourceandsinkunderconnectors. A blueprint with two of either can be created but can’t be deployed. - Port names come from each node’s contract (
source.out,window.in,MultiModalSource’stextandvideo).TeeNodeandConcatColumnsNodetake theirs fromconfig.ports:ports: [emb, feat]givestee.emb,tee.feat,fuse.embandfuse.feat. - Types must match along every edge. The platform checks this when you create the blueprint
and refuses a mismatch, for example
incompatible contracts on edge classifier.out -> newton_c.in: MultiModalPrompt cannot accept values of Record. valuesare the interface. Reference them as${values.name}anywhere in a node’sconfig, and models as${models.name}. Leave what you can’t know in advance asnull(such astimestamp_columnanddata_columns) and set it on a copy. Use${required}for a value that must come from a copy or an optimization’s search.
Creating and Running a Custom Agent
1
Create a project
Every blueprint belongs to a project; creating one without a
project_id returns
400 project_required. Use Create Project.2
Create the blueprint
Send the YAML as
yaml_document to Create
Blueprint, with a blueprint_key
and the project_id. Keys are unique within your organization, so version them
(my-agent-v2). The document is validated against the node registry; an unknown node,
port, or type mismatch is refused with the reason.3
Set its values on a copy
A package carries no values of its own, so set them on a copy with Copy
Blueprint and
overrides.values. One
template serves many datasets: make a copy for each set of columns or window size.4
Build a package
Build the copy into a package with Create
Package.
5
Deploy it and open sessions
Deploy the package with Create
Deployment, as
batch to process
files or serving to answer queries, then open a session with Create
Session. See Batch vs. serving
sessions.Things to Check
- Timestamps in seconds. The validation nodes read timestamps as seconds. With epoch
milliseconds, every window fails validation: each row comes back with
predicted_label: INVALID_STATEand no score, and the session still completes. - A completed batch session can still be all invalid. Check the
invalidcolumn of the results, not only the session status. And read the job’s events when a batch session staysrunning: anERRORevent means it has failed. - Batch graphs end in a
RecordsSink. A graph that ends inTextSinkfails in batch. For a language-model graph in batch, end it the way the canonical Manual Generation blueprint does: a results parser, then aRecordsSinkwithformat: json/per-request.TextSinkworks for serving. - Serving queries for a sensor graph send one window per query, channel-first, with no
timestamps:
{"query": "", "events": [{"type": "data.numeric_array", "event_data": {"contents": [[...channel 1...], [...channel 2...]]}}]}.
Trainable Custom Agents
A custom agent can be optimized, evaluated and promoted like the OSM, AD and RED blueprints, when it has something to fit and you have labelled data to score it on. Its blueprint needs:- A head with fittable state:
AnomalyDetectorNode,OutlierDetectorNode,ClassifierNode, orMultiheadClassifierNode, with its model left empty (models: { detection_head: }). Each trial fits it, and promoting a trial fills it in. - A
metricssection that names what to score:
search_space,
categorical values must be integers or strings, not booleans. A blueprint with no head and no
metrics (embeddings, a video summary) has nothing to fit: run it as it is.
Using the Agent Skill
Theatai-custom-agent agent skill teaches a coding agent (Claude Code, Cursor, Codex, and
others) every step on this page. It includes four example blueprints: the one above, a video
summary in batch and in serving, and a trainable anomaly detector. It also has a script that
checks a blueprint against the node registry before you create it. See Agent
Skills to install it.
atai-custom-agent
Write a blueprint from the platform’s agent nodes, check it, create it, set its values on a
copy, package it, and run it in batch or serving, with optimize, promote and eval for
trainable graphs.