Flowgentic 0.4.0

Flowgentic 0.4.0 is a repair release. It removes features that 0.3 shipped broken or unsafe, or that did not serve Flowgentic's purpose: running agent decisions as workflow tasks, checking their outputs and tracing them with the tasks. It adds accept, which checks an agent's output before it becomes HPC work, and one OpenTelemetry trace across an agent's decisions, the tasks they run in and their model calls. Flowgentic stays in maintenance mode, and the LangGraph execution adapter (LangraphIntegration) stays frozen; see the project status.

Breaking changes

None has a deprecation period. Where 0.3's behaviour can be kept, the entry says how; the changelog gives the reason for each.

• Logging at import: import flowgentic no longer configures logging. 0.3 set the root logger to DEBUG and printed every record to stdout. To print Flowgentic's records, call flowgentic.configure_logging().
• Logging utilities and settings file: flowgentic.utils.Logger, its formatters and filter, add_context_to_log, and the settings file (config.yml, FLOWGENTIC_CONFIG, flowgentic.settings) are gone. Configure logging in the application, or call flowgentic.configure_logging().
• Retries: each decorated call runs once. The retry loop, flowgentic.langGraph.fault_tolerance and the decorator's retry= are gone, and an unknown keyword raises TypeError. The nearest to 0.3's default of 3 attempts of at most 30 s each is, on a graph node, add_node(..., retry_policy=RetryPolicy(max_attempts=3), timeout=30), where timeout needs LangGraph 1.2 or later. LangGraph's default retry_on retries ConnectionError and an attempt that timed out, but not the other OSErrors that 0.3 retried: name the transient ones in retry_on. On a model call, the chat model's max_retries and timeout take its place; on an AsyncFlow task, a wrapper in the application. See Retries and timeouts.
• Academy: flowgentic.academy is gone, and Flowgentic no longer depends on academy-py. Call Academy agents from AsyncFlow tasks directly, with academy-py>=1.0,<2 installed, as Academy actions as AsyncFlow tasks shows.
• Node report: flowgentic.utils.telemetry, LangraphIntegration.agent_introspector, generate_execution_artifacts and LangraphUtils.render_graph are gone. Export the run's spans to a trace backend or a JSON-lines file instead, and draw a graph with LangGraph's app.get_graph().draw_png(path).
• Memory and mutable graph: flowgentic.langGraph.memory, the integration's memory_manager and flowgentic.langGraph.mutable_graph are gone, with two attributes of ExecutionWrappersLangraph that nothing used. Bound an agent's history with LangChain's SummarizationMiddleware, ContextEditingMiddleware or trim_messages, and build a new StateGraph to change a graph between runs.

New

• accept (flowgentic.acceptance) accepts or rejects an agent's output on explicit checks, for runs with no human in the loop. It asks again with the reasons, within an attempt budget, and falls back to a deterministic value when no proposal passes. The agentic AI-HPC demo's planner uses it. See Acceptance.
• One trace: each call of an agent bound with bind_agent is an invoke_agent span, and every task and service Flowgentic submits runs in its caller's trace context, so the model calls inside a task join the agent's trace. The spans follow OpenTelemetry's GenAI semantic conventions. Flowgentic depends on opentelemetry-api only, so without the SDK its spans are no-ops; the examples extra adds the SDK and the GenAI instrumentation. The AI-HPC demos write their traces to a JSON-lines file with --trace PATH. See Telemetry.

Other changes

• Dependencies are ranges, not pins: radical-asyncflow>=0.6,<0.7, where 0.3 required ==0.6.0. langgraph 1.1.5 or later is required: with 1.0 to 1.1.4, importing the LangGraph integration failed with ImportError.
• Log records follow a level contract, and no record carries prompts, model outputs, message lists or graph states.
• CI runs three design-pattern examples with a scripted chat model in place of the provider.
• The documentation site follows the latest release, no longer main.

Tested environment

Agent framework	Workflow engine	Backends	Python
LangGraph 1.x	RADICAL AsyncFlow 0.6.0	Local	3.10, 3.11, 3.12

From uv.lock: LangGraph 1.2.16, langchain-core 1.7.0, langchain 1.4.7, radical-asyncflow 0.6.0 and opentelemetry-api 1.45.1, and academy-py 1.0.0 for the Academy example. CI runs the test suite on Python 3.10, 3.11 and 3.12, and on Python 3.10 with the lowest versions the dependency ranges allow.

Install

The wheel and sdist are attached below; Flowgentic is not on PyPI.

uv venv --python 3.10 flowgentic-env
uv pip install --python flowgentic-env/bin/python https://github.com/stride-research/flowgentic/releases/download/v0.4.0/flowgentic-0.4.0-py3-none-any.whl

Known limitations

• ADR mode is not supported. The demos' --controller adr needs an ADR source checkout (ADR_SRC), because ADR is not released.
• Not validated: using an engine that the caller creates (the integration always creates its own), and any remote or HPC backend. Cancellation reaching in-flight AsyncFlow tasks is validated on local backends only.
• The recipe for calling Academy agents from AsyncFlow tasks is tested with Academy's local exchange and AsyncFlow's local backend only; see Academy actions as AsyncFlow tasks.
• AsyncFlow 0.6.0 has no per-task retry or timeout, so applications wrap the task calls that need them. See Retries and timeouts.
• Tracing (see Telemetry):
  • A model call inside an AsyncFlow task is a sibling of the task's span, not its child.
  • AsyncFlow block spans hang from the session span, not from the caller's.
  • AsyncFlow 0.6.0 labels every task span with the default backend.
  • No cost that a provider reports is recorded.
  • Acceptance's evaluation events are log records, emitted through Python's OpenTelemetry Logs API, which still lives in the module opentelemetry._logs. An application sees them only once it configures a logger provider.
  • RHAPSODY's Dragon-vLLM endpoint reports word counts as token counts.
• Live runs of the design-pattern examples need a model provider and credentials. CI runs three of them with a scripted chat model in place of the provider (tests/integration/test_design_patterns_offline.py), which shows that they complete, not what a live model makes of them. make tests-integration-llm runs two of them live, given OPEN_ROUTER_API_KEY, and the LLM examples workflow does the same on GitHub when a maintainer starts it. The interactive chatbot runs in neither.

Links: documentation · changelog · substitution experiment · Academy substitution check · 0.3.1 release