Package, install & run a node

Install a node from a directory, archive or Git repository, then run it as a background worker with persistent logs and process metadata.

For development in a terminal, use atfg dev as shown in the Quickstart. The commands here install a package and manage its detached worker.

The manifest: agentnode.yaml

An installable node has an agentnode.yaml file at the root of its directory, Git repository or atfg package archive. Use config_version: v2. vNext accepts the existing fields and the additional entrypoint.module field. Either entrypoint form below identifies the Python object to load:

config_version: v2
name: hello                       # package name and default label
version: 1.0.0
description: Greets travellers
entrypoint:
  start: python -m atfgraph.worker --module hello_node.agent:app   # compatible form
  # module: hello_node.agent:app                                  # or the additive key
agent_node:
  node_id: hello                  # label if it differs from name
dependencies:
  python: [pydantic>=2]           # pip installed after requirements.txt and `pip install .`
user_environment:
  required:
    - name: HELLO_REGION
      description: region label used in logs
  require_one_of:
    - options: [{name: SOURCE_URL}, {name: SOURCE_FILE}]
  optional:
    - name: HELLO_LOG_LEVEL
      default: INFO

The installer rejects languages other than python, configuration versions above v2, and entrypoint.start commands that do not invoke the worker. It installs one package at a time. It reports dependencies.nodes without resolving those dependencies. For a complete small manifest, see examples/python/first_node/agentnode.yaml.

Install, run, stop

atfg install ./hello --python python3.12          # or https://github.com/org/repo//subdir@v1.2.3, or hello-1.0.0.tar.gz
atfg run hello                                    # detached worker; waits until `hello` is registered
atfg list                                         # NAME VERSION LABEL PROCESS PID ON SERVER MODULE
atfg traverse hello.greet --in '{"name":"Ada"}'
atfg logs hello --tail 50
atfg stop hello                                   # SIGTERM -> drain -> exit
atfg uninstall hello

Installation copies the source into the package directory and creates <state>/packages/<name>/venv with the selected --python. Git clones are shallow; .git, virtual environments, caches and .env files are excluded.

The installer finds the SDK through --sdk, ATFGRAPH_SDK, a wheel beside the binary or the source checkout. It then installs requirements.txt, the project itself when it has pyproject.toml or setup.py, and dependencies.python. installed.json records the source, resolved Git commit, manifest digest and Python interpreter. Select Python 3.10 or newer; the macOS default Python 3.9 is refused. See Troubleshooting.

Before starting a worker, run resolves user_environment from your shell and the package's .env files. It reports missing required variables and unsatisfied require_one_of groups. SDK settings do not need individual manifest declarations: .env values beginning with ATFGRAPH_* or MLFLOW_*, plus DATABRICKS_HOST, DATABRICKS_TOKEN and DATABRICKS_CONFIG_PROFILE, reach the worker.

The worker runs in its own process group. Its log is <pkg>/worker.log, and run.json stores its PID. Once the label registers, the CLI prints the version and capability count. It exits with 1 and the log tail if the worker dies first, or 2 if --wait expires; in the latter case the worker stays running.

stop signals the recorded PID only after checking that its command line still identifies this package's worker. It leaves reused PIDs alone. The state directory defaults to ~/.atfgraph-vnext; change it with --state-dir or ATFGRAPH_VNEXT_HOME.

Package an artifact

atfg package ./hello --out target/dist/packages
# packaged hello 1.0.0 (4 files) -> target/dist/packages/hello-1.0.0.tar.gz
# sha256 ...   metadata hello-1.0.0.package.json   checksums SHA256SUMS
atfg install target/dist/packages/hello-1.0.0.tar.gz

The archive uses the same file exclusions as installation. Its metadata records each file's SHA-256, the worker module, the manifest digest and the Git commit when available. Verify the output directory's SHA256SUMS with shasum -a 256 -c. Digests identify the packaged files; different tar implementations may still produce different archive bytes.

Related

• Write capabilities with the Python SDK.
• Deploy the node in a container with Docker Compose.