Comprehensive framework manual

Start here to choose a guide for your task. The atfg CLI starts local servers, manages node packages, submits work and reads results. The Python SDK lets application teams write nodes and call the same shared server. This page also collects common commands and exit codes.

A graph server schedules work and stores its record. An agent node registers a label, version and capabilities: traversals coordinate work, skills conventionally perform a focused operation, and decisions return typed judgments. None must call a model. Starting a capability creates a traverser; its path records steps. atfg wait waits at the barrier until the run finishes. See Core concepts.

Reading order

1. Read Overview for the platform's scope and the division of responsibilities.
2. Follow Quickstart to run a server and node, submit work and inspect its path.
3. Use Core concepts to understand the terms.
4. Read the comparison guide when choosing how ATFGraph fits your stack.
5. Choose a task guide below.

1. Look up details in the HTTP reference, CLI reference and Troubleshooting.

Which side are you on?

Calling existing agents. You need the graph server URL and the credentials its operator provides. Submit work and read results through a client library, CLI or Console. You do not need to host a worker to call a node that another team already operates.

export ATFGRAPH_SERVER=http://127.0.0.1:18880   # or a remote server
export ATFGRAPH_API_KEY=...                      # required off loopback
atfg ls
atfg traverse co-consult.consult --in '{"request":"A relaxed family trip to Tokyo"}' --new-session

Building agents. You write the node's behavior and run an outbound worker. It registers with the server, claims tasks for its label/version, renews leases, reports progress and returns results. Standard workers open no inbound port. Run one in your terminal with atfg dev, install a package with atfg install and atfg run, or use a deployment target. The shared server provides the execution services; your team supplies code, configuration and ongoing node operation.

CLI command table

Common global flags are --server/-s (ATFGRAPH_SERVER, default http://127.0.0.1:18880), --api-key/-k (ATFGRAPH_API_KEY, sent as X-API-Key), --json, --timeout <s> (HTTP timeout, default 30), and --state-dir (ATFGRAPH_VNEXT_HOME). See the generated CLI reference for the full command set and options. A platform proxy may require its own credential separately.

Pass named inputs as a JSON object directly to --in. Use --in-file - to read that object from stdin.

Exit codes

Typical session

atfg ls
ID=$(atfg traverse hello.greet --in '{"name":"Ada"}' --async)
atfg ps --status queued
atfg wait "$ID" --wait-timeout 120 || echo "exit $?"
atfg path "$ID"
atfg --json show "$ID" | jq .output

Troubleshoot a running node

atfg doctor
atfg server status
atfg ls
atfg ps
atfg show <traverser-id>
atfg path <traverser-id>
atfg logs <node-name> --tail 100

If atfg ls does not show the label, check the worker process, server URL, namespace and registration logs. For a failed call, inspect the traverser and its path to find the failing step. Troubleshooting maps common messages to corrective actions.