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

# Custom Agent

> Build your own agent by wiring the platform's agent nodes into a blueprint, then package it and run it like any other agent.

When none of the [canonical blueprints](https://docs.archetypeai.app/core-concepts/agents/overview.md#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](https://docs.archetypeai.app/core-concepts/agents/overview.md#the-agent-lifecycle) like any
other blueprint: package, deployment, session.

> [!NOTE]
>
> Creating a blueprint requires the **Admin** role. A Developer gets `403 forbidden`
> ("blueprint creation requires the admin role"). An Admin can
> [copy](https://docs.archetypeai.app/api-reference/agents/blueprints/copy-blueprint.md) 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](#trainable-custom-agents) on your labelled data.

## The Building Blocks

[List Node Registry](https://docs.archetypeai.app/api-reference/agents/nodes/list-node-registry.md)
(`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.

| Group | Nodes (input → output type) |
| - | - |
| Sources | `RecordsSource` (→ Record), `MultiModalSource` (→ `text`: Text, `video`: VideoRef), `TextSource`, `ConversationSource` |
| Sinks | `RecordsSink` (Record), `TextSink` (Text), `ConversationSink`, `MultiheadClassifierSink` |
| Sensor preparation | `ValueInterpolationNode` (Record → Record), `WindowingNode` (Record → Window), `InWindowsInterpolationNode`, `SamplingRateValidationNode`, `LimitValuesValidationNode` (Window → Window), `FlattenWindowsNode` (Window → Record) |
| Sensor models and features | `OmegaEncoderNode` (Window → Record, a 768-dimensional embedding per channel), `ChannelFeaturesNode` (Window → Record) |
| Classical heads | `AnomalyDetectorNode`, `OutlierDetectorNode`, `ClassifierNode`, `MultiheadClassifierNode`, `ClassifierFittingNode`, `AnomalyEventsFormatNode`, `InvalidSplitterNode` |
| Video and audio | `VideoReaderNode` (VideoRef → VideoFrame), `VideoPreprocessorNode`, `ImageReaderNode`, `AudioReaderNode`, `WhisperModelNode` |
| Prompts | `ManualGenerationPromptGeneratorNode`, `TaskVerificationPromptGeneratorNode`, `ChatPromptGeneratorNode` (→ MultiModalPrompt), `PrepareSOPNode` |
| Language models | `NewtonCModelNode`, `NewtonFusionModelNode` (MultiModalPrompt → Text) |
| Parsers | `ManualGenerationResultsParserNode`, `TaskVerificationResultsParserNode` (Text → Record) |
| Plumbing | `TeeNode` (copies its input to named ports), `ConcatColumnsNode` (joins named ports row by row), `SplitterNode`, `RouteNode`, `MergeNode`, `InterleaveNode` |

## 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:

> [accordion] Omega embeddings + channel statistics
>
> ```yaml theme={"system"}
> name: Omega Embeddings + Channel Stats
> description: >
>   Custom Omega-based blueprint. Validates and cleans windows, then tees each
>   window to the Omega encoder and to per-channel summary statistics, and joins
>   both into one row per window. No trained head, so it runs without optimize.
>
> values:
>   # --- Inputs ---
>   timestamp_column: null
>   data_columns: null
>
>   # --- Window (canonical OSM: 1024 / 256) ---
>   window_size: 256
>   step_size: 128
>
>   # --- Data preparation ---
>   stream_interpolation_max_gap: 0
>   window_interpolation_max_gap: 8
>   interpolation_method: ffill
>
>   # --- Validations ---
>   validate_monotonic_timestamps: true
>   sample_rate_interval_tolerance: 0.10
>   max_temporal_gap: 0.05
>   max_nan_gap: 8
>   max_inf: 0
>   min_value: null
>   max_value: null
>
>   # --- Features ---
>   feature_names: [mean, std, slope]
>
> models:
>   encoder: "newton-omega-1-5-safetensors"
>
> connectors:
>   source:
>     key: RecordsSource
>     config:
>       format: csv
>       timestamp_column: ${values.timestamp_column}
>       data_columns: [{ dtype: f32, names: "${values.data_columns}" }]
>   sink:
>     key: RecordsSink
>     config:
>       format: jsonl
>
> nodes:
>   interpolate:
>     key: ValueInterpolationNode
>     config:
>       max_gap: ${values.stream_interpolation_max_gap}
>       method: ${values.interpolation_method}
>
>   window:
>     key: WindowingNode
>     config:
>       window_size: ${values.window_size}
>       step_size: ${values.step_size}
>
>   windowInterpolate:
>     key: InWindowsInterpolationNode
>     config:
>       max_gap: ${values.window_interpolation_max_gap}
>       method: ${values.interpolation_method}
>
>   samplingRate:
>     key: SamplingRateValidationNode
>     config:
>       validate_monotonic_timestamps: ${values.validate_monotonic_timestamps}
>       sample_rate_interval_tolerance: ${values.sample_rate_interval_tolerance}
>       max_temporal_gap: ${values.max_temporal_gap}
>
>   limitValues:
>     key: LimitValuesValidationNode
>     config:
>       max_nan_gap: ${values.max_nan_gap}
>       max_inf: ${values.max_inf}
>       min_value: ${values.min_value}
>       max_value: ${values.max_value}
>
>   tee:
>     key: TeeNode
>     config:
>       ports: [emb, feat]
>
>   encoder:
>     key: OmegaEncoderNode
>     config:
>       model: ${models.encoder}
>
>   features:
>     key: ChannelFeaturesNode
>     config:
>       features: ${values.feature_names}
>
>   fuse:
>     key: ConcatColumnsNode
>     config:
>       ports: [emb, feat]
>
> graph:
>   edges:
>     - { from: source.out, to: interpolate.in }
>     - { from: interpolate.out, to: window.in }
>     - { from: window.out, to: windowInterpolate.in }
>     - { from: windowInterpolate.out, to: samplingRate.in }
>     - { from: samplingRate.out, to: limitValues.in }
>     - { from: limitValues.out, to: tee.in }
>     - { from: tee.emb, to: encoder.in }
>     - { from: tee.feat, to: features.in }
>     - { from: encoder.out, to: fuse.emb }
>     - { from: features.out, to: fuse.feat }
>     - { from: fuse.out, to: sink.in }
> ```

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](https://docs.archetypeai.app/api-reference/projects/create-project.md).

**2. Create the blueprint**

Send the YAML as `yaml_document` to [Create
Blueprint](https://docs.archetypeai.app/api-reference/agents/blueprints/create-blueprint.md), 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.

```bash theme={"system"}
jq -n --arg y "$(cat my-agent.yaml)" --arg p "$PROJECT_ID" \
  '{blueprint_key: "my-agent-template", project_id: $p, yaml_document: $y}' > blueprint.json
curl -X POST "$ATAI_API_ENDPOINT/agents/blueprints" \
  -H "Authorization: Bearer $ATAI_API_KEY" -H "Content-Type: application/json" \
  --data @blueprint.json
```

**3. Set its values on a copy**

A package carries no values of its own, so set them on a copy with [Copy
Blueprint](https://docs.archetypeai.app/api-reference/agents/blueprints/copy-blueprint.md) and `overrides.values`. One
template serves many datasets: make a copy for each set of columns or window size.

```json theme={"system"}
{
  "project_id": "prj_...",
  "blueprint_key": "my-agent",
  "overrides": { "values": { "timestamp_column": "timestamp", "data_columns": ["sensor_a", "sensor_b"] } }
}
```

**4. Build a package**

Build the copy into a package with [Create
Package](https://docs.archetypeai.app/api-reference/agents/packages/create-package.md).

**5. Deploy it and open sessions**

Deploy the package with [Create
Deployment](https://docs.archetypeai.app/api-reference/agents/deployments/create-deployment.md), as `batch` to process
files or `serving` to answer queries, then open a session with [Create
Session](https://docs.archetypeai.app/api-reference/agents/sessions/create-session.md). See [Batch vs. serving
sessions](https://docs.archetypeai.app/core-concepts/agents/batch-and-serving.md).

### 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:

```yaml theme={"system"}
metrics:
  targets:
    - name: anomaly
      type: binary
      predicted: predicted_label
      labels: [${values.anomaly_label}, ${values.normal_label}]
      positive: ${values.anomaly_label}
      pairing: by_time
      objectives: [macro_f1, accuracy, detection_recall, detection_precision]
  primary: anomaly.macro_f1
```

Then follow [Optimizations and Evals](https://docs.archetypeai.app/core-concepts/agents/optimize-and-eval.md) 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](https://docs.archetypeai.app/for-agents/agent-skills.md) to install it.

> [card] [atai-custom-agent](https://github.com/archetypeai/agent-skills/tree/main/skills/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.

## Related Content

* [Agent Lifecycle overview](https://docs.archetypeai.app/core-concepts/agents/overview.md)
* [Optimizations and Evals](https://docs.archetypeai.app/core-concepts/agents/optimize-and-eval.md)
* [Batch vs. serving sessions](https://docs.archetypeai.app/core-concepts/agents/batch-and-serving.md)
* [List Node Registry](https://docs.archetypeai.app/api-reference/agents/nodes/list-node-registry.md)
* [Create Blueprint](https://docs.archetypeai.app/api-reference/agents/blueprints/create-blueprint.md)
* [Agent Skills](https://docs.archetypeai.app/for-agents/agent-skills.md)


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