Agents

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 Agents

To create an agent, use the Agent class:

from controlflow import Agent

# minimal agent
agent = Agent()

# agent with options
agent = Agent(
    name="DataAnalyst",
    description="An AI agent specialized in data analysis",
    instructions="Perform data analysis tasks efficiently and accurately",
    tools=[search_web, generate_plot],
    model=gpt_35_turbo,
)

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: The name of the agent, which serves as an identifier and is visible to other agents in the workflow. Names do not have to be unique, as agents also have IDs, but it is good practice to use unique names to avoid confusion.
• description: A brief description of the agent’s role or specialization. This information is visible to other agents.
• instructions: Specific instructions or guidelines for the agent to follow during task execution. These instructions are private and not shared with other agents.
• tools: A list of tools available to the agent. Tools are Python functions that the agent can call to perform specific actions or computations.
• model: A LangChain model that powers the agent responses.
• user_access: Indicates whether the agent has access to user interactions. If set to True, the agent will be provided with the talk_to_user 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. Each task requires at least one assigned agent, and will use a default agent if none are provided.

Here’s an example of assigning multiple agents to a task:

import controlflow as cf

data_analyst = cf.Agent(name="Data Analyst")
data_visualizer = cf.Agent(name="Data Visualizer")

task = cf.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.

​

Specifying an Agent’s Model

Each agent is backed by a specific LLM that powers its responses and interactions. This allows you to choose the most suitable model for your needs, based on factors such as performance, latency, and cost.

To customize the LLM, provide a model when creating your agent:

import controlflow as cf
from langchain_openai import ChatOpenAI

gpt_35_agent = cf.Agent(model=ChatOpenAI(model="gpt-3.5-turbo"))

For a full guide on how to use LLMs in ControlFlow, including changing the default globally, please refer to the LLMs guide.

​

User Access and Interaction

Agents with the user_access flag set to True have the ability to interact with users using the talk_to_user tool. This tool allows agents to send messages to users and receive responses.

from controlflow import Agent

agent = Agent(
    name="Support Agent",
    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_user tool to communicate with users when necessary.