agent.yml reference

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

agent.yml

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

string

required

The version of this file’s format. The only accepted value is v1.

agent.yml

apiVersion: v1

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.

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

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.

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.

string[]

default:"[]"

Operating system packages to install into the image. Available: ffmpeg, poppler-utils. Anything else fails with system_package_not_allowed.

agent.yml

systemPackages:
  - ffmpeg

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.

agent.yml

build:
  commands:
    - python scripts/prepare_index.py

string[]

default:"[]"

The names of configuration entries your agent cannot run without. Names only, never values: values go in your agent’s configuration in Onecortex. A name listed here that is not configured shows a warning before you deploy.

string[]

default:"[]"

The names of configuration entries your agent can use when they are set.

A complete example

Python
TypeScript

agent.yml

apiVersion: v1
runtime: python3.12
entrypoint: agent.py:graph
framework: langgraph
dependencies: requirements.txt
env:
  required:
    - OPENAI_API_KEY

agent.yml

apiVersion: v1
runtime: node22
entrypoint: src/agent.ts#handler
framework: mastra
dependencies: package.json

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.

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

Quickstart: deploy your first agent.
Entrypoints: how the agent object is found.
Configuration and secrets: where values go.

Get started

Build your agent

Frameworks

Deploy

Call your agent

Observe

Production

Organizations

Resources

agent.yml reference

The smallest agent.yml

Where the file goes

Fields

A complete example

Rules that apply to the whole file

Validation errors

​The smallest agent.yml

​Where the file goes

​Fields

​A complete example

​Rules that apply to the whole file

​Validation errors

​Related

The smallest agent.yml

Where the file goes

Fields

A complete example

Rules that apply to the whole file

Validation errors

Related