Skip to main content

​
Overview

Every AO project needs an ao.toml file in the project root. Run ao init to generate one automatically.

​
Full example

name = "my-agent"
framework = "langgraph"
entrypoint = "./graph.py:graph"

python = "3.11"

[runtime]
max_retries = 3
timeout = 300

[schedule]
cron = "0 9 * * *"

​
Fields

​
name

Optional. The name of your project. Must be at least 3 characters, lowercase. If you don’t declare the name, a random name will be generated for each deployment which is not desired. 
name = "my-agent"

​
framework

Optional. The framework your agent uses. AO uses this to inject the right runtime wrapper around your code. 
framework = "langgraph"
For LangGraph agents, AO automatically detects your langgraph.json and injects the graph at runtime, no extra wiring needed.

​
entrypoint

Required. Path to your agent’s main Python file, relative to the project root. 
entrypoint = "./graph.py:graph"

​
python

Optional. The python version used on your project. The default is 3.11. 
python = "3.11"

​
[runtime]

Controls retry and timeout behavior for every run.

​
max_retries

Number of times AO will retry a failed run before marking it as failed. Uses exponential backoff between attempts.
  • Default: 3
  • Type: integer
[runtime]
max_retries = 5

​
timeout

Maximum time in seconds a single run is allowed to execute. If exceeded, the container is killed and the run is retried.
  • Default: 300 (5 minutes)
  • Type: integer
[runtime]
timeout = 600 # 10 minutes

​
[schedule] (optional)

Run your agent automatically on a schedule.

​
cron

A standard cron expression defining when to run the agent. 
[schedule]
cron = "0 9 * * *" # every day at 9am

Cron expression reference

Use crontab.guru to build and test cron expressions.

​
Environment variables

Your agent has access to these environment variables at runtime:
VariableDescription
AO_RUN_IDUnique ID for the current run
AO_ATTEMPTCurrent attempt number (1-indexed)
AO_LAST_ERRORError message from the previous failed attempt, if any
AGENT_INPUTJSON object with the input passed via ao run --input