> ## 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 Direct Query API (POST /api/lens/query) with the Newton Fusion model (text, image, and video reasoning) or the Newton Omega 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.

# Create Agent

> Run a ready package as a batch job or a serving agent, creating a new agent instance

Requires [version 2.0.0](https://docs.archetypeai.app/release-notes/2.0.x.md#v2-0-0) or later of the Archetype platform.

## Overview

This endpoint runs a [package](https://docs.archetypeai.app/api-reference/agents/packages/create-package.md) and returns the
created agent.

The package fixes everything about how the agent behaves: its blueprint, the blueprint's values,
and the model every slot resolved to when the package was built. The request only says how to
run it and binds its I/O. To change anything else, build a new package.

`mode` picks how the agent executes:

* `batch` (the default) processes the input files in `connectors.source` and finishes.
* `serving` stays up to answer queries over [Query
  Agent](https://docs.archetypeai.app/api-reference/agents/instances/query-agent.md) and `/api/agents/instances/{agent_id}/connect`.
  A serving run takes its input from each query, so it must not send `connectors`.

A batch run is returned `running`. A serving run is returned `deploying`, before it is placed:
poll [Get Agent](https://docs.archetypeai.app/api-reference/agents/instances/get-agent.md) until it is `running` before you query
it. Follow either kind through its events, logs, and results, exactly as a run of a bundle.

The run is owned by the caller, or by the project's creator when the package is in a project.
Other members of the organization cannot see it unless they are org admins.

## Request

**package\_id** `string` *required*

The `pkg_` id of the package to run. It must be `ready`, built for the `platform` target, and
hold exactly one blueprint.

**mode** `string` (default: batch)

How the agent executes: `batch` processes the inputs and finishes; `serving` stays up to answer
queries.

**connectors** `object`

The run's input files and optional output file. A `batch` run must list at least one `file`
ref in `source`. A `serving` run must omit `connectors`.

**connectors.source** `array`

One or more input refs. Each entry is a data ref.

**connectors.sink** `object`

Optional output ref; omit it or send `null` for the default. It must not name an output that
already exists. Omitted: the runner writes one output per input, named after the input.
Provided: for concatenable formats (for example CSV) all output folds into this single file.

### Data ref

**type** `string` *required*

Storage kind, for example `file`.

**id** `string` *required*

Identifier within that storage kind, for example `file_abc123`.

**format** `string`

Optional format hint, for example `csv`.

## Response

Returns `202 Accepted` with the created agent.

**id** `string` *required*

TypeID-encoded agent identifier (`agt_` prefix).

**name** `string` *required*

The run's name. For a run of a package, this is the package's name.

**org\_id** `string` *required*

Organization the agent belongs to.

**package\_id** `string`

The package this agent was run from (provenance). Absent for a run of a bundle, which carries
`bundle_id` instead.

**blueprint** `string` *required*

Human-readable blueprint reference (its key), for example `osm`.

**blueprint\_id** `string` *required*

Immutable blueprint id the package holds.

**mode** `string` *required*

How the agent executes: `batch` or `serving`.

**status** `string` *required*

Agent lifecycle status. A new run is `running`, or `deploying` for a `serving` run.

**project\_id** `string`

The project the run is in, which is its package's project. `null` outside any project.

**connectors** `object`

The I/O binding this run was started with.

**job\_id** `string`

The executor's job id for this run. Present once the run has been dispatched.

**created\_at** `string` *required*

When the run was created (date-time).

**started\_at** `string`

When the run began executing. Absent until it has been dispatched.

**completed\_at** `string`

When the run reached a terminal status. Absent while it is unfinished.

**error** `string`

Why the run failed. Present only when `status` is `failed`.

```bash cURL - Batch Run theme={"system"}
curl -X POST "$ATAI_API_URL/api/agents/instances" \
  -H "Authorization: Bearer $ATAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "package_id": "pkg_01jcb2x7m4qv8n3h5t6rk9dzs0",
    "connectors": {
      "source": [
        {"type": "file", "id": "file_abc123", "format": "csv"}
      ]
    }
  }'
```

```bash cURL - Serving Agent theme={"system"}
curl -X POST "$ATAI_API_URL/api/agents/instances" \
  -H "Authorization: Bearer $ATAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "package_id": "pkg_01jcb2x7m4qv8n3h5t6rk9dzs0",
    "mode": "serving"
  }'
```

```python Python theme={"system"}
import os
import requests

base_url = os.environ["ATAI_API_URL"]
api_key = os.environ["ATAI_API_KEY"]

response = requests.post(
    f"{base_url}/api/agents/instances",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json={
        "package_id": "pkg_01jcb2x7m4qv8n3h5t6rk9dzs0",
        "connectors": {
            "source": [{"type": "file", "id": "file_abc123", "format": "csv"}],
        },
    },
)

if response.status_code == 202:
    agent = response.json()
    print(f"Run accepted: {agent['id']} (status {agent['status']})")
else:
    print(f"Error: {response.json()['errors']}")
```

```javascript JavaScript theme={"system"}
const response = await fetch(`${process.env.ATAI_API_URL}/api/agents/instances`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.ATAI_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    package_id: 'pkg_01jcb2x7m4qv8n3h5t6rk9dzs0',
    connectors: {
      source: [{ type: 'file', id: 'file_abc123', format: 'csv' }]
    }
  })
});

const body = await response.json();

if (response.status === 202) {
  console.log(`Run accepted: ${body.id} (status ${body.status})`);
} else {
  console.error('Error:', body.errors);
}
```

```json 202 - Run accepted theme={"system"}
{
  "id": "agt_01jcb3k8p5rw9t2bkz4dhs6fmq",
  "name": "Pump line 3",
  "org_id": "org_01jc8m5r2vq9xt4bn7h3kdzs6w",
  "package_id": "pkg_01jcb2x7m4qv8n3h5t6rk9dzs0",
  "blueprint": "osm",
  "blueprint_id": "blp_01jc9n7k3xf8mbq2v5t0ary6de",
  "mode": "batch",
  "connectors": {
    "source": [
      {"type": "file", "id": "file_abc123", "format": "csv"}
    ],
    "sink": null
  },
  "status": "running",
  "project_id": null,
  "created_at": "2026-10-21T15:20:00Z"
}
```

```json 400 - Request does not fit the mode theme={"system"}
{
  "errors": [
    {
      "code": "bad_request",
      "message": "<reason>",
      "suggestion": null,
      "error_uid": "err-xxxxxxxx"
    }
  ]
}
```

```json 403 - Blueprint not available theme={"system"}
{
  "errors": [
    {
      "code": "capability_locked",
      "message": "Blueprint not available to the caller's organization.",
      "suggestion": "Contact support@archetypeai.dev to unlock it.",
      "error_uid": "err-xxxxxxxx"
    }
  ]
}
```

```json 404 - Package not found theme={"system"}
{
  "errors": [
    {
      "code": "not_found",
      "message": "Package 'pkg_01jcb2x7m4qv8n3h5t6rk9dzs0' not found",
      "suggestion": null,
      "error_uid": "err-xxxxxxxx"
    }
  ]
}
```

```json 409 - Package not ready theme={"system"}
{
  "errors": [
    {
      "code": "conflict",
      "message": "package 'pkg_01jcb2x7m4qv8n3h5t6rk9dzs0' is not ready to run; wait until its status is `ready`",
      "suggestion": null,
      "error_uid": "err-xxxxxxxx"
    }
  ]
}
```

```json 429 - Serving limit reached theme={"system"}
{
  "errors": [
    {
      "code": "serving_limit_reached",
      "message": "Your organization already has 5 serving agents running, the most it may run at once.",
      "suggestion": "Cancel a running serving agent, then retry.",
      "error_uid": "err-xxxxxxxx"
    }
  ]
}
```

## Important Notes

> [!NOTE]
>
> * A `400` means the package was built for a target other than `platform` or holds more than one blueprint, or the request does not fit the mode: a `batch` run sent no `file` ref in `connectors.source`, or a `serving` run sent `connectors`. It also covers a `serving` run whose blueprint cannot be served, which creates no agent.
> * When the package is in a project, the run may only read `source` files the project's creator can see. Any other file returns `400`.
> * A `403` with code `capability_locked` means the package's blueprint is not available to your organization. A `403` without that code means you can see the package's project but cannot modify it.
> * A `409` means the package is not `ready` yet, or the `sink` names an output that already exists.
> * A `429` with code `serving_limit_reached` means your organization already runs as many serving agents as it may. Cancel one, then retry.
> * A `501` means `serving` was requested in an environment where serving is not enabled.
> * A serving run that cannot be placed or started ends `failed` with the reason in `error`. Create another instance to retry.
> * A package cannot be deleted while runs from it exist. Find them with [List Agents](https://docs.archetypeai.app/api-reference/agents/instances/list-agents.md) and `package_id`.


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