# ControlFlow
**ControlFlow is a Python framework for building agentic AI workflows.**
ControlFlow provides a structured, developer-focused framework for defining workflows and delegating work to LLMs, without sacrificing control or transparency:
- Create discrete, observable [tasks](https://controlflow.ai/concepts/tasks) for an AI to work on.
- Assign one or more specialized AI [agents](https://controlflow.ai/concepts/agents) to each task.
- Combine tasks into a [flow](https://controlflow.ai/concepts/flows) to orchestrate more complex behaviors.
## Example
The simplest ControlFlow workflow has one task, a default agent, and automatic thread management:
```python
import controlflow as cf
result = cf.run("Write a short poem about artificial intelligence")
print(result)
```
**Result:**
```
In circuits and code, a mind does bloom,
With algorithms weaving through the gloom.
A spark of thought in silicon's embrace,
Artificial intelligence finds its place.
```
## Why ControlFlow?
ControlFlow addresses the challenges of building AI-powered applications that are both powerful and predictable:
- 𧊠[**Task-Centric Architecture**](https://controlflow.ai/concepts/tasks): Break complex AI workflows into manageable, observable steps.
- đ [**Structured Results**](https://controlflow.ai/patterns/task-results): Bridge the gap between AI and traditional software with type-safe, validated outputs.
- đ¤ [**Specialized Agents**](https://controlflow.ai/concepts/agents): Deploy task-specific AI agents for efficient problem-solving.
- đī¸ [**Flexible Control**](https://controlflow.ai/patterns/instructions): Continuously tune the balance of control and autonomy in your workflows.
- đšī¸ [**Multi-Agent Orchestration**](https://controlflow.ai/concepts/flows): Coordinate multiple AI agents within a single workflow or task.
- đ [**Native Observability**](https://github.com/PrefectHQ/prefect): Monitor and debug your AI workflows with full Prefect 3.0 support.
- đ **Ecosystem Integration**: Seamlessly work with your existing code, tools, and the broader AI ecosystem.
## Installation
Install ControlFlow with `pip`:
```bash
pip install controlflow
```
Next, configure your LLM provider. ControlFlow's default provider is OpenAI, which requires the `OPENAI_API_KEY` environment variable:
```
export OPENAI_API_KEY=your-api-key
```
To use a different LLM provider, [see the LLM configuration docs](https://controlflow.ai/guides/configure-llms).
## Workflow Example
Here's a more involved example that showcases user interaction, a multi-step workflow, and structured outputs:
```python
import controlflow as cf
from pydantic import BaseModel
class ResearchProposal(BaseModel):
title: str
abstract: str
key_points: list[str]
@cf.flow
def research_proposal_flow():
# Task 1: Get the research topic from the user
user_input = cf.Task(
"Work with the user to choose a research topic",
interactive=True,
)
# Task 2: Generate a structured research proposal
proposal = cf.run(
"Generate a structured research proposal",
result_type=ResearchProposal,
depends_on=[user_input]
)
return proposal
result = research_proposal_flow()
print(result.model_dump_json(indent=2))
```
<details>
<summary><i>Click to see results</i></summary>
</br>
>**Conversation:**
> ```text
> Agent: Hello! I'm here to help you choose a research topic. Do you have
> any particular area of interest or field you would like to explore?
> If you have any specific ideas or requirements, please share them as well.
>
> User: Yes, I'm interested in LLM agentic workflows
> ```
>
> **Proposal:**
> ```json
> {
> "title": "AI Agentic Workflows: Enhancing Efficiency and Automation",
> "abstract": "This research proposal aims to explore the development and implementation of AI agentic workflows to enhance efficiency and automation in various domains. AI agents, equipped with advanced capabilities, can perform complex tasks, make decisions, and interact with other agents or humans to achieve specific goals. This research will investigate the underlying technologies, methodologies, and applications of AI agentic workflows, evaluate their effectiveness, and propose improvements to optimize their performance.",
> "key_points": [
> "Introduction: Definition and significance of AI agentic workflows, Historical context and evolution of AI in workflows",
> "Technological Foundations: AI technologies enabling agentic workflows (e.g., machine learning, natural language processing), Software and hardware requirements for implementing AI workflows",
> "Methodologies: Design principles for creating effective AI agents, Workflow orchestration and management techniques, Interaction protocols between AI agents and human operators",
> "Applications: Case studies of AI agentic workflows in various industries (e.g., healthcare, finance, manufacturing), Benefits and challenges observed in real-world implementations",
> "Evaluation and Metrics: Criteria for assessing the performance of AI agentic workflows, Metrics for measuring efficiency, accuracy, and user satisfaction",
> "Proposed Improvements: Innovations to enhance the capabilities of AI agents, Strategies for addressing limitations and overcoming challenges",
> "Conclusion: Summary of key findings, Future research directions and potential impact on industry and society"
> ]
> }
> ```
</details>
In this example, ControlFlow is automatically managing a `flow`, or a shared context for a series of tasks. You can switch between standard Python functions and agentic tasks at any time, making it easy to incrementally build out complex workflows.
## Learn More
To dive deeper into ControlFlow:
- [Read the full documentation](https://controlflow.ai)
- [Explore example projects](https://controlflow.ai/examples)
- [Join our community on Slack](https://prefect.io/slack)
Raw data
{
"_id": null,
"home_page": null,
"name": "controlflow",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "ai, chatbot, llm, ai orchestration, llm orchestration, agentic workflows, flow engineering, prefect, workflow, orchestration, python, GPT, openai, assistant, agents, AI agents, natural language processing",
"author": null,
"author_email": "Jeremiah Lowin <153965+jlowin@users.noreply.github.com>",
"download_url": "https://files.pythonhosted.org/packages/88/ce/794fadf202beabc8c401346d1701f13a4338d1e5c27aaef19266e4e456a2/controlflow-0.11.2.tar.gz",
"platform": null,
"description": "\n\n# ControlFlow\n\n**ControlFlow is a Python framework for building agentic AI workflows.**\n\nControlFlow provides a structured, developer-focused framework for defining workflows and delegating work to LLMs, without sacrificing control or transparency:\n\n- Create discrete, observable [tasks](https://controlflow.ai/concepts/tasks) for an AI to work on.\n- Assign one or more specialized AI [agents](https://controlflow.ai/concepts/agents) to each task.\n- Combine tasks into a [flow](https://controlflow.ai/concepts/flows) to orchestrate more complex behaviors.\n## Example\n\nThe simplest ControlFlow workflow has one task, a default agent, and automatic thread management:\n\n```python\nimport controlflow as cf\n\nresult = cf.run(\"Write a short poem about artificial intelligence\")\n\nprint(result)\n```\n**Result:**\n```\nIn circuits and code, a mind does bloom,\nWith algorithms weaving through the gloom.\nA spark of thought in silicon's embrace,\nArtificial intelligence finds its place.\n```\n## Why ControlFlow?\n\nControlFlow addresses the challenges of building AI-powered applications that are both powerful and predictable:\n\n- \ud83e\udde9 [**Task-Centric Architecture**](https://controlflow.ai/concepts/tasks): Break complex AI workflows into manageable, observable steps.\n- \ud83d\udd12 [**Structured Results**](https://controlflow.ai/patterns/task-results): Bridge the gap between AI and traditional software with type-safe, validated outputs.\n- \ud83e\udd16 [**Specialized Agents**](https://controlflow.ai/concepts/agents): Deploy task-specific AI agents for efficient problem-solving.\n- \ud83c\udf9b\ufe0f [**Flexible Control**](https://controlflow.ai/patterns/instructions): Continuously tune the balance of control and autonomy in your workflows.\n- \ud83d\udd79\ufe0f [**Multi-Agent Orchestration**](https://controlflow.ai/concepts/flows): Coordinate multiple AI agents within a single workflow or task.\n- \ud83d\udd0d [**Native Observability**](https://github.com/PrefectHQ/prefect): Monitor and debug your AI workflows with full Prefect 3.0 support.\n- \ud83d\udd17 **Ecosystem Integration**: Seamlessly work with your existing code, tools, and the broader AI ecosystem.\n\n\n## Installation\n\nInstall ControlFlow with `pip`:\n\n```bash\npip install controlflow\n```\n\nNext, configure your LLM provider. ControlFlow's default provider is OpenAI, which requires the `OPENAI_API_KEY` environment variable:\n\n```\nexport OPENAI_API_KEY=your-api-key\n```\n\nTo use a different LLM provider, [see the LLM configuration docs](https://controlflow.ai/guides/configure-llms).\n\n\n## Workflow Example\n\nHere's a more involved example that showcases user interaction, a multi-step workflow, and structured outputs:\n\n```python\nimport controlflow as cf\nfrom pydantic import BaseModel\n\n\nclass ResearchProposal(BaseModel):\n title: str\n abstract: str\n key_points: list[str]\n\n\n@cf.flow\ndef research_proposal_flow():\n\n # Task 1: Get the research topic from the user\n user_input = cf.Task(\n \"Work with the user to choose a research topic\",\n interactive=True,\n )\n \n # Task 2: Generate a structured research proposal\n proposal = cf.run(\n \"Generate a structured research proposal\",\n result_type=ResearchProposal,\n depends_on=[user_input]\n )\n \n return proposal\n\n\nresult = research_proposal_flow()\n\nprint(result.model_dump_json(indent=2))\n```\n<details>\n<summary><i>Click to see results</i></summary>\n</br>\n\n>**Conversation:**\n> ```text\n> Agent: Hello! I'm here to help you choose a research topic. Do you have \n> any particular area of interest or field you would like to explore? \n> If you have any specific ideas or requirements, please share them as well.\n> \n> User: Yes, I'm interested in LLM agentic workflows\n> ```\n> \n> **Proposal:**\n> ```json\n> {\n> \"title\": \"AI Agentic Workflows: Enhancing Efficiency and Automation\",\n> \"abstract\": \"This research proposal aims to explore the development and implementation of AI agentic workflows to enhance efficiency and automation in various domains. AI agents, equipped with advanced capabilities, can perform complex tasks, make decisions, and interact with other agents or humans to achieve specific goals. This research will investigate the underlying technologies, methodologies, and applications of AI agentic workflows, evaluate their effectiveness, and propose improvements to optimize their performance.\",\n> \"key_points\": [\n> \"Introduction: Definition and significance of AI agentic workflows, Historical context and evolution of AI in workflows\",\n> \"Technological Foundations: AI technologies enabling agentic workflows (e.g., machine learning, natural language processing), Software and hardware requirements for implementing AI workflows\",\n> \"Methodologies: Design principles for creating effective AI agents, Workflow orchestration and management techniques, Interaction protocols between AI agents and human operators\",\n> \"Applications: Case studies of AI agentic workflows in various industries (e.g., healthcare, finance, manufacturing), Benefits and challenges observed in real-world implementations\",\n> \"Evaluation and Metrics: Criteria for assessing the performance of AI agentic workflows, Metrics for measuring efficiency, accuracy, and user satisfaction\",\n> \"Proposed Improvements: Innovations to enhance the capabilities of AI agents, Strategies for addressing limitations and overcoming challenges\",\n> \"Conclusion: Summary of key findings, Future research directions and potential impact on industry and society\"\n> ]\n> }\n> ```\n</details>\n\nIn this example, ControlFlow is automatically managing a `flow`, or a shared context for a series of tasks. You can switch between standard Python functions and agentic tasks at any time, making it easy to incrementally build out complex workflows. \n\n## Learn More\n\nTo dive deeper into ControlFlow:\n\n- [Read the full documentation](https://controlflow.ai)\n- [Explore example projects](https://controlflow.ai/examples)\n- [Join our community on Slack](https://prefect.io/slack)\n",
"bugtrack_url": null,
"license": null,
"summary": "A framework for building agentic LLM workflows",
"version": "0.11.2",
"project_urls": {
"Code": "https://github.com/PrefectHQ/ControlFlow"
},
"split_keywords": [
"ai",
" chatbot",
" llm",
" ai orchestration",
" llm orchestration",
" agentic workflows",
" flow engineering",
" prefect",
" workflow",
" orchestration",
" python",
" gpt",
" openai",
" assistant",
" agents",
" ai agents",
" natural language processing"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5525b599300c8afd675a298a917dd4484975696a7da276cad583a1917b929f96",
"md5": "c8b0c7e60538ff7eef3d6ec9a40bc1f6",
"sha256": "543fdefc55679b9c70b0820843c259c6535d97523bf43d7f9a89ea766c20177d"
},
"downloads": -1,
"filename": "controlflow-0.11.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c8b0c7e60538ff7eef3d6ec9a40bc1f6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 91748,
"upload_time": "2024-10-31T18:28:04",
"upload_time_iso_8601": "2024-10-31T18:28:04.216345Z",
"url": "https://files.pythonhosted.org/packages/55/25/b599300c8afd675a298a917dd4484975696a7da276cad583a1917b929f96/controlflow-0.11.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "88ce794fadf202beabc8c401346d1701f13a4338d1e5c27aaef19266e4e456a2",
"md5": "6e0283dc821af818c09b83d36ddc9490",
"sha256": "526fd9f44a7f61347cd04a09a49b4e79c1fad82d3661cdae860eb83daf97b305"
},
"downloads": -1,
"filename": "controlflow-0.11.2.tar.gz",
"has_sig": false,
"md5_digest": "6e0283dc821af818c09b83d36ddc9490",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 1649019,
"upload_time": "2024-10-31T18:28:07",
"upload_time_iso_8601": "2024-10-31T18:28:07.567747Z",
"url": "https://files.pythonhosted.org/packages/88/ce/794fadf202beabc8c401346d1701f13a4338d1e5c27aaef19266e4e456a2/controlflow-0.11.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-31 18:28:07",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "PrefectHQ",
"github_project": "ControlFlow",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "controlflow"
}
JSON
