Merge pull request #51 from jlowin/docs

New concepts docs

Author: jlowin

docs/concepts.mdx

@@ -2,20 +2,39 @@
 title: Core Concepts
 ---
 
-**ControlFlow is built on three core concepts** that are essential to understanding how the framework works. These concepts are designed to make it easy to build and manage complex AI workflows, while also providing a clear structure for developers to follow.
 
-## 🚦 Task
-**Tasks are the building blocks of ControlFlow workflows**. Each task represents a discrete objective for agents to solve, such as generating text, classifying data, or extracting information from a document. In addition, tasks can specify instructions, tools for agents to use, a schema for the expected output, and more. 
+ControlFlow is a Python framework for building AI-powered applications using large language models (LLMs). It provides a structured and intuitive way to create sophisticated workflows that leverage the power of AI while adhering to traditional software engineering best practices.
 
-Tasks can depend on each other in various ways, creating complex workflows that are easy to understand and manage:
-- **sequential** dependencies: one task must be completed before another can start
-- **context** dependencies: the result of one task is used as input for another
-- **subtask** dependencies: a task has subtasks that must be completed before the task can be considered done
+At the core of ControlFlow are three key concepts: Tasks, Flows, and Agents.
 
-By specifying the parameters of each task and how they relate to each other, developers can create complex workflows that are easy to understand and manage.
+## Tasks
 
-## 🌊 Flow
-**A flow represents an entire agentic workflow.** It is a "container" for the workflow that maintains consistent context and state across all tasks and agents. Each flow executes on a different thread, meaning all agents in the flow see the same state and can communicate with each other. 
+Tasks are the building blocks of ControlFlow workflows. Each task represents a discrete objective or goal that an AI agent needs to solve, such as generating text, classifying data, or extracting information from a document. Tasks are defined using a declarative approach, specifying the objective, instructions, expected result type, and any required context or tools.
 
-## 🤖 Agent
-**Agents are the AI "workers" that complete tasks.** Each agent can have distinct instructions, personality, and capabilities, and they are responsible for completing any tasks assigned to them. Agents can be specialized for specific tasks or more general-purpose, depending on the requirements of the workflow.
+ControlFlow provides two ways to create tasks:
+
+1. Using the `Task` class, which allows you to explicitly define all properties of a task.
+2. Using the `@task` decorator on a Python function, which automatically infers task properties from the function definition.
+
+Tasks can depend on each other in various ways, such as sequential dependencies (one task must be completed before another can start), context dependencies (the result of one task is used as input for another), or subtask dependencies (a task has subtasks that must be completed before the parent task can be considered done).
+
+
+## Agents
+
+Agents are the AI "workers" responsible for executing tasks within a flow. Each agent can have distinct instructions, personality, and capabilities, tailored to specific roles or domains. Agents are assigned to tasks based on their suitability and availability.
+
+ControlFlow allows you to create specialized agents equipped with relevant tools and instructions to tackle specific tasks efficiently. Agents can interact with each other and with human users (if given user access) to gather information, make decisions, and complete tasks collaboratively.
+
+## Flows
+
+Flows are high-level containers that encapsulate and orchestrate entire AI-powered workflows. They provide a structured way to manage tasks, agents, tools, and shared context. A flow maintains a consistent state across all its components, allowing agents to communicate and collaborate effectively.
+
+## Putting It All Together
+
+When designing workflows in ControlFlow, you break down your application logic into discrete tasks, define the dependencies and relationships between them, and assign suitable agents to execute them. Flows provide a high-level orchestration mechanism to manage the execution of tasks, handle data flow, and maintain a shared context.
+
+ControlFlow seamlessly integrates with existing Python codebases, treating AI tasks as first-class citizens. You can mix imperative and declarative programming styles, leverage Python's control flow and error handling capabilities, and gradually adopt AI capabilities into your applications.
+
+Under the hood, ControlFlow utilizes Prefect, a popular workflow orchestration tool, to provide observability, monitoring, and management features. This allows you to track the progress of your workflows, identify bottlenecks, and optimize performance.
+
+By adhering to software engineering best practices, such as modularity, error handling, and documentation, ControlFlow enables you to build robust, maintainable, and trustworthy AI-powered applications.

docs/concepts/agents.mdx

@@ -0,0 +1,90 @@
+
+Agents are a key concept in ControlFlow, representing the AI entities responsible for executing tasks within a workflow. Each agent has its own set of properties, methods, and capabilities that define its behavior and role in the flow.
+
+## Creating an Agent
+
+To create an agent, you can use the `Agent` class provided by ControlFlow. Here's an example of how to create an agent:
+
+```python
+from controlflow import Agent
+
+agent = Agent(
+    name="DataAnalyst",
+    description="An AI agent specialized in data analysis",
+    instructions="Perform data analysis tasks efficiently and accurately",
+    tools=[pandas_tool, matplotlib_tool]
+)
+```
+
+In this example, we create an agent named "DataAnalyst" with a description and specific instructions. The `tools` parameter is used to provide the agent with a list of tools it can use during task execution. These tools are essentially Python functions that the agent can call at any time.
+
+## Agent Properties
+
+An agent has the following key properties:
+
+- `name` (str): The name of the agent, which serves as an identifier and is visible to other agents in the workflow.
+- `description` (str, optional): A brief description of the agent's role or specialization, which is also visible to other agents.
+- `instructions` (str, optional): Specific instructions or guidelines for the agent to follow during task execution. These instructions are private to the agent and not visible to other agents.
+- `tools` (List[ToolType], optional): A list of tools available to the agent. Tools are Python functions that the agent can call to perform specific actions or computations.
+- `user_access` (bool, default=False): Indicates whether the agent has access to user interactions. If set to `True`, the agent will be provided with the `talk_to_human` tool to communicate with users.
+
+These properties help define the agent's characteristics, behavior, and capabilities within the flow.
+
+## Assigning Agents to Tasks
+
+To assign an agent to a task, you can use the `agents` parameter when creating a task. Here's an example:
+
+```python
+from controlflow import Task
+
+task = Task(
+    objective="Analyze sales data",
+    agents=[data_analyst, data_visualizer]
+)
+```
+
+In this example, we create a task with the objective "Analyze sales data" and assign two agents, `data_analyst` and `data_visualizer`, to it. Agents can only work on tasks they are assigned to.
+
+## Running Agents
+
+The `Agent` class provides a `run()` method to take low-level control of an agent's execution. Here's an example of how to run an agent:
+
+```python
+from controlflow import Agent, Task
+
+agent = Agent(name="DataAnalyst")
+task = Task(objective="Analyze sales data", agents=[agent])
+
+while task.is_incomplete():
+    agent.run(task)
+```
+
+In this example, we create an agent and a task, and assign the agent to the task. We then use a while loop to run the agent repeatedly until the task is marked as complete.
+
+## User Access and Interaction
+
+Agents with the `user_access` flag set to `True` have the ability to interact with users using the `talk_to_human` tool. This tool allows agents to send messages to users and receive responses.
+
+```python
+from controlflow import Agent
+
+agent = Agent(
+    name="UserAssistant",
+    description="An AI agent that interacts with users",
+    user_access=True
+)
+```
+
+In this example, we create an agent named "UserAssistant" with the `user_access` flag set to `True`. This agent will have access to the `talk_to_human` tool to communicate with users when necessary.
+
+## Best Practices
+
+When working with agents in ControlFlow, consider the following best practices:
+
+- Create specialized agents tailored to specific tasks or equipped with relevant tools.
+- Provide clear and concise instructions to guide the agent's behavior and decision-making process.
+- Assign agents to tasks based on their capabilities and the task's requirements.
+- Use the `user_access` flag judiciously and ensure proper handling of user interactions.
+- Monitor and debug agent execution to identify and resolve any issues or inefficiencies.
+
+By designing and deploying agents effectively, you can build powerful and efficient workflows that leverage the strengths of AI in task execution and decision-making.