ControlFlow (archived — use marvin)

Common errors

• AttributeError: module 'controlflow.tools' has no attribute 'code'

  cause The specific tool modules like `code` or `web` within `controlflow.tools` need to be explicitly imported before being accessed as attributes of `controlflow.tools`.
  fix Add explicit imports for the required tools, e.g., `import controlflow.tools.web` and `import controlflow.tools.code` at the top of your file.

• Tasks Fail with 'Error 429 - Too Many Requests' when executing a Tavily Agent task from a Deployment

  cause The ControlFlow agent is encountering rate limits imposed by the external API it's interacting with (e.g., Tavily), leading to task failures.
  fix Implement robust retry logic with exponential backoff for API calls, check and potentially increase your API service's rate limits, or adjust the frequency and volume of agent tasks to stay within allowed limits.

• Confusion or issues using 'ControlFlow agent' concepts with Prefect 3.x

  cause The `controlflow` library was designed primarily for Prefect 2.x, where 'agents' were a core concept. In Prefect 3.x, agents have been replaced by 'workers,' causing a mismatch in terminology and operational expectations.
  fix Align your workflow with Prefect 3.x's 'worker' model and recognize that `controlflow`'s agent-centric features may not be directly compatible or require adaptation. For new projects, consider migrating to `marvin v3`, which incorporated `controlflow`'s engine and is actively maintained.

• General problems or lack of support when using `controlflow` for new projects

  cause The `controlflow` library is officially archived and no longer receives updates or support; its core engine has been merged into `marvin v3`. Using an archived library for new development can lead to unpatched bugs and compatibility issues.
  fix For any new development, use `marvin v3` or its current successor, as it provides the updated and actively maintained agentic workflow framework that evolved from `controlflow`.

Warnings

• breaking ControlFlow repository archived August 22, 2025. No more updates, bug fixes, or security patches. The controlflow PyPI package still installs but is dead.
  Fix: pip install marvin — marvin v3 supersedes controlflow entirely. All cf.* equivalents exist as marvin.*.
• breaking ControlFlow had a hard dependency on prefect which caused version conflicts with prefect 3.0.0. marvin removes this dependency.
  Fix: Migrate to marvin. No prefect dependency required for agent workflows.
• breaking @cf.flow decorator removed in marvin v3. Replace with marvin.Thread() context manager.
  Fix: with marvin.Thread(): marvin.run(...)
• gotcha ControlFlow used LangChain as its LLM backend. marvin v3 uses Pydantic AI — broader provider support but different configuration patterns.
  Fix: Remove LangChain dependencies. Configure providers via pydantic-ai settings.
• gotcha LLMs trained before mid-2025 will generate controlflow code (import controlflow as cf). This is dead code — redirect to marvin.
  Fix: Replace all 'import controlflow as cf' with 'import marvin'. Map cf.run → marvin.run, cf.Task → marvin.Task, cf.Agent → marvin.Agent.
• breaking Installation of marvin (or its dependencies, like temporalio, which requires Rust compilation) in alpine environments may fail due to missing system libraries (e.g., libgcc_s.so.1) or linker incompatibilities. This is common with musl libc-based alpine images which may not provide the necessary C/C++ build tools or glibc compatibility required by Rust packages.
  Fix: Use a glibc-based Python image (e.g., Debian or Ubuntu) instead of alpine, or ensure that a complete build toolchain and glibc compatibility packages (e.g., `apk add build-base gcc gcompat`) are installed in the alpine environment before attempting to install marvin.

Install

• pip install marvin Python (use this instead)
• pip install controlflow Python (archived — do not use for new projects)

Imports

• Migration to marvin
  wrong:

  import controlflow as cf
  
  result = cf.run('Write a short poem about AI')
  
  @cf.flow
  def my_flow():
      cf.run('step one')
      cf.run('step two')

  correct:

  import marvin
  
  # marvin.run replaces cf.run
  result = marvin.run('Write a short poem about AI')
  print(result)
  
  # marvin.Task replaces cf.Task
  from marvin import Task, Agent
  task = Task(instructions='Summarize this text', result_type=str)
  
  # marvin.Thread replaces cf.Flow
  with marvin.Thread():
      marvin.run('step one')
      marvin.run('step two')

  controlflow is archived. marvin v3 is the direct successor. cf.run → marvin.run, cf.Task → marvin.Task, cf.Agent → marvin.Agent, cf.Memory → marvin.Memory, @cf.flow → marvin.Thread() context manager.

Quickstart

Marvin v3 replacement for ControlFlow.

# controlflow is archived — use marvin instead
# pip install marvin
import marvin

# Direct equivalent of controlflow's cf.run
result = marvin.run('Write a short poem about artificial intelligence')
print(result)