Trigger dagraph workflows via webhook or cron schedule

agentgraph schedule and agentgraph serve turn a DAG YAML into a long-running service. schedule fires the workflow on a cron expression and blocks until you press Ctrl+C. serve starts an HTTP server that runs the workflow when it receives a POST request, and optionally also runs on a cron schedule. Both commands require the serve extras package.

pip install 'dagraph[serve]'

schedule
serve

agentgraph schedule

Run a DAG on a repeating cron schedule. Each tick creates a new run with a fresh run ID. If the previous run is still in progress when the next tick fires, that tick is skipped and a warning is logged — runs never overlap.

agentgraph schedule <dag_path> --cron "<expression>" [OPTIONS]

Arguments and flags

dag_path

string

required

Path to the DAG YAML file.

--cron

string

required

5-field cron expression in the format minute hour day month weekday. For example, 0 9 * * 1-5 runs at 09:00 on weekdays.

--input / -i

string

Static inputs passed to every run. Repeat for multiple values. These are the same across all ticks; use a user_input node if you need dynamic values per run.

--runs-dir

string

default:"runs"

Directory where run subdirectories are created.

--backend

string

default:"claude_code"

Executor backend. See agentgraph run for options.

--sandbox

string

Sandbox for exec nodes (inprocess or docker).

--rpm

number

Requests-per-minute cap across all nodes.

--max-concurrent

number

default:"10"

Maximum simultaneous LLM calls per run.

Examples

agentgraph schedule examples/research.yaml \
  --cron "0 9 * * 1-5" \
  --input topic="AI news"

Non-overlapping execution

If a run is still in progress when the next cron tick fires, the scheduler skips that tick and logs a warning:

⚠ cron tick skipped: previous run still in progress (job ...)

This guarantees at most one concurrent execution of your DAG, regardless of how long each run takes.

agentgraph serve

Start an HTTP server that triggers a DAG run when it receives a POST request. The JSON body keys are merged with any --input defaults and passed to the DAG as template inputs. The server responds synchronously with the run ID and status once the run completes.You can combine a webhook trigger and a cron schedule in a single serve invocation.

agentgraph serve <dag_path> [OPTIONS]

Arguments and flags

dag_path

string

required

Path to the DAG YAML file.

--webhook

string

URL path to expose for POST requests, for example /trigger. At least one of --webhook or --cron must be provided.

--cron

string

Also run the DAG on a cron schedule while the server is running.

--webhook-secret

string

If set, all incoming requests must include the header Authorization: Bearer <secret>. Reads from the AGENTGRAPH_WEBHOOK_SECRET environment variable if the flag is not passed explicitly.

--host

string

default:"127.0.0.1"

Host address to bind the server to.

--port

number

default:"8000"

Port to listen on.

--input / -i

string

Base inputs merged with the webhook JSON body on every request. Webhook body values take precedence over --input defaults.

--runs-dir

string

default:"runs"

Directory where run subdirectories are created.

--backend

string

default:"claude_code"

Executor backend.

--sandbox

string

Sandbox for exec nodes.

--rpm

number

Requests-per-minute cap.

--max-concurrent

number

default:"10"

Maximum simultaneous LLM calls.

Examples

agentgraph serve examples/research.yaml --webhook /trigger

Triggering the webhook

Send a POST request with a JSON body. Body keys are merged with any --input defaults and passed to the DAG as template variables:

curl -X POST http://localhost:8000/trigger \
  -H "Content-Type: application/json" \
  -d '{"topic": "quantum computing"}'

With authentication:

curl -X POST http://localhost:8000/trigger \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer my-secret-token" \
  -d '{"topic": "quantum computing"}'

Webhook response

The server responds synchronously after the run completes:

{
  "run_id": "a1b2c3d4e5f6",
  "status": "completed"
}

Possible status values are completed, failed, and paused (if the DAG hit an approval gate).

serve runs each triggered DAG synchronously in the same process. For high-throughput use cases, consider the dagraph cloud or self-hosted control-plane, which queues runs in a job worker.

Commands

​agentgraph schedule

​Arguments and flags

​Examples

​Non-overlapping execution

​agentgraph serve

​Arguments and flags

​Examples

​Triggering the webhook

​Webhook response

agentgraph schedule

Arguments and flags

Examples

Non-overlapping execution

agentgraph serve

Arguments and flags

Examples

Triggering the webhook

Webhook response