Merge pull request #282 from PrefectHQ/docs

New flow docs; clean up

docs/concepts/agents/assigning-agents.mdx

@@ -1,25 +1,39 @@
 ---
 title: Assigning Agents to Tasks
-sidebarTitle: Task Assignment
+sidebarTitle: Assigning to Tasks
 ---
 
-To assign an agent to a task, use the `agents` parameter when creating a task. Each task requires at least one assigned agent, and will use a default agent if none are provided. Agents can be assigned to multiple tasks, and tasks can have multiple agents. 
+Agents must be assigned to tasks in order to work on them.
+
+Use the `agents` parameter when creating a task to assign agents. Each task requires at least one assigned agent, and will use a default agent if none are provided. Agents can be assigned to multiple tasks, and tasks can have multiple agents. 
+
+## Assigning agents
+
+### Tasks with no agents
+
+If you do not assign any agents to a task, it will determine its agents at runtimeaccording to the following rules:
+
+1. If the task has a parent, it will use the parent's agents.
+2. If the task's flow has a default agent, it will use that agent.
+3. It will use the global default agent (`controlflow.defaults.agent`).
+
+To see the agents assigned to a task, use its `get_agents()` method. This will return a list of all the agents assigned to the task, including any inherited from its environment.
 
 ### Tasks with one agent
 
-To assign a single agent to a task, create the task and pass the agent to the `agents` parameter:
+To assign a single agent to a task, pass a  agent to the `agents` parameter:
 
-```python
+```python Providing agents to a task
 import controlflow as cf
 
 poet = cf.Agent(name="Poet")
 
 poem = cf.run("Write a short poem about AI", agents=[poet])
 ```
 
-Alternatively, you can use the agent's own `run` method:
+Alternatively, you can use the agent's own `run` method to create and run a task in one step:
 
-```python
+```python Calling Agent.run()
 import controlflow as cf
 
 poet = cf.Agent(name="Poet")
@@ -109,3 +123,29 @@ temporary positive outcomes, despite the overall bleak and discouraging reality.
 ````
 
 </CodeGroup>
+
+
+## Completion agents
+
+By default, every agent assigned to a task will be given tools for marking the task as successful or failed. If you want to restrict completion tools to a specific agent or agents, you can do so by setting the task's `completion_agents`.
+
+<Warning>
+  Setting `completion_agents` will prevent other agents from marking the task as successful or failed. Make sure your completion agents are also assigned to the task!
+</Warning>
+
+```python Completion agents
+import controlflow as cf
+
+a1 = cf.Agent(name="A1")
+a2 = cf.Agent(name="A2")
+a3 = cf.Agent(name="A3")
+
+
+task = cf.Task(
+    ...,
+    # all three agents can work on the task
+    agents=[a1, a2, a3],
+    # only a1 and a2 can mark the task as successful
+    completion_agents=[a1, a2],
+)
+```

docs/concepts/flows/creating-flows.mdx

@@ -0,0 +1,58 @@
+---
+title: Creating Flows
+---
+
+Flows are containers for tasks that provide a shared context and history. Each flow corresponds to a specific "thread" which maintains the state of all LLM activity.
+
+Every task must always be executed as part of a flow.
+
+## Why do we need flows?
+
+You may have noticed that we haven't needed to create flows explicitly in any of the examples so far. Tasks will automatically detect if they are being run inside a flow and create a new flow if necessary.
+
+This is convenient for one-off tasks, but it's easy to see the limitations of the approach. Consider the following example:
+
+<CodeGroup>
+```python Code
+import controlflow as cf
+
+x = cf.run('Choose a number between 1 and 1000', result_type=int)
+y = cf.run('Add 5 to the number', result_type=int)
+
+print(x)
+print(y)
+print(f'The difference between x and y is {y - x}')
+```
+
+```text Result
+649
+5
+The difference between x and y is -644
+```
+</CodeGroup>
+
+Each `cf.run()` call will create a new flow, which means that the result of the first tasks will not be visible to the second task.
+
+We can fix this by running both tasks inside a flow.
+
+<CodeGroup>
+```python Code
+import controlflow as cf
+
+with cf.Flow() as flow:
+    x = cf.run('Choose a number between 1 and 1000', result_type=int)
+    y = cf.run('Add 5 to the number', result_type=int)
+
+print(x)
+print(y)
+print(f'The difference between x and y is {y - x}')
+```
+
+```text Result
+732
+737
+The difference between x and y is 5
+```
+</CodeGroup>
+
+Now the results are correct.