Python SDK overview

The ArcFlow Python SDK lets you declare multi-agent workflows in Python and execute them in the Rust runtime (arcflow-core). Python owns structure: agents, steps, tools, memory config, graph topology, and run options. The native extension owns execution: LLM calls, tool validation, memory I/O, tracing, recovery, and streaming.

This split keeps workflow definitions readable in application code while preserving deterministic, metadata-only trace execution in Rust.

What you can build

Capability	Python surface	Notes
Linear workflows	`Workflow().step(agent)`	Default path; stub agent when no provider
Graph workflows	`Workflow(graph=True)` with `node()`, `add_edge()`, `join_node()`	Conditional routing, joins, parallel branches
Tools	`Tool` on `Agent(tools=...)`	JSON Schema validated in Rust; Python supplies callables
Memory	`MemoryConfig`, `VectorStore`	Session, shared, Postgres persistent, Qdrant vector
LLM providers	`OpenAI`, `Anthropic`, `Gemini`	Keys from environment only
Recovery	`enable_recovery()`	Postgres-backed; linear resume supported; graph resume partial
HITL	`HitlConfig` on `step()`	Interrupt, approve/reject via `resume_with_approval()`
Streaming	`run_stream()`	In-process only; not supported with remote `runtime=` URL
External callbacks	`ExternalBindingConfig`, `report_outcome()`	HMAC-signed POST to server
Observability	`WorkflowResult.trace_events`, `workflow.trace()`	Metadata only; no raw prompts or tool payloads
Registry	`Workflow(..., runtime=...)`, `publish()`, `resolve()`	Server-backed workflow refs
Schedules	`ScheduleManifest`	Validates `arcflow.schedule.yaml` structure
LangChain interop	`arcflow.langchain` submodule	Optional; not in top-level `__all__`

Architecture

text

Your Python app
 |
 v
arcflow (PyO3 extension + thin Python wrappers)
 |
 v
arcflow-core (Rust)
 |
 +-- LLM providers (OpenAI, Anthropic, Gemini)
 +-- Tool execution + jsonschema validation
 +-- Memory backends (in-process, Postgres, Qdrant)
 +-- Trace store (metadata-only trace events)
 +-- Recovery / HITL / external resume

Python has no runtime dependencies beyond the built extension. Install published wheels with pip install arcflow-sdk. Contributors building from this repository use maturin; see the ArcFlow repository.

Typical workflow

python

from arcflow import Agent, OpenAI, Workflow

researcher = Agent(
 name="researcher",
 role="research",
 instructions="Research the topic and list key facts.")
writer = Agent(
 name="writer",
 role="write",
 instructions="Write a concise summary from the research.")

wf = Workflow("research_pipeline")
wf.step(researcher)
wf.step(writer)

result = wf.run(
 "Analyze renewable energy trends",
 provider=OpenAI(model="gpt-4o"))
print(result.output)
print(result.run_id)

trace = wf.trace()
print(trace.summary())

Without provider=, run() uses the stub agent. That path needs no API keys and is useful for structure tests and CI.

Public API boundary

Top-level imports come from arcflow/__init__.py via __all__. Additional helpers live in submodules:

Module	Purpose
`arcflow.langchain`	LangChain tool and LangGraph conversion (optional extra)
`arcflow.memory`	`VectorStore`, `ChunkHit` (not re-exported at package root)

Names like FromLangChain, LangChainToArcflow, and CommonTools do not exist in this codebase. The LangChain adapter exports from_langchain_tool, to_arcflow_step, langgraph_to_arcflow, and langgraph_to_rcs_json from arcflow.langchain.

Parity and gaps

Python is the reference SDK surface. TypeScript matches core workflow, graph, recovery, HITL, streaming, and vector ingest, but its Agent class does not yet expose tools, memory, or context policy in the TypeScript binding layer. See parity matrix for a full cross-surface comparison.

Known runtime gaps that affect both SDKs:

Gap	Impact on Python SDK
Graph recovery resume	`resume()` works for linear runs; mid-graph resume incomplete
Server SSE	Use `run_stream()` in-process or poll server GET run
Remote runtime + streaming	`run_stream()` raises `WorkflowConfigurationError` when `runtime=` is set