Skip to main content
When none of the canonical blueprints fits your task, you can write your own. A custom agent is a blueprint you author: you choose which of the platform’s agent nodes to use (the Omega encoder, windowing and validation, channel features, anomaly and classifier heads, Newton C 2.6 or Newton Fusion over video), connect them into a graph, and register the result as a blueprint in a project. From then on it moves through the agent lifecycle like any other blueprint: package, deployment, session.
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:
The rules the platform enforces:
  • Exactly one source and one sink, named source and sink under connectors. 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’s text and video). TeeNode and ConcatColumnsNode take theirs from config.ports: ports: [emb, feat] gives tee.emb, tee.feat, fuse.emb and fuse.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.
  • values are the interface. Reference them as ${values.name} anywhere in a node’s config, and models as ${models.name}. Leave what you can’t know in advance as null (such as timestamp_column and data_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_STATE and no score, and the session still completes.
  • A completed batch session can still be all invalid. Check the invalid column of the results, not only the session status. And read the job’s events when a batch session stays running: an ERROR event means it has failed.
  • Batch graphs end in a RecordsSink. A graph that ends in TextSink fails in batch. For a language-model graph in batch, end it the way the canonical Manual Generation blueprint does: a results parser, then a RecordsSink with format: json/per-request. TextSink works 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, or MultiheadClassifierNode, with its model left empty (models: { detection_head: }). Each trial fits it, and promoting a trial fills it in.
  • A metrics section that names what to score:
Then follow Optimizations and Evals with your blueprint in place of a canonical one: optimize it, promote the best trial, evaluate the promoted blueprint once on held-out data, and package it. In an optimization’s 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

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