> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onecortex.io/llms.txt
> Use this file to discover all available pages before exploring further.

# agent.yml reference

> Every field of agent.yml, the one file you write to deploy an agent on Onecortex, with its type, default, rules and the exact error each mistake produces.

`agent.yml` tells Onecortex which runtime your agent needs and which object in your code is the agent. It is the only file you add to your repository. Onecortex never writes to your repository and never modifies your code.

## The smallest agent.yml

```yaml agent.yml theme={null}
apiVersion: v1
runtime: python3.12
entrypoint: agent.py:agent
```

These three lines deploy a Python agent whose object is named `agent` in `agent.py`. Dependencies are found automatically, and no configuration is required.

## Where the file goes

Put `agent.yml` at the root of the folder Onecortex builds from: the repository root, or the agent folder you pick when you create the agent. The name `agent.yaml` also works. If both exist in the same folder, validation fails with `manifest_ambiguous`: keep one.

Paths inside `agent.yml` are relative to that folder and cannot leave it. An absolute path or any `..` segment fails with `path_escapes_context`.

## Fields

<ParamField path="apiVersion" type="string" required>
  The version of this file's format. The only accepted value is `v1`.

  ```yaml agent.yml theme={null}
  apiVersion: v1
  ```
</ParamField>

<ParamField path="runtime" type="string" required>
  The language runtime your agent runs on.

  | `runtime` | Language | Version |
  | - | - | - |
  | `python3.12` | Python | 3.12 |
  | `python3.11` | Python | 3.11 |
  | `node22` | TypeScript or JavaScript | Node.js 22 |
  | `node20` | TypeScript or JavaScript | Node.js 20 |

  A value that is not in the list fails with `enum_invalid`, which suggests the closest accepted value.
</ParamField>

<ParamField path="entrypoint" type="string" required>
  The file and the name of the agent object in it. The separator depends on the language:

  | Runtime | Format | Example |
  | - | - | - |
  | Python | `path/to/file.py:name` | `agent.py:graph` |
  | TypeScript or JavaScript | `path/to/file.ts#exportName` | `src/agent.ts#agent` |

  TypeScript and JavaScript entrypoints accept `.ts`, `.mts`, `.cts`, `.js`, `.mjs` and `.cjs`. Onecortex recognises the object by what it is, not by what you call it. See [Entrypoints](/build/entrypoints) for how each framework's agent object is found.

  If you use the other language's separator, validation suggests the corrected value. If the file does not exist, it lists the files it found. If the name is not defined at the top level of the file, it lists the names that are.
</ParamField>

<ParamField path="dependencies" type="string" default="found automatically">
  The file your dependencies are installed from. Leave it out and Onecortex takes the first of these that exists in the folder:

  | Language | Looked for, in order |
  | - | - |
  | Python | `uv.lock`, `poetry.lock`, `Pipfile.lock`, `pyproject.toml`, `requirements.txt` |
  | TypeScript | `bun.lock`, `bun.lockb`, `pnpm-lock.yaml`, `package-lock.json`, `yarn.lock`, `package.json` |

  Lockfiles come first because they hold the versions you actually resolved. See [Dependencies](/build/dependencies).
</ParamField>

<ParamField path="framework" type="string">
  The framework your agent uses, for your own records and the dashboard. It does not change how your agent is run: Onecortex recognises the framework from the object itself.

  Accepted: `langgraph`, `langchain`, `crewai`, `strands`, `llamaindex`, `openai-agents`, `autogen`, `pydantic-ai`, `mastra`, `vercel-ai`, `langchain-js`, `other`.
</ParamField>

<ParamField path="systemPackages" type="string[]" default="[]">
  Operating system packages to install into the image. Available: `ffmpeg`, `poppler-utils`. Anything else fails with `system_package_not_allowed`.

  ```yaml agent.yml theme={null}
  systemPackages:
    - ffmpeg
  ```
</ParamField>

<ParamField path="build.commands" type="string[]" default="[]">
  Shell commands to run after dependencies are installed, in order, in one build step. Use them for a step your agent needs at build time, such as downloading a model file.

  ```yaml agent.yml theme={null}
  build:
    commands:
      - python scripts/prepare_index.py
  ```
</ParamField>

<ParamField path="env.required" type="string[]" default="[]">
  The names of configuration entries your agent cannot run without. Names only, never values: values go in your agent's [configuration](/build/configuration) in Onecortex. A name listed here that is not configured shows a warning before you deploy.
</ParamField>

<ParamField path="env.optional" type="string[]" default="[]">
  The names of configuration entries your agent can use when they are set.
</ParamField>

## A complete example

<Tabs>
  <Tab title="Python">
    ```yaml agent.yml theme={null}
    apiVersion: v1
    runtime: python3.12
    entrypoint: agent.py:graph
    framework: langgraph
    dependencies: requirements.txt
    env:
      required:
        - OPENAI_API_KEY
    ```
  </Tab>

  <Tab title="TypeScript">
    ```yaml agent.yml theme={null}
    apiVersion: v1
    runtime: node22
    entrypoint: src/agent.ts#handler
    framework: mastra
    dependencies: package.json
    ```
  </Tab>
</Tabs>

## Rules that apply to the whole file

* **Unknown keys are ignored with a warning**, not a failure: ``Unknown key `mode` will be ignored.``
* **Values that look like credentials fail validation.** `agent.yml` lives in your repository, where everyone with access can read it. A value shaped like a well known API key format, a private key, a long random string, or any value under a key named like `SECRET`, `TOKEN`, `PASSWORD` or `API_KEY` fails with `credential_detected`. Put the secret in your agent's configuration and list its name under `env.required`.
* **`_onecortex/` is reserved.** A folder of that name in your build folder fails with `reserved_directory_present`.

## Validation errors

Every mistake names the line, what was found, what was expected, and a corrected snippet you can copy. The full text of each is on the [errors page](/production/errors#agent-yml-errors).

| Code | Severity | Cause |
| - | - | - |
| `manifest_missing` | error | No `agent.yml` in the build folder |
| `manifest_ambiguous` | error | Both `agent.yml` and `agent.yaml` exist |
| `yaml_syntax_error` | error | The file is not valid YAML |
| `api_version_missing` | error | `apiVersion` is missing |
| `api_version_unsupported` | error | `apiVersion` is not `v1` |
| `field_missing` | error | A required field is missing |
| `field_type_invalid` | error | A field has the wrong type |
| `enum_invalid` | error | A value is not one of the accepted ones |
| `entrypoint_format_invalid` | error | The entrypoint is not in the format for its runtime |
| `entrypoint_runtime_mismatch` | error | The entrypoint's file extension belongs to the other language |
| `entrypoint_file_missing` | error | The entrypoint's file does not exist |
| `entrypoint_attribute_missing` | error | The name is not defined at the top level of the file |
| `path_escapes_context` | error | A path leaves the build folder |
| `system_package_not_allowed` | error | A system package is not available |
| `credential_detected` | error | A value looks like a secret |
| `dependencies_file_missing` | error | The `dependencies` file does not exist |
| `dependencies_not_found` | error | No dependency file was found |
| `reserved_directory_present` | error | The build folder contains `_onecortex/` |
| `unknown_field` | warning | A key Onecortex does not know |
| `env_required_not_configured` | warning | A required name is not configured |
| `tree_truncated` | warning | The repository is too large to check paths before the build |

## Related

* [Quickstart](/quickstart): deploy your first agent.
* [Entrypoints](/build/entrypoints): how the agent object is found.
* [Configuration and secrets](/build/configuration): where values go.