Node manifest & configuration

agentnode.yaml describes a node release. The hosted platform reads its identity, Python entrypoint and deployment settings. Keep it at the root of the directory created by atfg new, beside requirements.txt and tests/.

This page covers the current hosted manifest and the related files and settings you control. Python capability behavior belongs in your node code; graph-server configuration belongs to AI-LAB.

A complete hosted example

This example matches a Python package named hello_world with an app object in hello_world/agent.py:

config_version: v2
name: hello-world
version: 0.1.0
description: A deterministic greeting
language: python
entrypoint:
  module: hello_world.agent:app
agent_node:
  node_id: hello-world
dependencies:
  python: []
deploy:
  capacity: 8
  smoke: greet
  secrets: []
  egress: []

The object in Python must use the same node identity and version:

from atfgraph import Agent

app = Agent(node_id="hello-world", version="0.1.0")

@app.skill()
async def greet(name: str) -> dict:
    return {"greeting": f"Hello {name}!"}

The original scaffold may name its smoke capability hello. If you replace it with greet, update both the manifest and smoke input. Team and project ownership come from registration through atfg new; do not add invented team or project manifest fields to change ownership.

Fields read by hosted deployment

Field	Type / default	Meaning and constraints
`name`	Required string	Must match the registered node label. Use the name generated by `atfg new`, with lowercase letters and hyphens. The Python package uses underscores where needed.
`version`	Required string	`MAJOR.MINOR.PATCH`, optionally followed by a prerelease suffix such as `-rc.1`. A new upload must be greater than the latest version; build metadata such as `+build` is not accepted by the release validator. Keep the Python `Agent` version aligned.
`description`	String; empty when omitted	Human-readable release metadata. Use a simple one-line value.
`entrypoint.module`	Required string	Python import target, normally `package.module:app`. The referenced object must be an ATFGraph `Agent`; the hosted worker verifies its identity and version.
`deploy.capacity`	Integer; default `8`	Capacity passed to the node's worker. Use a positive integer. This is worker concurrency, not a count of apps, replicas or CPUs. No documented maximum is enforced by the manifest parser; capacity changes do not provision compute.
`deploy.smoke`	Capability name	Required for a verified hosted rollout. Use the unqualified capability, e.g. `greet`, not `hello-world.greet`. The pipeline calls `<name>.<smoke>` using the matching entry in `tests/smoke.json`.
`deploy.secrets`	Inline list of names; default `[]`	Names of environment variables the node receives through managed secret bindings. Declare names here and set values with `atfg secret set`. Missing bindings prevent worker startup.
`deploy.egress`	Inline list of `host:port`; default `[]`	External destinations declared for deployment review, e.g. `["api.example.com:443"]`. The gateway requires a port. A first outbound declaration or newly added destination can require approval, including in dev. The declaration alone does not grant credentials or prove network connectivity.

The default capacity should be omitted or set explicitly to a positive value. Do not use 0 as an off switch: the gateway currently substitutes 8 while later stages read the raw manifest, so zero is not a consistent configuration.

Scaffold metadata and compatibility fields

These fields appear in the Python scaffold or older framework packaging guides. Keep the generated values, but distinguish them from the hosted deployment controls above.

Field	Recommended value	Current hosted behavior
`config_version`	`v2`	Scaffold format marker. The lightweight hosted release reader does not negotiate configuration versions.
`language`	`python`	Scaffold metadata; changing this does not enable another runtime.
`agent_node.node_id`	Same as `name`	Packaging metadata. Hosted execution checks the actual Python `Agent.node_id` against the registered label. This field does not override it.
`dependencies.python`	Keep scaffold metadata aligned; use `requirements.txt` for actual extra dependencies	The hosted pipeline installs pinned `requirements.txt` dependencies. It does not install this manifest list. The scaffold's `pydantic>=2,<3` declaration is not a substitute for exact dependency pins.

entrypoint.start, dependencies.nodes, user_environment, host, arbitrary env maps, CPU/memory limits, replica counts and provider settings are not consumed as hosted manifest controls. Some belong to other framework workflows. An unknown field can be ignored rather than rejected, so successful parsing does not prove it has any effect. Contact AI-LAB for hosting/isolation or platform configuration changes.

Supported YAML shape

Keep the simple block mappings shown above, one scalar per line. Use inline lists for the two deployment lists:

deploy:
  capacity: 4
  smoke: greet
  secrets: [SUPPLIER_API_KEY]
  egress: ["api.example.com:443"]

The gateway and CLI read a limited YAML shape; they are not general YAML parsers. Do not use anchors, aliases, folded/multiline scalars, duplicate keys or flow mappings for sections. In particular, block-style - item lists under deploy.secrets or deploy.egress are not read correctly by the current gateway parser. Keep comments separate or preceded by a space as in the scaffold.

Smoke input: tests/smoke.json

The object is keyed by the capability name in deploy.smoke:

{
  "greet": {"name": "Ada"}
}

Choose a small, deterministic, safe-to-repeat smoke call. Local build checks that the file exists when a smoke capability is declared; the pipeline checks that its matching input is present, and deployment submits the smoke run through the graph. The current rollout check verifies successful run status, not an expected-output assertion. Use local tests for exact output expectations.

Dependencies: requirements.txt

List every additional dependency at an exact version using package==version, one per line. A comments-only file is valid when no additional packages are needed. The platform supplies the ATFGraph SDK; do not add atfgraph to this file.

Hosted dependency checks are stricter than merely having a == somewhere in a line. Avoid version ranges, editable installs, option lines, direct URLs and unpinned requirements. Nodes sharing an app must not pin the same package to incompatible versions; shared staging rejects conflicting pins. Discuss incompatible dependencies or isolation requirements with AI-LAB.

Secrets and environment

Set each declared secret in the selected team/environment:

atfg --team sandbox --env dev secret set hello-world SUPPLIER_API_KEY
atfg --team sandbox --env dev secret ls hello-world

The first command reads a hidden prompt or stdin. Do not put the value in the manifest. The worker exposes declared names through the process environment, so node code can read os.environ["SUPPLIER_API_KEY"].

.env.example documents variable names without values. A local .env file is not a hosted configuration upload; keep it out of the release. The graph connection and worker identity are provided by the platform. Shared workers currently use one process: conflicting values for the same secret name across nodes are rejected, and this arrangement is not a process-isolation boundary. Ask AI-LAB when a node needs separate hosting.

Release contents: .atfgignore

The installer-generated .atfgignore excludes caches, local environments and secret-looking files. The CLI always excludes .git, __pycache__, .pytest_cache, .ruff_cache, .mypy_cache, .venv, node_modules, .DS_Store and .atfg.toml.

Additional entries use a small matching syntax, not the full .gitignore language:

Pattern	Effect
`scratch/`	Exclude the directory and its descendants; a matching path component is also excluded.
`.env`	Exclude that file name/path component.
`*.pem`	Exclude paths or file names ending in `.pem`.
`# comment` or a blank line	Ignored.

Negation (!), arbitrary glob patterns and .gitignore precedence are not supported. Check the build's included-file count and keep each node in its own directory. Never hide the manifest, required source, requirements or smoke input from the release.

Local node state: .atfg.toml

atfg new and atfg pull create this file. It holds node_id, label, team, project and base_version, linking the local directory to the registered node. It is excluded from release uploads. Do not edit IDs to move a node between projects or teams; use supported registration/source workflows and ask AI-LAB about ownership changes.

CLI settings and environment overrides

These configure your local tools, not the node's runtime:

Setting	How to set it	Behavior
Default team	`atfg config set team <team>`	Overridden by `ATFG_TEAM`, then `--team`.
Default environment	`atfg config set env dev`	Accepts `dev` or `prod`; overridden by `ATFG_ENV`, then `--env`. Default is `dev`.
Service endpoint	`atfg config set api <url>`	Defaults to the installed service address; `ATFG_API` overrides it. Change only when AI-LAB provides another endpoint.
Local state/install location	`ATFG_HOME`	Defaults to `~/.atfgraph`. An explicit value uses isolated session storage and changes where the CLI looks for configuration and the managed Python environment. Pointing it at an empty directory is not a new installation.

Use atfg config show to inspect defaults and atfg config unset <key> to remove a saved value. Settings normally live in ~/.atfgraph/config.toml. CLI and Console share the default same-computer sign-in session; an isolated home or VM session is separate. See CLI reference for all commands and flags.

Python SDK behavior and platform settings

Configure capabilities, model calls, harnesses, retry budgets, timeouts, sessions, memory, knowledge, emitters and approval pauses in Python using the corresponding SDK guides and Python API reference. These are not additional agentnode.yaml fields.

A hosted node does not configure the graph database, authentication, retention, Kubernetes or provider enablement by adding an atfgraph.yaml. Those are platform capabilities managed with AI-LAB.

Validate a change

atfg doctor --local
atfg build

For a new release, keep name, the Python Agent.node_id, version, Agent.version, entrypoint and smoke capability/input aligned. After deployment, check atfg status <node> and its smoke result. If an unchanged uploaded release failed due to platform availability, retry the existing release instead of changing its version.