mirror of
https://github.com/crewAIInc/crewAI.git
synced 2026-01-07 15:18:29 +00:00
Merge pull request #1675 from rokbenko/rok
[DOCS] Update Agents docs to include two approaches for creating an agent
This commit is contained in:
Tony Kipkemboi
@@ -7,49 +7,154 @@ icon: robot
|
||||
## What is an agent?
|
||||
|
||||
An agent is an **autonomous unit** programmed to:
|
||||
|
||||
<ul>
|
||||
<li class='leading-3'>Perform tasks</li>
|
||||
<li class='leading-3'>Make decisions</li>
|
||||
<li class='leading-3'>Communicate with other agents</li>
|
||||
<li class="leading-3">Perform tasks</li>
|
||||
<li class="leading-3">Make decisions</li>
|
||||
<li class="leading-3">Communicate with other agents</li>
|
||||
</ul>
|
||||
|
||||
<Tip>
|
||||
Think of an agent as a member of a team, with specific skills and a particular job to do. Agents can have different roles like `Researcher`, `Writer`, or `Customer Support`, each contributing to the overall goal of the crew.
|
||||
Think of an agent as a member of a team, with specific skills and a particular
|
||||
job to do. Agents can have different roles like `Researcher`, `Writer`, or
|
||||
`Customer Support`, each contributing to the overall goal of the crew.
|
||||
</Tip>
|
||||
|
||||
## Agent attributes
|
||||
|
||||
| Attribute | Parameter | Description |
|
||||
| :------------------------- | :--------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| **Role** | `role` | Defines the agent's function within the crew. It determines the kind of tasks the agent is best suited for. |
|
||||
| **Goal** | `goal` | The individual objective that the agent aims to achieve. It guides the agent's decision-making process. |
|
||||
| **Backstory** | `backstory`| Provides context to the agent's role and goal, enriching the interaction and collaboration dynamics. |
|
||||
| **LLM** *(optional)* | `llm` | Represents the language model that will run the agent. It dynamically fetches the model name from the `OPENAI_MODEL_NAME` environment variable, defaulting to "gpt-4" if not specified. |
|
||||
| **Tools** *(optional)* | `tools` | Set of capabilities or functions that the agent can use to perform tasks. Expected to be instances of custom classes compatible with the agent's execution environment. Tools are initialized with a default value of an empty list. |
|
||||
| **Function Calling LLM** *(optional)* | `function_calling_llm` | Specifies the language model that will handle the tool calling for this agent, overriding the crew function calling LLM if passed. Default is `None`. |
|
||||
| **Max Iter** *(optional)* | `max_iter` | Max Iter is the maximum number of iterations the agent can perform before being forced to give its best answer. Default is `25`. |
|
||||
| **Max RPM** *(optional)* | `max_rpm` | Max RPM is the maximum number of requests per minute the agent can perform to avoid rate limits. It's optional and can be left unspecified, with a default value of `None`. |
|
||||
| **Max Execution Time** *(optional)* | `max_execution_time` | Max Execution Time is the maximum execution time for an agent to execute a task. It's optional and can be left unspecified, with a default value of `None`, meaning no max execution time. |
|
||||
| **Verbose** *(optional)* | `verbose` | Setting this to `True` configures the internal logger to provide detailed execution logs, aiding in debugging and monitoring. Default is `False`. |
|
||||
| **Allow Delegation** *(optional)* | `allow_delegation` | Agents can delegate tasks or questions to one another, ensuring that each task is handled by the most suitable agent. Default is `False`. |
|
||||
| **Step Callback** *(optional)* | `step_callback` | A function that is called after each step of the agent. This can be used to log the agent's actions or to perform other operations. It will overwrite the crew `step_callback`. |
|
||||
| **Cache** *(optional)* | `cache` | Indicates if the agent should use a cache for tool usage. Default is `True`. |
|
||||
| **System Template** *(optional)* | `system_template` | Specifies the system format for the agent. Default is `None`. |
|
||||
| **Prompt Template** *(optional)* | `prompt_template` | Specifies the prompt format for the agent. Default is `None`. |
|
||||
| **Response Template** *(optional)* | `response_template` | Specifies the response format for the agent. Default is `None`. |
|
||||
| **Allow Code Execution** *(optional)* | `allow_code_execution` | Enable code execution for the agent. Default is `False`. |
|
||||
| **Max Retry Limit** *(optional)* | `max_retry_limit` | Maximum number of retries for an agent to execute a task when an error occurs. Default is `2`. |
|
||||
| **Use System Prompt** *(optional)* | `use_system_prompt` | Adds the ability to not use system prompt (to support o1 models). Default is `True`. |
|
||||
| **Respect Context Window** *(optional)* | `respect_context_window` | Summary strategy to avoid overflowing the context window. Default is `True`. |
|
||||
| **Code Execution Mode** *(optional)* | `code_execution_mode` | Determines the mode for code execution: 'safe' (using Docker) or 'unsafe' (direct execution on the host machine). Default is `safe`. |
|
||||
| Attribute | Parameter | Description |
|
||||
| :-------------------------------------- | :----------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| **Role** | `role` | Defines the agent's function within the crew. It determines the kind of tasks the agent is best suited for. |
|
||||
| **Goal** | `goal` | The individual objective that the agent aims to achieve. It guides the agent's decision-making process. |
|
||||
| **Backstory** | `backstory` | Provides context to the agent's role and goal, enriching the interaction and collaboration dynamics. |
|
||||
| **LLM** _(optional)_ | `llm` | Represents the language model that will run the agent. It dynamically fetches the model name from the `OPENAI_MODEL_NAME` environment variable, defaulting to "gpt-4" if not specified. |
|
||||
| **Tools** _(optional)_ | `tools` | Set of capabilities or functions that the agent can use to perform tasks. Expected to be instances of custom classes compatible with the agent's execution environment. Tools are initialized with a default value of an empty list. |
|
||||
| **Function Calling LLM** _(optional)_ | `function_calling_llm` | Specifies the language model that will handle the tool calling for this agent, overriding the crew function calling LLM if passed. Default is `None`. |
|
||||
| **Max Iter** _(optional)_ | `max_iter` | Max Iter is the maximum number of iterations the agent can perform before being forced to give its best answer. Default is `25`. |
|
||||
| **Max RPM** _(optional)_ | `max_rpm` | Max RPM is the maximum number of requests per minute the agent can perform to avoid rate limits. It's optional and can be left unspecified, with a default value of `None`. |
|
||||
| **Max Execution Time** _(optional)_ | `max_execution_time` | Max Execution Time is the maximum execution time for an agent to execute a task. It's optional and can be left unspecified, with a default value of `None`, meaning no max execution time. |
|
||||
| **Verbose** _(optional)_ | `verbose` | Setting this to `True` configures the internal logger to provide detailed execution logs, aiding in debugging and monitoring. Default is `False`. |
|
||||
| **Allow Delegation** _(optional)_ | `allow_delegation` | Agents can delegate tasks or questions to one another, ensuring that each task is handled by the most suitable agent. Default is `False`. |
|
||||
| **Step Callback** _(optional)_ | `step_callback` | A function that is called after each step of the agent. This can be used to log the agent's actions or to perform other operations. It will overwrite the crew `step_callback`. |
|
||||
| **Cache** _(optional)_ | `cache` | Indicates if the agent should use a cache for tool usage. Default is `True`. |
|
||||
| **System Template** _(optional)_ | `system_template` | Specifies the system format for the agent. Default is `None`. |
|
||||
| **Prompt Template** _(optional)_ | `prompt_template` | Specifies the prompt format for the agent. Default is `None`. |
|
||||
| **Response Template** _(optional)_ | `response_template` | Specifies the response format for the agent. Default is `None`. |
|
||||
| **Allow Code Execution** _(optional)_ | `allow_code_execution` | Enable code execution for the agent. Default is `False`. |
|
||||
| **Max Retry Limit** _(optional)_ | `max_retry_limit` | Maximum number of retries for an agent to execute a task when an error occurs. Default is `2`. |
|
||||
| **Use System Prompt** _(optional)_ | `use_system_prompt` | Adds the ability to not use system prompt (to support o1 models). Default is `True`. |
|
||||
| **Respect Context Window** _(optional)_ | `respect_context_window` | Summary strategy to avoid overflowing the context window. Default is `True`. |
|
||||
| **Code Execution Mode** _(optional)_ | `code_execution_mode` | Determines the mode for code execution: 'safe' (using Docker) or 'unsafe' (direct execution on the host machine). Default is `safe`. |
|
||||
|
||||
## Creating an agent
|
||||
|
||||
<Note>
|
||||
**Agent interaction**: Agents can interact with each other using CrewAI's built-in delegation and communication mechanisms. This allows for dynamic task management and problem-solving within the crew.
|
||||
**Agent interaction**: Agents can interact with each other using CrewAI's
|
||||
built-in delegation and communication mechanisms. This allows for dynamic task
|
||||
management and problem-solving within the crew.
|
||||
</Note>
|
||||
|
||||
To create an agent, you would typically initialize an instance of the `Agent` class with the desired properties. Here's a conceptual example including all attributes:
|
||||
Agents can be created using one of the following methods:
|
||||
|
||||
<ul>
|
||||
<li class="leading-3">
|
||||
**With a YAML configuration (recommended):** Define agent properties in a
|
||||
structured YAML file, promoting reusability and cleaner code.
|
||||
</li>
|
||||
<li class="leading-3">
|
||||
**Without a YAML configuration:** Define agent properties directly in your
|
||||
code.
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
### Creating an agent with a YAML configuration (recommended)
|
||||
|
||||
The YAML configuration approach allows you to separate the agent's required properties (i.e., `role`, `goal`, and `backstory`) from the code logic. This makes your setup modular, easier to manage, and reusable across multiple projects.
|
||||
|
||||
#### Step 1: Define an agent in a YAML file
|
||||
|
||||
The YAML file contains required properties of the agent:
|
||||
|
||||
<ul>
|
||||
<li class="leading-3">
|
||||
`role`: A short description of the agent's purpose or position.
|
||||
</li>
|
||||
<li class="leading-3">
|
||||
`goal`: The primary objective the agent is designed to accomplish.
|
||||
</li>
|
||||
<li class="leading-3">
|
||||
`backstory`: A detailed description of the agent's context to enhance its
|
||||
understanding and responses.
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
<Note>
|
||||
The YAML file should only include these three properties (i.e., `role`,
|
||||
`goal`, and `backstory`). Any additional configurations must be defined in the
|
||||
`crew.py` file.
|
||||
</Note>
|
||||
|
||||
```yaml agents.yaml
|
||||
data_analyst:
|
||||
role: |
|
||||
Data Analyst
|
||||
goal: |
|
||||
Extract actionable insights
|
||||
backstory: >
|
||||
You're a data analyst at a large company. You're responsible for analyzing
|
||||
data and providing insights to the business. You're currently working on a
|
||||
project to analyze the performance of our marketing campaigns.
|
||||
```
|
||||
|
||||
#### Step 2: Initialize the agent in `crew.py`
|
||||
|
||||
After defining the agent in the YAML file, you need to create an instance of the `Agent` class in your code and link it to the YAML configuration. This is done in the `crew.py` file, where additional properties can be specified.
|
||||
|
||||
```python crew.py
|
||||
from crewai import Agent, Crew, Process, Task
|
||||
from crewai.project import CrewBase, agent, crew, task
|
||||
|
||||
@CrewBase
|
||||
class ResearchCrew():
|
||||
"""Research crew"""
|
||||
|
||||
agents_config = "your/path/to/agents.yaml"
|
||||
|
||||
@agent
|
||||
def data_analyst(self) -> Agent:
|
||||
return Agent(
|
||||
config=self.agents_config['data_analyst'],
|
||||
tools=[my_tool1, my_tool2], # Optional, defaults to an empty list
|
||||
llm=my_llm, # Optional
|
||||
function_calling_llm=my_llm, # Optional
|
||||
max_iter=15, # Optional
|
||||
max_rpm=None, # Optional
|
||||
max_execution_time=None, # Optional
|
||||
verbose=True, # Optional
|
||||
allow_delegation=False, # Optional
|
||||
step_callback=my_intermediate_step_callback, # Optional
|
||||
cache=True, # Optional
|
||||
system_template=my_system_template, # Optional
|
||||
prompt_template=my_prompt_template, # Optional
|
||||
response_template=my_response_template, # Optional
|
||||
config=my_config, # Optional
|
||||
crew=my_crew, # Optional
|
||||
tools_handler=my_tools_handler, # Optional
|
||||
cache_handler=my_cache_handler, # Optional
|
||||
callbacks=[callback1, callback2], # Optional
|
||||
allow_code_execution=True, # Optional
|
||||
max_retry_limit=2, # Optional
|
||||
use_system_prompt=True, # Optional
|
||||
respect_context_window=True, # Optional
|
||||
code_execution_mode='safe', # Optional, defaults to 'safe'
|
||||
)
|
||||
|
||||
# ... remaining code
|
||||
```
|
||||
|
||||
### Creating an agent without a YAML configuration
|
||||
|
||||
The non-YAML configuration approach allows you to define the agent's properties directly in your code. Initialize an instance of the `Agent` class with the desired properties.
|
||||
|
||||
```python Code example
|
||||
from crewai import Agent
|
||||
@@ -110,8 +215,9 @@ agent = Agent(
|
||||
|
||||
Extend your third-party agents like LlamaIndex, Langchain, Autogen or fully custom agents using the the CrewAI's `BaseAgent` class.
|
||||
|
||||
<Note>
|
||||
**BaseAgent** includes attributes and methods required to integrate with your crews to run and delegate tasks to other agents within your own crew.
|
||||
<Note>
|
||||
**BaseAgent** includes attributes and methods required to integrate with your
|
||||
crews to run and delegate tasks to other agents within your own crew.
|
||||
</Note>
|
||||
|
||||
CrewAI is a universal multi-agent framework that allows for all agents to work together to automate tasks and solve problems.
|
||||
@@ -157,5 +263,5 @@ crew = my_crew.kickoff(inputs={"input": "Mark Twain"})
|
||||
|
||||
## Conclusion
|
||||
|
||||
Agents are the building blocks of the CrewAI framework. By understanding how to define and interact with agents,
|
||||
Agents are the building blocks of the CrewAI framework. By understanding how to define and interact with agents,
|
||||
you can create sophisticated AI systems that leverage the power of collaborative intelligence. The `code_execution_mode` attribute provides flexibility in how agents execute code, allowing for both secure and direct execution options.
|
||||
|
||||
Reference in New Issue
Block a user