---
title: ControlFlow
sidebarTitle: Why ControlFlow?
---

## What is ControlFlow?

**ControlFlow is a Python framework for building agentic LLM workflows.**

<Note>
An **agentic workflow** is a process that delegates at least some of its work to an LLM agent. An agent is an autonomous entity that is invoked repeatedly to make decisions and perform complex tasks. To learn more, see the [AI glossary](/glossary/agentic-workflow).
</Note>

LLMs are powerful AI models that can understand and generate human-like text, enabling them to perform a wide range of tasks. However, building applications with LLMs can be challenging due to their complexity, unpredictability, and potential for hallucinating or generating irrelevant outputs.

ControlFlow provides a structured and intuitive way to create sophisticated agentic workflows while adhereing to traditional software engineering best practices. The resulting applications are observable, controllable, and easy to trust.

<CodeGroup>
```python Example: Restaurant recommendations
from controlflow import flow, Task
from pydantic import BaseModel

class Preferences(BaseModel):
    location: str
    cuisine: str

class Restaurant(BaseModel):
    name: str
    description: str

@flow
def restaurant_recommendations(n:int) -> list[Restaurant]:
    """
    An agentic workflow that asks the user for preferences, 
    then recommends restaurants based on their input.
    """
    
    # get preferences from the user
    preferences = Task(
        "Get the user's preferences", 
        result_type=Preferences, 
        user_access=True,
    )
    
    # generate the recommendations
    recommendations = Task(
        f"Recommend {n} restaurants to the user", 
        context=dict(preferences=preferences),
        result_type=list[Restaurant], 
    )

    return recommendations

recs = restaurant_recs(n=3)
print(recs)
```
```python Result
# >> Agent: Hi there! To help find the best restaurant 
# for you, could you please tell me your location and 
# the type of cuisine you're interested in?

# >> User: I'm in DC looking for a cafe

[
    Restaurant(
        name="Compass Coffee",
        description="A popular coffee shop known for its quality coffee and relaxed atmosphere.",
    ),
    Restaurant(
        name="The Wydown Coffee Bar",
        description="A stylish cafe offering specialty coffee, pastries, and a cozy environment.",
    ),
    Restaurant(
        name="Tryst Coffeehouse",
        description="A vibrant coffeehouse with great coffee, food options, and a welcoming ambiance.",
    ),
]
```
</CodeGroup>
## Design principles

ControlFlow's design is informed by a strong opinion: LLMs are powerful tools, but they are most effective when applied to small, well-defined tasks within a structured workflow. This approach mitigates many of the challenges associated with LLMs, such as hallucinations, biases, and unpredictable behavior, while also making it easier to debug, monitor, and control the application.

This belief leads to three core design principles that underpin ControlFlow's architecture:

### 🛠️ Simple over complex

ControlFlow believes in deploying specialized, single-purpose LLMs to a series of small problems, rather than using monolithic models that try to do everything. Single-serving LLMs are more effective and efficient, ensuring that each task is handled by the right tool, leading to higher-quality results and easier management.

### 🎯 Outcome over process

ControlFlow takes a declarative approach to defining AI workflows. By focusing on outcomes instead of attempting to steer every action and decision of the LLM, developers can create more predictable and controllable workflows, making it easier to achieve the desired results.


### 🎛️ Explicit over implicit

ControlFlow treats LLMs like discrete components of a software workflow rather than an end-to-end magic process. By explicitly defining tasks and checkpoints within workflows, developers can achieve reliable, predictable, and testable results. By focusing on code first and chat second, ControlFlow ensures that the artifacts of your workflows are structured data, not conversational text

## Why ControlFlow?

The three design principles of ControlFlow lead to a number of key features that make it a powerful tool for building AI-powered applications:

### 🧩 Task-centric architecture

ControlFlow breaks down AI workflows into discrete, self-contained tasks, each with a specific objective and set of requirements. This declarative, modular approach lets developers focus on the high-level logic of their applications while allowing the framework to manage the details of coordinating agents and data flow between tasks.

### 🕵️ Agent orchestration

ControlFlow's runtime engine handles the orchestration of specialized AI agents, assigning tasks to the most appropriate models and managing the flow of data between them. This orchestration layer abstracts away the complexities of coordinating multiple AI components, allowing developers to focus on the high-level logic of their applications.

### 🔍 Native debugging and observability

ControlFlow prioritizes transparency and ease of debugging by providing native tools for monitoring and inspecting the execution of AI tasks. Developers can easily track the progress of their workflows, identify bottlenecks or issues, and gain insights into the behavior of individual agents, ensuring that their AI applications are functioning as intended.

### 🤝 Seamless integration

ControlFlow is designed to integrate seamlessly with existing Python codebases, treating AI tasks as first-class citizens in the application logic. The `Task` class provides a clean interface for defining the inputs, outputs, and requirements of each task, making it easy to incorporate AI capabilities into traditional software workflows. This seamless integration allows for a gradual and controlled adoption of AI, reducing the risk and complexity of introducing AI into existing systems.

Together, these features make ControlFlow a powerful and flexible framework for building AI-powered applications that are transparent, maintainable, and aligned with software engineering best practices.
