Where ATFGraph fits
ATFGraph is a platform for building and operating multi-agent systems: a shared durable runtime and control plane, with a Python authoring SDK. Nodes register capabilities with a graph server, workers execute their code, and routed calls leave a recorded path. Teams can inspect steps, attempts, results and reported usage through the Console, CLI or HTTP API.
Application code makes model calls and implements business behavior. The server supplies routing, scheduling, durable records, shared state and policy enforcement. The division lets teams reuse infrastructure while retaining control over prompts, providers, integrations and deployment choices.
What production means for an agent
A useful prototype also needs operational controls before other applications depend on it. ATFGraph provides the following foundations; teams still configure them and operate their nodes.
Callable. A capability is a typed, versioned function registered on a node. Authorized callers can start it over the HTTP API, CLI, Python SDK, generated TypeScript/Go clients, or app.traverse. These clients are programming libraries, not user interfaces. Optional discovery publications expose selected capabilities through HTTP, MCP or A2A.
Durable. The server stores runs, assigns leases and schedules retries. Worker loss can cause a step to be attempted again, so handlers must account for replay and external side effects. Approval requests pause without holding a worker; resume re-runs the handler from its start. Checkpoints help reuse work but do not make arbitrary external actions exactly once. See Approvals and checkpoints.
Bounded. Capabilities have timeouts, workers have capacity limits, and waiting parents release capacity so children can run. Model loops can be limited by rounds/calls; harness calls have deadlines and can enforce a dollar cap when the provider reports usable streamed cost. See nested calls and harness limits.
Observable. Routed steps retain inputs, outputs, timing, parentage and attempts. Agent model helpers record usage; other provider/framework calls need explicit reporting or instrumentation. Known cost comes from provider billing or a configured table labeled as an estimate. Unknown cost stays null. Export traces to MLflow or OpenTelemetry and inspect runs/costs in the Console. See Observability.
Governed. The server checks configured credentials, roles, policies, connector grants and budgets. Standard workers connect outbound and need no inbound port. Application teams and operators define the rules and manage credentials; installing the platform does not choose business policy for them. See Identity and access.
Auditable. Server-held node keys can sign recorded paths, and execution credentials can bind input/output/error hashes to node identity. Knowledge results carry doc_id#ordinal citations. Application checks can go further: the travel example compares proposed prices with saved supplier responses. These mechanisms establish record integrity and evidence links, not the factual correctness of every answer. See Knowledge.
The concepts, and why each one exists
| Concept | What it is | Why it is there |
|---|---|---|
| Agent node | A Python process, Agent(node_id=…), that registers capabilities and connects outbound to the server | The unit of deployment and identity; runs on a laptop, in a container or as a Databricks App without changing |
| Traversal | @app.traversal(): a capability that coordinates work, with or without models | Expresses orchestration and composition; the decorator labels intent rather than enforcing routing permissions |
| Skill | @app.skill(): conventionally a focused operation such as an API call, database read or calculation | Gives external operations typed inputs, limits and records; the SDK does not enforce leaf behavior |
| Decision | @app.decision(): a traversal whose job is one typed judgement with its own confidence | Makes "the model was not sure and the code used a default" visible in the path and the totals |
| Router | AgentRouter(prefix, tags): groups capabilities that one node includes | Lets a team ship desks or domains as modules on one node |
| Traverser | One run of a capability: attempts, lease, deadline, parent | The server-side object that durability, retries and cancellation act on |
| Path and steps | The record of routed capability calls and their attempts; instrumentation can add model/tool detail | Shows how the run executed, with optional signed proofs |
| Session and memory scopes | Server-held state in four scopes: session, actor, workflow, global, with revisions and TTLs | Explicit state instead of a framework's hidden object; the server derives namespace and actor from authentication |
| Emitter | A schedule, webhook or memory-change trigger declared on a capability | Agents that start themselves, with idempotency keys, duplicate suppression and dead letters |
| Harness | app.harness(...): a bounded local or remote coding-agent invocation within a handler | Delegates work to a coding agent and normalizes its result; its internal actions are not automatically graph steps |
| Agent Registry and Discovery (ARD) | The server's catalogue of published capabilities, optionally exposed as MCP and A2A endpoints and a well-known manifest | Other agents find and call yours without hard-coded addresses; everything stays behind the one endpoint |
| Identity, credentials, policies | Node signing keys and DIDs; verifiable credentials; access policies, connector grants, budgets, API tokens with roles | Who may call what, and proof of who did |
Write orchestration in Python: use asyncio.gather for fan-out, await for dependencies and if for branches. The recorded path follows routed execution rather than a separately declared workflow diagram. Code running inside one handler remains internal unless its SDK calls or instrumentation expose it. See a DAG across nodes.
Decisions with confidence you can query
Decisions describes a historical travel example where a low-confidence answer replaced four research lookups with a generic question. All steps still succeeded, although the work changed. This motivates recording judgment quality separately from execution status.
Declare a capability as a decision, define what its confidence field means, and use app.ai(..., confidence_field="confident") to report it with usage. Missing confidence stays distinct from false. Fallback records and capability totals make patterns queryable. Before using confidence to gate actions, calibrate it against labeled outcomes; request human review where consequences justify it.
Keep evidence attached to results
Use path records to locate the step that produced an answer, citations to identify retrieved passages, and stored payload references to retain source data within a run. The travel example adds application-specific validation: it saves supplier responses and verifies selected offers and quoted fields before composing a proposal. Signed paths and credentials add integrity checks. Your team must still decide which sources and validations the business requires.
Apply the same distinction to cost: a provider-reported price, a configured table estimate and an unknown charge are different records. Inspect price sources and completeness before treating an aggregate as an invoice total.
Where it runs
Run the Rust graph server with its database and deploy Python workers wherever they can reach it. Guides cover Databricks Apps, Compose, Kubernetes, long-running workers and serverless hosting. On Databricks, nodes can use serving endpoints, secret scopes and MLflow. Release assets include binaries, the Python wheel and clients; the installer configures the selected components.
How it compares
Authoring frameworks: LangGraph, CrewAI, PydanticAI, OpenAI Agents SDK, LlamaIndex, Google ADK
Authoring frameworks provide tools for prompts, structured output, handoffs and orchestration. Some also offer persistence, deployment and tracing products. Compare the specific framework and hosting service you intend to use rather than assuming all framework deployments run only in memory.
ATFGraph focuses on shared execution across registered nodes: routing, leases, scoped state, recorded paths and server-side policy. A traversal can retain existing framework code inside its handler. Use app.traverse for child work you want represented as graph steps, and Agent model helpers or explicit usage recording for accounting. Framework-internal actions do not automatically become ATFGraph steps.
Platform agent services: Amazon Bedrock agents, Databricks Agent Bricks, and their peers
Managed cloud agent services combine hosted execution with their platform's data, models, identity and observability. Examples include Amazon Bedrock/AgentCore, Databricks Agent Bricks, Azure agent services and Google Vertex AI Agent Engine. Their features and boundaries change; verify the current offering against your requirements.
ATFGraph gives you a self-hosted, Apache-2.0 runtime with its own node and path model. This adds operational responsibility but lets you run the same design across supported targets. On Databricks it deploys as Apps and can use workspace endpoints, secrets and MLflow. A skill can also call a managed agent endpoint, so using ATFGraph need not replace existing platform services.
Workflow runtimes: Temporal, Restate, Inngest, Prefect, Dagster
General workflow runtimes provide durability, retries and execution history, with different replay and side-effect models. ATFGraph combines its lease/attempt/checkpoint model with agent capabilities, usage records, discovery and scoped state. Do not assume identical execution guarantees across products. If you already operate a workflow runtime, one of its tasks can submit an ATFGraph traverser and retain the graph path as the agent-level record.
Coding harnesses used directly: Claude Code, Codex, Gemini CLI, OpenCode
The harness adapter lets a traversal delegate a bounded task to an existing coding agent and normalize its answer. It supports local CLIs and remote harness workspaces. It does not replace a team's framework or convert all its internal actions into graph steps. A working directory selects where code runs; it is not a sandbox. Tool restrictions and cost reporting vary by provider.
A documented pattern runs a planning pass, pauses for approval, then applies the approved proposal. Separately, bundled coding-assistant skills teach Claude Code or Codex how to build ATFGraph nodes from a brief. Those instruction files help developers author code; they are not runtime @app.skill() capabilities. See build from a brief.
Visual automation builders: n8n, Zapier, Make
Visual builders can remain the entry point for event-driven business flows and connectors. They can call an ATFGraph capability through HTTP when work needs code-based agent orchestration and a shared execution record.
Other agent backends
When comparing agent backends, test the requirements that matter to your system: how workers connect, what survives failure, what constitutes a recorded step, where state lives, how policy is enforced, and how identity, cost and evidence are reported. ATFGraph's standard model uses one server endpoint, outbound Python workers and generated caller libraries. Verify integrations against your chosen deployment.
Building it yourself
Building shared services yourself also means maintaining scheduling, leases, retries, checkpoints, state, discovery, access control, accounting, tracing and operational tools. ATFGraph supplies implementations for these foundations. Teams still own their business code, connector behavior, trigger filters, policy decisions, provider setup and service operation.
When ATFGraph is the right choice
- Other applications or teams need authorized access to your agents.
- Work can outlast a request, need retries or pause for a reviewer.
- Agents call other agents and you need a shared execution record.
- You need usage accounting, trace integration, identity and evidence links.
- You want supported self-hosted deployments, including Databricks Apps.
- Coding harnesses form part of a wider, bounded workflow.
When it is not
- For a small supervised prototype, a local framework may cover the whole task.
- For document retrieval alone, a retrieval library or managed knowledge service may be enough.
- If you want fully managed operations, compare hosted services first.
- TypeScript and Go callers are supported, but the documented node-authoring SDK is Python.
Questions people ask
Where do model calls happen? In node code, using the provider or endpoint your team configures. The server schedules work and stores reported execution/usage records.
Can I keep existing framework code? Yes. Run it inside a traversal, and connect its child calls, accounting and tracing explicitly where you need visibility.
How do coding agents fit? Bundled instruction skills help developers build nodes. At runtime, app.harness delegates a task to a local or remote coding harness. Read the harness guide for each provider's tool controls, deadlines and cost limits.
What does the Databricks integration provide? Deployment adapters for Apps, serving-endpoint configuration, secret-based credentials and MLflow integration. Your team selects endpoints, prices, permissions and operational settings.
Do callers need Rust? Prebuilt releases include the server and CLI, so Rust is needed only for source builds. A normal client install requires Python 3.10+ and the installer prerequisites described in Install.
What is the license? Apache 2.0.