SDK vs Platform
Decide when to build with the open-source Python SDK, when to use the Dynamiq platform, and how the two connect through tracing, YAML, the gateway, and deployment.
The SDK and the platform are two surfaces over the same execution engine. The open-source dynamiq package gives you full programmatic control in Python; the platform adds a visual Workflow builder, managed deployments (Apps), Knowledge Bases, tracing, evaluations, and team administration. Most production teams end up using both.
Decision guide
| You want to… | Use |
|---|---|
| Define workflows in Python, version them in git, run them in your own infrastructure | SDK |
| Write custom node logic, function tools, or bespoke orchestration (graph state machines, custom callbacks) | SDK |
| Embed agentic logic inside an existing Python service (FastAPI, workers, notebooks) | SDK |
| Build workflows visually and iterate with non-engineers | Platform — Workflow builder |
| Deploy a workflow as a managed HTTPS endpoint with auth, streaming, and run history | Platform — Apps |
| Managed RAG with sources, sync, chunking, and search testing | Platform — Knowledge Bases |
| One API key and routing layer over many LLM providers | Platform — AI Gateway |
| Run code anywhere but keep observability, evaluations, and governance in one place | Both — SDK code + platform tracing |
A useful rule of thumb: the SDK is a library you ship inside your application; the platform is a runtime and control plane that hosts, observes, and governs AI workloads — including ones built with the SDK.
The bridges
Nothing forces an either/or choice. Four integration points connect SDK code to the platform:
1. Tracing
Attach DynamiqTracingCallbackHandler to any run and the full execution tree — workflow, nodes, agent loops, LLM calls — is sent to the platform's trace collector (https://collector.getdynamiq.ai), where it shows up alongside traces from deployed Apps:
from dynamiq.callbacks import DynamiqTracingCallbackHandler
from dynamiq.runnables import RunnableConfig
tracing = DynamiqTracingCallbackHandler() # auth via DYNAMIQ_ACCESS_KEY env var
result = workflow.run(
input_data={"text": "Hola Mundo!"},
config=RunnableConfig(callbacks=[tracing]),
)See Tracing to Dynamiq for setup and what gets captured.
2. YAML workflows
Workflows serialize to a declarative YAML format and load back with full fidelity:
workflow.to_yaml_file("workflow.yaml")
from dynamiq import Workflow
restored = Workflow.from_yaml_file(file_path="workflow.yaml")This is the same node/connection schema the platform uses, which makes YAML the interchange format between code-first and canvas-first work. See YAML workflows.
3. AI Gateway
Connection classes accept a custom url, so you can point any OpenAI-compatible connection at the platform's AI Gateway and get centralized key management, model routing, and per-project usage tracking without changing node code. See Remote connections and gateway.
4. Deploy from the SDK
The dynamiq CLI (installed with the package) authenticates against the platform and deploys SDK projects as managed services — dynamiq service deploy packages your source (or references a prebuilt image) and starts the deployment; dynamiq service status reports its state. See Deploy from the SDK and the CLI reference.
Feature map
| Capability | SDK | Platform |
|---|---|---|
| Workflows / DAG execution | Workflow, Flow, nodes in Python | Visual canvas, versions and releases |
| Agents | Agent node, Graph Orchestrator | Agent node, orchestrator nodes, Chat |
| RAG | Embedders, splitters, vector-store nodes | Knowledge Bases with managed ingestion |
| Serving | Your own process (FastAPI, workers, …) | Apps with auth, SSE, triggers, sessions |
| Observability | Callbacks, tracing handlers | Trace explorer, run history |
| Credentials | Env vars / connection objects | Connections stored per project |
| Evaluations | Evaluators in code | Datasets and evaluation runs |
Quickstart
Run an LLM workflow in about 20 lines of Python, then build a ReAct agent that answers questions with a web-search tool.
Workflows, Flows & Nodes
The three core SDK abstractions — Workflow, Flow, and Node — how the DAG is wired with depends_on() and .inputs(), and the node execution lifecycle.