Skip to main content

agentflow.json configuration

agentflow.json is the configuration file the CLI reads at startup. Place it in your project root (next to your graph/ folder).

Minimal example​

{
  "agent": "graph.react:app"
}

Full example​

{
  "agent": "graph.react:app",
  "checkpointer": "graph.dependencies:my_checkpointer",
  "store": "graph.dependencies:my_store",
  "injectq": "graph.dependencies:container",
  "thread_name_generator": "graph.thread_name_generator:MyNameGenerator",
  "authorization": "graph.auth:my_authorization_backend",
  "env": ".env",
  "auth": "jwt",
  "rate_limit": {
    "enabled": true,
    "backend": "memory",
    "requests": 100,
    "window": 60,
    "by": "ip",
    "exclude_paths": ["/health", "/docs", "/redoc", "/openapi.json"]
  }
}

Fields​

agent (required)​

The import path to your compiled CompiledGraph, in the format module.path:variable.

"agent": "graph.react:app"
  • graph.react — the Python module path (relative to the project root)
  • app — the variable name that holds the compiled graph

The CLI imports this module at startup and calls the variable as the graph for every request.

checkpointer​

Import path to a BaseCheckpointer instance.

"checkpointer": "graph.dependencies:my_checkpointer"

If omitted, the graph uses no checkpointer and each request is stateless.

In graph/dependencies.py:

from agentflow.storage.checkpointer import InMemoryCheckpointer

my_checkpointer = InMemoryCheckpointer()

store​

Import path to a BaseStore instance.

"store": "graph.dependencies:my_store"

Required if you want to use the /v1/store/* endpoints.

injectq​

Import path to an injectq dependency injection container.

"injectq": "graph.dependencies:container"

Use this when your graph nodes or tools depend on services that need to be resolved at startup.

thread_name_generator​

Import path to a class that generates display names for threads.

"thread_name_generator": "graph.thread_name_generator:MyNameGenerator"

The class must implement a generate(thread_id: str) -> str method.

authorization​

Import path to a custom authorization backend.

"authorization": "graph.auth:my_authorization_backend"

See Auth for details on building a custom authorization backend.

env​

Path to a .env file that is loaded before the graph module is imported.

"env": ".env"

Variables in this file are available to all modules as os.environ values.

auth​

Authentication method. Accepted values:

ValueDescription
nullNo authentication (default)
"jwt"JWT bearer token authentication
{"method": "custom", "path": "module:backend"}Custom auth backend

JWT auth:

"auth": "jwt"

Requires JWT_SECRET_KEY and JWT_ALGORITHM environment variables.

Custom auth:

"auth": {
  "method": "custom",
  "path": "graph.auth:MyAuthBackend"
}

See Auth reference for the custom backend interface.

rate_limit​

Sliding-window rate limiter configuration.

"rate_limit": {
  "enabled": true,
  "backend": "memory",
  "requests": 100,
  "window": 60,
  "by": "ip",
  "exclude_paths": ["/health", "/docs", "/redoc", "/openapi.json"]
}

Omit this field (or set it to null) to disable rate limiting entirely.

For the full field reference, backend options, response headers, and custom backend interface see Rate Limiting.

test​

Default settings for agentflow test. All fields are optional. CLI flags always take precedence.

"test": {
  "path": "tests",
  "coverage": true,
  "coverage_threshold": 70
}
FieldTypeDefaultDescription
pathstring—Default path passed to pytest when no PATH argument is given on the CLI. Omit to let pytest auto-discover tests.
coveragebooleanfalseEnable coverage collection by default (equivalent to --coverage flag)
coverage_thresholdinteger—Minimum coverage percentage required for a passing run. Adds --cov-fail-under=N to the pytest command. Omit to skip threshold enforcement.

Example — enforce 80 % coverage on every run:

{
  "agent": "graph.react:app",
  "test": {
    "path": "tests",
    "coverage": true,
    "coverage_threshold": 80
  }
}

evaluation​

Default settings for agentflow eval. All fields are optional. CLI flags always take precedence.

"evaluation": {
  "directory": "evals",
  "output_dir": "eval_reports",
  "threshold": 0.75,
  "timestamp_files": true
}
FieldTypeDefaultDescription
directorystring"evals"Directory scanned for eval files when no TARGET argument is given
output_dirstring"eval_reports"Directory where HTML and JSON report files are written
thresholdfloat—Minimum pass rate (0.0–1.0) required for a passing run. Omit to skip threshold enforcement.
timestamp_filesbooleantrueAppend a timestamp to report filenames so runs do not overwrite each other

Example — enforce 75 % pass rate and write reports to ci/reports/:

{
  "agent": "graph.react:app",
  "evaluation": {
    "directory": "evals",
    "output_dir": "ci/reports",
    "threshold": 0.75
  }
}

Loading order​

When the CLI starts:

  1. Reads agentflow.json
  2. Loads .env if env is set
  3. Imports the module specified in agent and gets the compiled graph
  4. Imports and configures checkpointer, store, injectq, and authorization if set
  5. Starts the FastAPI server
Last updated on