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"
}

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.

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