The Visual Agent Builder enables:
* Intuitive agent configuration with form-based interfaces
* Real-time testing and validation
* Template library with pre-configured agent types
* Easy customization of agent attributes and behaviors
The Visual Agent Builder enables:
* Intuitive agent configuration with form-based interfaces
* Real-time testing and validation
* Template library with pre-configured agent types
* Easy customization of agent attributes and behaviors
With Prompt Tracing you can:
* View the complete history of all prompts sent to your LLM
* Track token usage and costs
* Debug agent reasoning failures
* Share prompt sequences with your team
* Compare different prompt strategies
* Export traces for compliance and auditing
In the above example, we have created a simple Flow that generates a random city using OpenAI and then generates a fun fact about that city. The Flow consists of two tasks: `generate_city` and `generate_fun_fact`. The `generate_city` task is the starting point of the Flow, and the `generate_fun_fact` task listens for the output of the `generate_city` task.
Each Flow instance automatically receives a unique identifier (UUID) in its state, which helps track and manage flow executions. The state can also store additional data (like the generated city and fun fact) that persists throughout the flow's execution.
When you run the Flow, it will:
1. Generate a unique ID for the flow state
2. Generate a random city and store it in the state
3. Generate a fun fact about that city and store it in the state
4. Print the results to the console
The state's unique ID and stored data can be useful for tracking flow executions and maintaining context between tasks.
**Note:** Ensure you have set up your `.env` file to store your `OPENAI_API_KEY`. This key is necessary for authenticating requests to the OpenAI API.
### @start()
The `@start()` decorator marks entry points for a Flow. You can:
* Declare multiple unconditional starts: `@start()`
* Gate a start on a prior method or router label: `@start("method_or_label")`
* Provide a callable condition to control when a start should fire
All satisfied `@start()` methods will execute (often in parallel) when the Flow begins or resumes.
### @listen()
The `@listen()` decorator is used to mark a method as a listener for the output of another task in the Flow. The method decorated with `@listen()` will be executed when the specified task emits an output. The method can access the output of the task it is listening to as an argument.
#### Usage
The `@listen()` decorator can be used in several ways:
1. **Listening to a Method by Name**: You can pass the name of the method you want to listen to as a string. When that method completes, the listener method will be triggered.
```python Code
@listen("generate_city")
def generate_fun_fact(self, random_city):
# Implementation
```
2. **Listening to a Method Directly**: You can pass the method itself. When that method completes, the listener method will be triggered.
```python Code
@listen(generate_city)
def generate_fun_fact(self, random_city):
# Implementation
```
### Flow Output
Accessing and handling the output of a Flow is essential for integrating your AI workflows into larger applications or systems. CrewAI Flows provide straightforward mechanisms to retrieve the final output, access intermediate results, and manage the overall state of your Flow.
#### Retrieving the Final Output
When you run a Flow, the final output is determined by the last method that completes. The `kickoff()` method returns the output of this final method.
Here's how you can access the final output:
In this example, the `second_method` is the last method to complete, so its output will be the final output of the Flow.
The `kickoff()` method will return the final output, which is then printed to the console. The `plot()` method will generate the HTML file, which will help you understand the flow.
#### Accessing and Updating State
In addition to retrieving the final output, you can also access and update the state within your Flow. The state can be used to store and share data between different methods in the Flow. After the Flow has run, you can access the state to retrieve any information that was added or updated during the execution.
Here's an example of how to update and access the state:
In this example, the state is updated by both `first_method` and `second_method`.
After the Flow has run, you can access the final state to see the updates made by these methods.
By ensuring that the final method's output is returned and providing access to the state, CrewAI Flows make it easy to integrate the results of your AI workflows into larger applications or systems,
while also maintaining and accessing the state throughout the Flow's execution.
## Flow State Management
Managing state effectively is crucial for building reliable and maintainable AI workflows. CrewAI Flows provides robust mechanisms for both unstructured and structured state management,
allowing developers to choose the approach that best fits their application's needs.
### Unstructured State Management
In unstructured state management, all state is stored in the `state` attribute of the `Flow` class.
This approach offers flexibility, enabling developers to add or modify state attributes on the fly without defining a strict schema.
Even with unstructured states, CrewAI Flows automatically generates and maintains a unique identifier (UUID) for each state instance.
```python Code
from crewai.flow.flow import Flow, listen, start
class UnstructuredExampleFlow(Flow):
@start()
def first_method(self):
# The state automatically includes an 'id' field
print(f"State ID: {self.state['id']}")
self.state['counter'] = 0
self.state['message'] = "Hello from structured flow"
@listen(first_method)
def second_method(self):
self.state['counter'] += 1
self.state['message'] += " - updated"
@listen(second_method)
def third_method(self):
self.state['counter'] += 1
self.state['message'] += " - updated again"
print(f"State after third_method: {self.state}")
flow = UnstructuredExampleFlow()
flow.plot("my_flow_plot")
flow.kickoff()
```
**Note:** The `id` field is automatically generated and preserved throughout the flow's execution. You don't need to manage or set it manually, and it will be maintained even when updating the state with new data.
**Key Points:**
* **Flexibility:** You can dynamically add attributes to `self.state` without predefined constraints.
* **Simplicity:** Ideal for straightforward workflows where state structure is minimal or varies significantly.
### Structured State Management
Structured state management leverages predefined schemas to ensure consistency and type safety across the workflow.
By using models like Pydantic's `BaseModel`, developers can define the exact shape of the state, enabling better validation and auto-completion in development environments.
Each state in CrewAI Flows automatically receives a unique identifier (UUID) to help track and manage state instances. This ID is automatically generated and managed by the Flow system.
```python Code
from crewai.flow.flow import Flow, listen, start
from pydantic import BaseModel
class ExampleState(BaseModel):
# Note: 'id' field is automatically added to all states
counter: int = 0
message: str = ""
class StructuredExampleFlow(Flow[ExampleState]):
@start()
def first_method(self):
# Access the auto-generated ID if needed
print(f"State ID: {self.state.id}")
self.state.message = "Hello from structured flow"
@listen(first_method)
def second_method(self):
self.state.counter += 1
self.state.message += " - updated"
@listen(second_method)
def third_method(self):
self.state.counter += 1
self.state.message += " - updated again"
print(f"State after third_method: {self.state}")
flow = StructuredExampleFlow()
flow.kickoff()
```
**Key Points:**
* **Defined Schema:** `ExampleState` clearly outlines the state structure, enhancing code readability and maintainability.
* **Type Safety:** Leveraging Pydantic ensures that state attributes adhere to the specified types, reducing runtime errors.
* **Auto-Completion:** IDEs can provide better auto-completion and error checking based on the defined state model.
### Choosing Between Unstructured and Structured State Management
* **Use Unstructured State Management when:**
* The workflow's state is simple or highly dynamic.
* Flexibility is prioritized over strict state definitions.
* Rapid prototyping is required without the overhead of defining schemas.
* **Use Structured State Management when:**
* The workflow requires a well-defined and consistent state structure.
* Type safety and validation are important for your application's reliability.
* You want to leverage IDE features like auto-completion and type checking for better developer experience.
By providing both unstructured and structured state management options, CrewAI Flows empowers developers to build AI workflows that are both flexible and robust, catering to a wide range of application requirements.
## Flow Persistence
The @persist decorator enables automatic state persistence in CrewAI Flows, allowing you to maintain flow state across restarts or different workflow executions. This decorator can be applied at either the class level or method level, providing flexibility in how you manage state persistence.
### Class-Level Persistence
When applied at the class level, the @persist decorator automatically persists all flow method states:
```python
@persist # Using SQLiteFlowPersistence by default
class MyFlow(Flow[MyState]):
@start()
def initialize_flow(self):
# This method will automatically have its state persisted
self.state.counter = 1
print("Initialized flow. State ID:", self.state.id)
@listen(initialize_flow)
def next_step(self):
# The state (including self.state.id) is automatically reloaded
self.state.counter += 1
print("Flow state is persisted. Counter:", self.state.counter)
```
### Method-Level Persistence
For more granular control, you can apply @persist to specific methods:
```python
class AnotherFlow(Flow[dict]):
@persist # Persists only this method's state
@start()
def begin(self):
if "runs" not in self.state:
self.state["runs"] = 0
self.state["runs"] += 1
print("Method-level persisted runs:", self.state["runs"])
```
### How It Works
1. **Unique State Identification**
* Each flow state automatically receives a unique UUID
* The ID is preserved across state updates and method calls
* Supports both structured (Pydantic BaseModel) and unstructured (dictionary) states
2. **Default SQLite Backend**
* SQLiteFlowPersistence is the default storage backend
* States are automatically saved to a local SQLite database
* Robust error handling ensures clear messages if database operations fail
3. **Error Handling**
* Comprehensive error messages for database operations
* Automatic state validation during save and load
* Clear feedback when persistence operations encounter issues
### Important Considerations
* **State Types**: Both structured (Pydantic BaseModel) and unstructured (dictionary) states are supported
* **Automatic ID**: The `id` field is automatically added if not present
* **State Recovery**: Failed or restarted flows can automatically reload their previous state
* **Custom Implementation**: You can provide your own FlowPersistence implementation for specialized storage needs
### Technical Advantages
1. **Precise Control Through Low-Level Access**
* Direct access to persistence operations for advanced use cases
* Fine-grained control via method-level persistence decorators
* Built-in state inspection and debugging capabilities
* Full visibility into state changes and persistence operations
2. **Enhanced Reliability**
* Automatic state recovery after system failures or restarts
* Transaction-based state updates for data integrity
* Comprehensive error handling with clear error messages
* Robust validation during state save and load operations
3. **Extensible Architecture**
* Customizable persistence backend through FlowPersistence interface
* Support for specialized storage solutions beyond SQLite
* Compatible with both structured (Pydantic) and unstructured (dict) states
* Seamless integration with existing CrewAI flow patterns
The persistence system's architecture emphasizes technical precision and customization options, allowing developers to maintain full control over state management while benefiting from built-in reliability features.
## Flow Control
### Conditional Logic: `or`
The `or_` function in Flows allows you to listen to multiple methods and trigger the listener method when any of the specified methods emit an output.
When you run this Flow, the `logger` method will be triggered by the output of either the `start_method` or the `second_method`.
The `or_` function is used to listen to multiple methods and trigger the listener method when any of the specified methods emit an output.
### Conditional Logic: `and`
The `and_` function in Flows allows you to listen to multiple methods and trigger the listener method only when all the specified methods emit an output.
When you run this Flow, the `logger` method will be triggered only when both the `start_method` and the `second_method` emit an output.
The `and_` function is used to listen to multiple methods and trigger the listener method only when all the specified methods emit an output.
### Router
The `@router()` decorator in Flows allows you to define conditional routing logic based on the output of a method.
You can specify different routes based on the output of the method, allowing you to control the flow of execution dynamically.
In the above example, the `start_method` generates a random boolean value and sets it in the state.
The `second_method` uses the `@router()` decorator to define conditional routing logic based on the value of the boolean.
If the boolean is `True`, the method returns `"success"`, and if it is `False`, the method returns `"failed"`.
The `third_method` and `fourth_method` listen to the output of the `second_method` and execute based on the returned value.
When you run this Flow, the output will change based on the random boolean value generated by the `start_method`.
## Adding Agents to Flows
Agents can be seamlessly integrated into your flows, providing a lightweight alternative to full Crews when you need simpler, focused task execution. Here's an example of how to use an Agent within a flow to perform market research:
```python
import asyncio
from typing import Any, Dict, List
from crewai_tools import SerperDevTool
from pydantic import BaseModel, Field
from crewai.agent import Agent
from crewai.flow.flow import Flow, listen, start
# Define a structured output format
class MarketAnalysis(BaseModel):
key_trends: List[str] = Field(description="List of identified market trends")
market_size: str = Field(description="Estimated market size")
competitors: List[str] = Field(description="Major competitors in the space")
# Define flow state
class MarketResearchState(BaseModel):
product: str = ""
analysis: MarketAnalysis | None = None
# Create a flow class
class MarketResearchFlow(Flow[MarketResearchState]):
@start()
def initialize_research(self) -> Dict[str, Any]:
print(f"Starting market research for {self.state.product}")
return {"product": self.state.product}
@listen(initialize_research)
async def analyze_market(self) -> Dict[str, Any]:
# Create an Agent for market research
analyst = Agent(
role="Market Research Analyst",
goal=f"Analyze the market for {self.state.product}",
backstory="You are an experienced market analyst with expertise in "
"identifying market trends and opportunities.",
tools=[SerperDevTool()],
verbose=True,
)
# Define the research query
query = f"""
Research the market for {self.state.product}. Include:
1. Key market trends
2. Market size
3. Major competitors
Format your response according to the specified structure.
"""
# Execute the analysis with structured output format
result = await analyst.kickoff_async(query, response_format=MarketAnalysis)
if result.pydantic:
print("result", result.pydantic)
else:
print("result", result)
# Return the analysis to update the state
return {"analysis": result.pydantic}
@listen(analyze_market)
def present_results(self, analysis) -> None:
print("\nMarket Analysis Results")
print("=====================")
if isinstance(analysis, dict):
# If we got a dict with 'analysis' key, extract the actual analysis object
market_analysis = analysis.get("analysis")
else:
market_analysis = analysis
if market_analysis and isinstance(market_analysis, MarketAnalysis):
print("\nKey Market Trends:")
for trend in market_analysis.key_trends:
print(f"- {trend}")
print(f"\nMarket Size: {market_analysis.market_size}")
print("\nMajor Competitors:")
for competitor in market_analysis.competitors:
print(f"- {competitor}")
else:
print("No structured analysis data available.")
print("Raw analysis:", analysis)
# Usage example
async def run_flow():
flow = MarketResearchFlow()
flow.plot("MarketResearchFlowPlot")
result = await flow.kickoff_async(inputs={"product": "AI-powered chatbots"})
return result
# Run the flow
if __name__ == "__main__":
asyncio.run(run_flow())
```
This example demonstrates several key features of using Agents in flows:
1. **Structured Output**: Using Pydantic models to define the expected output format (`MarketAnalysis`) ensures type safety and structured data throughout the flow.
2. **State Management**: The flow state (`MarketResearchState`) maintains context between steps and stores both inputs and outputs.
3. **Tool Integration**: Agents can use tools (like `WebsiteSearchTool`) to enhance their capabilities.
## Adding Crews to Flows
Creating a flow with multiple crews in CrewAI is straightforward.
You can generate a new CrewAI project that includes all the scaffolding needed to create a flow with multiple crews by running the following command:
```bash
crewai create flow name_of_flow
```
This command will generate a new CrewAI project with the necessary folder structure. The generated project includes a prebuilt crew called `poem_crew` that is already working. You can use this crew as a template by copying, pasting, and editing it to create other crews.
### Folder Structure
After running the `crewai create flow name_of_flow` command, you will see a folder structure similar to the following:
| Directory/File | Description |
| :--------------------- | :------------------------------------------------------------------ |
| `name_of_flow/` | Root directory for the flow. |
| ├── `crews/` | Contains directories for specific crews. |
| │ └── `poem_crew/` | Directory for the "poem\_crew" with its configurations and scripts. |
| │ ├── `config/` | Configuration files directory for the "poem\_crew". |
| │ │ ├── `agents.yaml` | YAML file defining the agents for "poem\_crew". |
| │ │ └── `tasks.yaml` | YAML file defining the tasks for "poem\_crew". |
| │ ├── `poem_crew.py` | Script for "poem\_crew" functionality. |
| ├── `tools/` | Directory for additional tools used in the flow. |
| │ └── `custom_tool.py` | Custom tool implementation. |
| ├── `main.py` | Main script for running the flow. |
| ├── `README.md` | Project description and instructions. |
| ├── `pyproject.toml` | Configuration file for project dependencies and settings. |
| └── `.gitignore` | Specifies files and directories to ignore in version control. |
### Building Your Crews
In the `crews` folder, you can define multiple crews. Each crew will have its own folder containing configuration files and the crew definition file. For example, the `poem_crew` folder contains:
* `config/agents.yaml`: Defines the agents for the crew.
* `config/tasks.yaml`: Defines the tasks for the crew.
* `poem_crew.py`: Contains the crew definition, including agents, tasks, and the crew itself.
You can copy, paste, and edit the `poem_crew` to create other crews.
### Connecting Crews in `main.py`
The `main.py` file is where you create your flow and connect the crews together. You can define your flow by using the `Flow` class and the decorators `@start` and `@listen` to specify the flow of execution.
Here's an example of how you can connect the `poem_crew` in the `main.py` file:
```python Code
#!/usr/bin/env python
from random import randint
from pydantic import BaseModel
from crewai.flow.flow import Flow, listen, start
from .crews.poem_crew.poem_crew import PoemCrew
class PoemState(BaseModel):
sentence_count: int = 1
poem: str = ""
class PoemFlow(Flow[PoemState]):
@start()
def generate_sentence_count(self):
print("Generating sentence count")
self.state.sentence_count = randint(1, 5)
@listen(generate_sentence_count)
def generate_poem(self):
print("Generating poem")
result = PoemCrew().crew().kickoff(inputs={"sentence_count": self.state.sentence_count})
print("Poem generated", result.raw)
self.state.poem = result.raw
@listen(generate_poem)
def save_poem(self):
print("Saving poem")
with open("poem.txt", "w") as f:
f.write(self.state.poem)
def kickoff():
poem_flow = PoemFlow()
poem_flow.kickoff()
def plot():
poem_flow = PoemFlow()
poem_flow.plot("PoemFlowPlot")
if __name__ == "__main__":
kickoff()
plot()
```
In this example, the `PoemFlow` class defines a flow that generates a sentence count, uses the `PoemCrew` to generate a poem, and then saves the poem to a file. The flow is kicked off by calling the `kickoff()` method. The PoemFlowPlot will be generated by `plot()` method.
### Running the Flow
(Optional) Before running the flow, you can install the dependencies by running:
```bash
crewai install
```
Once all of the dependencies are installed, you need to activate the virtual environment by running:
```bash
source .venv/bin/activate
```
After activating the virtual environment, you can run the flow by executing one of the following commands:
```bash
crewai flow kickoff
```
or
```bash
uv run kickoff
```
The flow will execute, and you should see the output in the console.
## Plot Flows
Visualizing your AI workflows can provide valuable insights into the structure and execution paths of your flows. CrewAI offers a powerful visualization tool that allows you to generate interactive plots of your flows, making it easier to understand and optimize your AI workflows.
### What are Plots?
Plots in CrewAI are graphical representations of your AI workflows. They display the various tasks, their connections, and the flow of data between them. This visualization helps in understanding the sequence of operations, identifying bottlenecks, and ensuring that the workflow logic aligns with your expectations.
### How to Generate a Plot
CrewAI provides two convenient methods to generate plots of your flows:
#### Option 1: Using the `plot()` Method
If you are working directly with a flow instance, you can generate a plot by calling the `plot()` method on your flow object. This method will create an HTML file containing the interactive plot of your flow.
```python Code
# Assuming you have a flow instance
flow.plot("my_flow_plot")
```
This will generate a file named `my_flow_plot.html` in your current directory. You can open this file in a web browser to view the interactive plot.
#### Option 2: Using the Command Line
If you are working within a structured CrewAI project, you can generate a plot using the command line. This is particularly useful for larger projects where you want to visualize the entire flow setup.
```bash
crewai flow plot
```
This command will generate an HTML file with the plot of your flow, similar to the `plot()` method. The file will be saved in your project directory, and you can open it in a web browser to explore the flow.
### Understanding the Plot
The generated plot will display nodes representing the tasks in your flow, with directed edges indicating the flow of execution. The plot is interactive, allowing you to zoom in and out, and hover over nodes to see additional details.
By visualizing your flows, you can gain a clearer understanding of the workflow's structure, making it easier to debug, optimize, and communicate your AI processes to others.
### Conclusion
Plotting your flows is a powerful feature of CrewAI that enhances your ability to design and manage complex AI workflows. Whether you choose to use the `plot()` method or the command line, generating plots will provide you with a visual representation of your workflows, aiding in both development and presentation.
## Next Steps
If you're interested in exploring additional examples of flows, we have a variety of recommendations in our examples repository. Here are four specific flow examples, each showcasing unique use cases to help you match your current problem type to a specific example:
1. **Email Auto Responder Flow**: This example demonstrates an infinite loop where a background job continually runs to automate email responses. It's a great use case for tasks that need to be performed repeatedly without manual intervention. [View Example](https://github.com/crewAIInc/crewAI-examples/tree/main/email_auto_responder_flow)
2. **Lead Score Flow**: This flow showcases adding human-in-the-loop feedback and handling different conditional branches using the router. It's an excellent example of how to incorporate dynamic decision-making and human oversight into your workflows. [View Example](https://github.com/crewAIInc/crewAI-examples/tree/main/lead-score-flow)
3. **Write a Book Flow**: This example excels at chaining multiple crews together, where the output of one crew is used by another. Specifically, one crew outlines an entire book, and another crew generates chapters based on the outline. Eventually, everything is connected to produce a complete book. This flow is perfect for complex, multi-step processes that require coordination between different tasks. [View Example](https://github.com/crewAIInc/crewAI-examples/tree/main/write_a_book_with_flows)
4. **Meeting Assistant Flow**: This flow demonstrates how to broadcast one event to trigger multiple follow-up actions. For instance, after a meeting is completed, the flow can update a Trello board, send a Slack message, and save the results. It's a great example of handling multiple outcomes from a single event, making it ideal for comprehensive task management and notification systems. [View Example](https://github.com/crewAIInc/crewAI-examples/tree/main/meeting_assistant_flow)
By exploring these examples, you can gain insights into how to leverage CrewAI Flows for various use cases, from automating repetitive tasks to managing complex, multi-step processes with dynamic decision-making and human feedback.
Also, check out our YouTube video on how to use flows in CrewAI below!
## Running Flows
There are two ways to run a flow:
### Using the Flow API
You can run a flow programmatically by creating an instance of your flow class and calling the `kickoff()` method:
```python
flow = ExampleFlow()
result = flow.kickoff()
```
### Using the CLI
Starting from version 0.103.0, you can run flows using the `crewai run` command:
```shell
crewai run
```
This command automatically detects if your project is a flow (based on the `type = "flow"` setting in your pyproject.toml) and runs it accordingly. This is the recommended way to run flows from the command line.
For backward compatibility, you can also use:
```shell
crewai flow kickoff
```
However, the `crewai run` command is now the preferred method as it works for both crews and flows.
# Knowledge
Source: https://docs.crewai.com/en/concepts/knowledge
What is knowledge in CrewAI and how to use it.
## Overview
Knowledge in CrewAI is a powerful system that allows AI agents to access and utilize external information sources during their tasks.
Think of it as giving your agents a reference library they can consult while working.
stop parameter, you can simply omit it from your LLM call:
```python
from crewai import LLM
import os
os.environ["OPENAI_API_KEY"] = "
The Visual Task Builder enables:
* Drag-and-drop task creation
* Visual task dependencies and flow
* Real-time testing and validation
* Easy sharing and collaboration
## Supported Integrations
### **Communication & Collaboration**
* **Gmail** - Manage emails and drafts
* **Slack** - Workspace notifications and alerts
* **Microsoft** - Office 365 and Teams integration
### **Project Management**
* **Jira** - Issue tracking and project management
* **ClickUp** - Task and productivity management
* **Asana** - Team task and project coordination
* **Notion** - Page and database management
* **Linear** - Software project and bug tracking
* **GitHub** - Repository and issue management
### **Customer Relationship Management**
* **Salesforce** - CRM account and opportunity management
* **HubSpot** - Sales pipeline and contact management
* **Zendesk** - Customer support ticket management
### **Business & Finance**
* **Stripe** - Payment processing and customer management
* **Shopify** - E-commerce store and product management
### **Productivity & Storage**
* **Google Sheets** - Spreadsheet data synchronization
* **Google Calendar** - Event and schedule management
* **Box** - File storage and document management
and more to come!
## Prerequisites
Before using Authentication Integrations, ensure you have:
* A [CrewAI Enterprise](https://app.crewai.com) account. You can get started with a free trial.
## Setting Up Integrations
### 1. Connect Your Account
1. Navigate to [CrewAI Enterprise](https://app.crewai.com)
2. Go to **Integrations** tab - [https://app.crewai.com/crewai\_plus/connectors](https://app.crewai.com/crewai_plus/connectors)
3. Click **Connect** on your desired service from the Authentication Integrations section
4. Complete the OAuth authentication flow
5. Grant necessary permissions for your use case
6. All set! Get your Enterprise Token from your [CrewAI Enterprise](https://app.crewai.com) in **Integration** tab
### 2. Install Integration Tools
All you need is the latest version of `crewai-tools` package.
```bash
uv add crewai-tools
```
## Usage Examples
### Basic Usage
### Scoped Deployments for multi user organizations
You can deploy your crew and scope each integration to a specific user. For example, a crew that connects to google can use a specific user's gmail account.
### Getting Help
## Users and Roles
Each member in your CrewAI workspace is assigned a role, which determines their access across various features.
You can:
* Use predefined roles (Owner, Member)
* Create custom roles tailored to specific permissions
* Assign roles at any time through the settings panel
You can configure users and roles in Settings → Roles.
## Accessing Traces
### 2. Tasks & Agents
This section shows all tasks and agents that were part of the crew execution:
* Task name and agent assignment
* Agents and LLMs used for each task
* Status (completed/failed)
* Individual execution time of the task
### 3. Final Output
Displays the final result produced by the crew after all tasks are completed.
### 4. Execution Timeline
A visual representation of when each task started and ended, helping you identify bottlenecks or parallel execution patterns.
### 5. Detailed Task View
When you click on a specific task in the timeline or task list, you'll see:
* **Task Key**: Unique identifier for the task
* **Task ID**: Technical identifier in the system
* **Status**: Current state (completed/running/failed)
* **Agent**: Which agent performed the task
* **LLM**: Language model used for this task
* **Start/End Time**: When the task began and completed
* **Execution Time**: Duration of this specific task
* **Task Description**: What the agent was instructed to do
* **Expected Output**: What output format was requested
* **Input**: Any input provided to this task from previous tasks
* **Output**: The actual result produced by the agent
## Using Traces for Debugging
Traces are invaluable for troubleshooting issues with your crews:
This view shows all the trigger integrations available for your deployment, along with their current connection status.
### Enabling and Disabling Triggers
Each trigger can be easily enabled or disabled using the toggle switch:
* **Enabled (blue toggle)**: The trigger is active and will automatically execute your deployment when the specified events occur
* **Disabled (gray toggle)**: The trigger is inactive and will not respond to events
Simply click the toggle to change the trigger state. Changes take effect immediately.
### Monitoring Trigger Executions
Track the performance and history of your triggered executions:
## Building Automation
Before building your automation, it's helpful to understand the structure of trigger payloads that your crews and flows will receive.
### Payload Samples Repository
We maintain a comprehensive repository with sample payloads from various trigger sources to help you build and test your automations:
**🔗 [CrewAI Enterprise Trigger Payload Samples](https://github.com/crewAIInc/crewai-enterprise-trigger-payload-samples)**
This repository contains:
* **Real payload examples** from different trigger sources (Gmail, Google Drive, etc.)
* **Payload structure documentation** showing the format and available fields
### Triggers with Crew
Your existing crew definitions work seamlessly with triggers, you just need to have a task to parse the received payload:
```python
@CrewBase
class MyAutomatedCrew:
@agent
def researcher(self) -> Agent:
return Agent(
config=self.agents_config['researcher'],
)
@task
def parse_trigger_payload(self) -> Task:
return Task(
config=self.tasks_config['parse_trigger_payload'],
agent=self.researcher(),
)
@task
def analyze_trigger_content(self) -> Task:
return Task(
config=self.tasks_config['analyze_trigger_data'],
agent=self.researcher(),
)
```
The crew will automatically receive and can access the trigger payload through the standard CrewAI context mechanisms.
Once deployment is complete, you'll see:
* Your crew's unique URL
* A Bearer token to protect your crew API
* A "Delete" button if you need to remove the deployment
With Crew Studio, you can:
* Chat with the Crew Assistant to describe your problem
* Automatically generate agents and tasks
* Select appropriate tools
* Configure necessary inputs
* Generate downloadable code for customization
* Deploy directly to the CrewAI Enterprise platform
## Configuration Steps
Before you can start using Crew Studio, you need to configure your LLM connections:
* Configure any additional actions as needed
* Review your workflow steps to ensure everything is set up correctly
* Activate the workflow
### Step 2: Initiate Execution
From your crew's detail page, you have two options to kickoff an execution:
#### Option A: Quick Kickoff
1. Click the `Kickoff` link in the Test Endpoints section
2. Enter the required input parameters for your crew in the JSON editor
3. Click the `Send Request` button
#### Option B: Using the Visual Interface
1. Click the `Run` tab in the crew detail page
2. Enter the required inputs in the form fields
3. Click the `Run Crew` button
### Step 3: Monitor Execution Progress
After initiating the execution:
1. You'll receive a response containing a `kickoff_id` - **copy this ID**
2. This ID is essential for tracking your execution
### Step 4: Check Execution Status
To monitor the progress of your execution:
1. Click the "Status" endpoint in the Test Endpoints section
2. Paste the `kickoff_id` into the designated field
3. Click the "Get Status" button
The status response will show:
* Current execution state (`running`, `completed`, etc.)
* Details about which tasks are in progress
* Any outputs produced so far
### Step 5: View Final Results
Once execution is complete:
1. The status will change to `completed`
2. You can view the full execution results and outputs
3. For a more detailed view, check the `Executions` tab in the crew detail page
## Method 2: Using the API
You can also kickoff crews programmatically using the CrewAI Enterprise REST API.
### Authentication
All API requests require a bearer token for authentication:
```bash
curl -H "Authorization: Bearer YOUR_CREW_TOKEN" https://your-crew-url.crewai.com
```
Your bearer token is available on the Status tab of your crew's detail page.
### Checking Crew Health
Before executing operations, you can verify that your crew is running properly:
```bash
curl -H "Authorization: Bearer YOUR_CREW_TOKEN" https://your-crew-url.crewai.com
```
A successful response will return a message indicating the crew is operational:
```
Healthy%
```
### Step 1: Retrieve Required Inputs
First, determine what inputs your crew requires:
```bash
curl -X GET \
-H "Authorization: Bearer YOUR_CREW_TOKEN" \
https://your-crew-url.crewai.com/inputs
```
The response will be a JSON object containing an array of required input parameters, for example:
```json
{"inputs":["topic","current_year"]}
```
This example shows that this particular crew requires two inputs: `topic` and `current_year`.
### Step 2: Kickoff Execution
Initiate execution by providing the required inputs:
```bash
curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_CREW_TOKEN" \
-d '{"inputs": {"topic": "AI Agent Frameworks", "current_year": "2025"}}' \
https://your-crew-url.crewai.com/kickoff
```
The response will include a `kickoff_id` that you'll need for tracking:
```json
{"kickoff_id":"abcd1234-5678-90ef-ghij-klmnopqrstuv"}
```
### Step 3: Check Execution Status
Monitor the execution progress using the kickoff\_id:
```bash
curl -X GET \
-H "Authorization: Bearer YOUR_CREW_TOKEN" \
https://your-crew-url.crewai.com/status/abcd1234-5678-90ef-ghij-klmnopqrstuv
```
## Handling Executions
### Long-Running Executions
For executions that may take a long time:
1. Consider implementing a polling mechanism to check status periodically
2. Use webhooks (if available) for notification when execution completes
3. Implement error handling for potential timeouts
### Execution Context
The execution context includes:
* Inputs provided at kickoff
* Environment variables configured during deployment
* Any state maintained between tasks
### Debugging Failed Executions
If an execution fails:
1. Check the "Executions" tab for detailed logs
2. Review the "Traces" tab for step-by-step execution details
3. Look for LLM responses and tool usage in the trace details
## Next Steps
* Customize the component styling to match your application's design
* Add additional props for configuration
* Integrate with your application's state management
* Add error handling and loading states
# Salesforce Trigger
Source: https://docs.crewai.com/en/enterprise/guides/salesforce-trigger
Trigger CrewAI crews from Salesforce workflows for CRM automation
CrewAI Enterprise can be triggered from Salesforce to automate customer relationship management workflows and enhance your sales operations.
## Overview
Salesforce is a leading customer relationship management (CRM) platform that helps businesses streamline their sales, service, and marketing operations. By setting up CrewAI triggers from Salesforce, you can:
* Automate lead scoring and qualification
* Generate personalized sales materials
* Enhance customer service with AI-powered responses
* Streamline data analysis and reporting
## Demo
## Getting Started
To set up Salesforce triggers:
1. **Contact Support**: Reach out to CrewAI Enterprise support for assistance with Salesforce trigger setup
2. **Review Requirements**: Ensure you have the necessary Salesforce permissions and API access
3. **Configure Connection**: Work with the support team to establish the connection between CrewAI and your Salesforce instance
4. **Test Triggers**: Verify the triggers work correctly with your specific use cases
## Use Cases
Common Salesforce + CrewAI trigger scenarios include:
* **Lead Processing**: Automatically analyze and score incoming leads
* **Proposal Generation**: Create customized proposals based on opportunity data
* **Customer Insights**: Generate analysis reports from customer interaction history
* **Follow-up Automation**: Create personalized follow-up messages and recommendations
## Next Steps
For detailed setup instructions and advanced configuration options, please contact CrewAI Enterprise support who can provide tailored guidance for your specific Salesforce environment and business needs.
# Slack Trigger
Source: https://docs.crewai.com/en/enterprise/guides/slack-trigger
Trigger CrewAI crews directly from Slack using slash commands
This guide explains how to start a crew directly from Slack using CrewAI triggers.
## Prerequisites
* CrewAI Slack trigger installed and connected to your Slack workspace
* At least one crew configured in CrewAI
## Setup Steps
Verify that Slack is listed and is connected.
* Press Enter or select the "**Kickoff crew**" option. A dialog box titled "**Kickoff an AI Crew**" will appear.
* If your crew requires any inputs, click the "**Add Inputs**" button to provide them.
* The crew will start executing and you will see the results in the Slack channel.
* Click on the `Add Role` button to add a new role.
* Enter the details and permissions of the role and click the `Create Role` button to create the role.
* Once the member has accepted the invitation, you can add a role to them.
* Navigate back to `Roles` tab
* Go to the member you want to add a role to and under the `Role` column, click on the dropdown
* Select the role you want to add to the member
* Click the `Update` button to save the role
This will trigger an update that you can track using the progress bar. The system will pull the latest code from your repository and rebuild your deployment.
## 2. Resetting Bearer Token
If you need to generate a new bearer token (for example, if you suspect the current token might have been compromised):
1. Navigate to your crew in the CrewAI Enterprise platform
2. Find the `Bearer Token` section
3. Click the `Reset` button next to your current token
2. Locate the `Environment Variables` section (you will need to click the `Settings` icon to access it)
3. Edit the existing variables or add new ones in the fields provided
4. Click the `Update` button next to each variable you modify
5. Finally, click the `Update Deployment` button at the bottom of the page to apply the changes
3. Add an HTTP action step
* Set the action to `Send HTTP request`
* Use `POST` as the method
* Set the URL to your CrewAI Enterprise kickoff endpoint
* Add necessary headers (e.g., `Bearer Token`)
* In the body, include the JSON content as configured in step 2
* The crew will then kickoff at the pre-defined time.
2. Add a webhook step as the trigger:
* Select `Catch Webhook` as the trigger type
* This will generate a unique URL that will receive HTTP requests and trigger your flow
* Configure the email to use crew webhook body text
* Select `New Pushed Message` as the Trigger Event.
* Connect your Slack account if you haven't already.
* Configure the inputs for the Crew using the data from the Slack message.
* Select the 3 ellipsis button and then chose Push to Zapier
CrewAI Enterprise extends the power of the open-source framework with features designed for production deployments, collaboration, and scalability. Deploy your crews to a managed infrastructure and monitor their execution in real-time.
## Key Features
This matrix helps visualize how different approaches align with varying requirements for complexity and precision. Let's explore what each quadrant means and how it guides your architectural choices.
## The Complexity-Precision Matrix Explained
### What is Complexity?
In the context of CrewAI applications, **complexity** refers to:
* The number of distinct steps or operations required
* The diversity of tasks that need to be performed
* The interdependencies between different components
* The need for conditional logic and branching
* The sophistication of the overall workflow
### What is Precision?
**Precision** in this context refers to:
* The accuracy required in the final output
* The need for structured, predictable results
* The importance of reproducibility
* The level of control needed over each step
* The tolerance for variation in outputs
### The Four Quadrants
#### 1. Low Complexity, Low Precision
**Characteristics:**
* Simple, straightforward tasks
* Tolerance for some variation in outputs
* Limited number of steps
* Creative or exploratory applications
**Recommended Approach:** Simple Crews with minimal agents
**Example Use Cases:**
* Basic content generation
* Idea brainstorming
* Simple summarization tasks
* Creative writing assistance
#### 2. Low Complexity, High Precision
**Characteristics:**
* Simple workflows that require exact, structured outputs
* Need for reproducible results
* Limited steps but high accuracy requirements
* Often involves data processing or transformation
**Recommended Approach:** Flows with direct LLM calls or simple Crews with structured outputs
**Example Use Cases:**
* Data extraction and transformation
* Form filling and validation
* Structured content generation (JSON, XML)
* Simple classification tasks
#### 3. High Complexity, Low Precision
**Characteristics:**
* Multi-stage processes with many steps
* Creative or exploratory outputs
* Complex interactions between components
* Tolerance for variation in final results
**Recommended Approach:** Complex Crews with multiple specialized agents
**Example Use Cases:**
* Research and analysis
* Content creation pipelines
* Exploratory data analysis
* Creative problem-solving
#### 4. High Complexity, High Precision
**Characteristics:**
* Complex workflows requiring structured outputs
* Multiple interdependent steps with strict accuracy requirements
* Need for both sophisticated processing and precise results
* Often mission-critical applications
**Recommended Approach:** Flows orchestrating multiple Crews with validation steps
**Example Use Cases:**
* Enterprise decision support systems
* Complex data processing pipelines
* Multi-stage document processing
* Regulated industry applications
## Choosing Between Crews and Flows
### When to Choose Crews
Crews are ideal when:
1. **You need collaborative intelligence** - Multiple agents with different specializations need to work together
2. **The problem requires emergent thinking** - The solution benefits from different perspectives and approaches
3. **The task is primarily creative or analytical** - The work involves research, content creation, or analysis
4. **You value adaptability over strict structure** - The workflow can benefit from agent autonomy
5. **The output format can be somewhat flexible** - Some variation in output structure is acceptable
```python
# Example: Research Crew for market analysis
from crewai import Agent, Crew, Process, Task
# Create specialized agents
researcher = Agent(
role="Market Research Specialist",
goal="Find comprehensive market data on emerging technologies",
backstory="You are an expert at discovering market trends and gathering data."
)
analyst = Agent(
role="Market Analyst",
goal="Analyze market data and identify key opportunities",
backstory="You excel at interpreting market data and spotting valuable insights."
)
# Define their tasks
research_task = Task(
description="Research the current market landscape for AI-powered healthcare solutions",
expected_output="Comprehensive market data including key players, market size, and growth trends",
agent=researcher
)
analysis_task = Task(
description="Analyze the market data and identify the top 3 investment opportunities",
expected_output="Analysis report with 3 recommended investment opportunities and rationale",
agent=analyst,
context=[research_task]
)
# Create the crew
market_analysis_crew = Crew(
agents=[researcher, analyst],
tasks=[research_task, analysis_task],
process=Process.sequential,
verbose=True
)
# Run the crew
result = market_analysis_crew.kickoff()
```
### When to Choose Flows
Flows are ideal when:
1. **You need precise control over execution** - The workflow requires exact sequencing and state management
2. **The application has complex state requirements** - You need to maintain and transform state across multiple steps
3. **You need structured, predictable outputs** - The application requires consistent, formatted results
4. **The workflow involves conditional logic** - Different paths need to be taken based on intermediate results
5. **You need to combine AI with procedural code** - The solution requires both AI capabilities and traditional programming
```python
# Example: Customer Support Flow with structured processing
from crewai.flow.flow import Flow, listen, router, start
from pydantic import BaseModel
from typing import List, Dict
# Define structured state
class SupportTicketState(BaseModel):
ticket_id: str = ""
customer_name: str = ""
issue_description: str = ""
category: str = ""
priority: str = "medium"
resolution: str = ""
satisfaction_score: int = 0
class CustomerSupportFlow(Flow[SupportTicketState]):
@start()
def receive_ticket(self):
# In a real app, this might come from an API
self.state.ticket_id = "TKT-12345"
self.state.customer_name = "Alex Johnson"
self.state.issue_description = "Unable to access premium features after payment"
return "Ticket received"
@listen(receive_ticket)
def categorize_ticket(self, _):
# Use a direct LLM call for categorization
from crewai import LLM
llm = LLM(model="openai/gpt-4o-mini")
prompt = f"""
Categorize the following customer support issue into one of these categories:
- Billing
- Account Access
- Technical Issue
- Feature Request
- Other
Issue: {self.state.issue_description}
Return only the category name.
"""
self.state.category = llm.call(prompt).strip()
return self.state.category
@router(categorize_ticket)
def route_by_category(self, category):
# Route to different handlers based on category
return category.lower().replace(" ", "_")
@listen("billing")
def handle_billing_issue(self):
# Handle billing-specific logic
self.state.priority = "high"
# More billing-specific processing...
return "Billing issue handled"
@listen("account_access")
def handle_access_issue(self):
# Handle access-specific logic
self.state.priority = "high"
# More access-specific processing...
return "Access issue handled"
# Additional category handlers...
@listen("billing", "account_access", "technical_issue", "feature_request", "other")
def resolve_ticket(self, resolution_info):
# Final resolution step
self.state.resolution = f"Issue resolved: {resolution_info}"
return self.state.resolution
# Run the flow
support_flow = CustomerSupportFlow()
result = support_flow.kickoff()
```
### When to Combine Crews and Flows
The most sophisticated applications often benefit from combining Crews and Flows:
1. **Complex multi-stage processes** - Use Flows to orchestrate the overall process and Crews for complex subtasks
2. **Applications requiring both creativity and structure** - Use Crews for creative tasks and Flows for structured processing
3. **Enterprise-grade AI applications** - Use Flows to manage state and process flow while leveraging Crews for specialized work
```python
# Example: Content Production Pipeline combining Crews and Flows
from crewai.flow.flow import Flow, listen, start
from crewai import Agent, Crew, Process, Task
from pydantic import BaseModel
from typing import List, Dict
class ContentState(BaseModel):
topic: str = ""
target_audience: str = ""
content_type: str = ""
outline: Dict = {}
draft_content: str = ""
final_content: str = ""
seo_score: int = 0
class ContentProductionFlow(Flow[ContentState]):
@start()
def initialize_project(self):
# Set initial parameters
self.state.topic = "Sustainable Investing"
self.state.target_audience = "Millennial Investors"
self.state.content_type = "Blog Post"
return "Project initialized"
@listen(initialize_project)
def create_outline(self, _):
# Use a research crew to create an outline
researcher = Agent(
role="Content Researcher",
goal=f"Research {self.state.topic} for {self.state.target_audience}",
backstory="You are an expert researcher with deep knowledge of content creation."
)
outliner = Agent(
role="Content Strategist",
goal=f"Create an engaging outline for a {self.state.content_type}",
backstory="You excel at structuring content for maximum engagement."
)
research_task = Task(
description=f"Research {self.state.topic} focusing on what would interest {self.state.target_audience}",
expected_output="Comprehensive research notes with key points and statistics",
agent=researcher
)
outline_task = Task(
description=f"Create an outline for a {self.state.content_type} about {self.state.topic}",
expected_output="Detailed content outline with sections and key points",
agent=outliner,
context=[research_task]
)
outline_crew = Crew(
agents=[researcher, outliner],
tasks=[research_task, outline_task],
process=Process.sequential,
verbose=True
)
# Run the crew and store the result
result = outline_crew.kickoff()
# Parse the outline (in a real app, you might use a more robust parsing approach)
import json
try:
self.state.outline = json.loads(result.raw)
except:
# Fallback if not valid JSON
self.state.outline = {"sections": result.raw}
return "Outline created"
@listen(create_outline)
def write_content(self, _):
# Use a writing crew to create the content
writer = Agent(
role="Content Writer",
goal=f"Write engaging content for {self.state.target_audience}",
backstory="You are a skilled writer who creates compelling content."
)
editor = Agent(
role="Content Editor",
goal="Ensure content is polished, accurate, and engaging",
backstory="You have a keen eye for detail and a talent for improving content."
)
writing_task = Task(
description=f"Write a {self.state.content_type} about {self.state.topic} following this outline: {self.state.outline}",
expected_output="Complete draft content in markdown format",
agent=writer
)
editing_task = Task(
description="Edit and improve the draft content for clarity, engagement, and accuracy",
expected_output="Polished final content in markdown format",
agent=editor,
context=[writing_task]
)
writing_crew = Crew(
agents=[writer, editor],
tasks=[writing_task, editing_task],
process=Process.sequential,
verbose=True
)
# Run the crew and store the result
result = writing_crew.kickoff()
self.state.final_content = result.raw
return "Content created"
@listen(write_content)
def optimize_for_seo(self, _):
# Use a direct LLM call for SEO optimization
from crewai import LLM
llm = LLM(model="openai/gpt-4o-mini")
prompt = f"""
Analyze this content for SEO effectiveness for the keyword "{self.state.topic}".
Rate it on a scale of 1-100 and provide 3 specific recommendations for improvement.
Content: {self.state.final_content[:1000]}... (truncated for brevity)
Format your response as JSON with the following structure:
{{
"score": 85,
"recommendations": [
"Recommendation 1",
"Recommendation 2",
"Recommendation 3"
]
}}
"""
seo_analysis = llm.call(prompt)
# Parse the SEO analysis
import json
try:
analysis = json.loads(seo_analysis)
self.state.seo_score = analysis.get("score", 0)
return analysis
except:
self.state.seo_score = 50
return {"score": 50, "recommendations": ["Unable to parse SEO analysis"]}
# Run the flow
content_flow = ContentProductionFlow()
result = content_flow.kickoff()
```
## Practical Evaluation Framework
To determine the right approach for your specific use case, follow this step-by-step evaluation framework:
### Step 1: Assess Complexity
Rate your application's complexity on a scale of 1-10 by considering:
1. **Number of steps**: How many distinct operations are required?
* 1-3 steps: Low complexity (1-3)
* 4-7 steps: Medium complexity (4-7)
* 8+ steps: High complexity (8-10)
2. **Interdependencies**: How interconnected are the different parts?
* Few dependencies: Low complexity (1-3)
* Some dependencies: Medium complexity (4-7)
* Many complex dependencies: High complexity (8-10)
3. **Conditional logic**: How much branching and decision-making is needed?
* Linear process: Low complexity (1-3)
* Some branching: Medium complexity (4-7)
* Complex decision trees: High complexity (8-10)
4. **Domain knowledge**: How specialized is the knowledge required?
* General knowledge: Low complexity (1-3)
* Some specialized knowledge: Medium complexity (4-7)
* Deep expertise in multiple domains: High complexity (8-10)
Calculate your average score to determine overall complexity.
### Step 2: Assess Precision Requirements
Rate your precision requirements on a scale of 1-10 by considering:
1. **Output structure**: How structured must the output be?
* Free-form text: Low precision (1-3)
* Semi-structured: Medium precision (4-7)
* Strictly formatted (JSON, XML): High precision (8-10)
2. **Accuracy needs**: How important is factual accuracy?
* Creative content: Low precision (1-3)
* Informational content: Medium precision (4-7)
* Critical information: High precision (8-10)
3. **Reproducibility**: How consistent must results be across runs?
* Variation acceptable: Low precision (1-3)
* Some consistency needed: Medium precision (4-7)
* Exact reproducibility required: High precision (8-10)
4. **Error tolerance**: What is the impact of errors?
* Low impact: Low precision (1-3)
* Moderate impact: Medium precision (4-7)
* High impact: High precision (8-10)
Calculate your average score to determine overall precision requirements.
### Step 3: Map to the Matrix
Plot your complexity and precision scores on the matrix:
* **Low Complexity (1-4), Low Precision (1-4)**: Simple Crews
* **Low Complexity (1-4), High Precision (5-10)**: Flows with direct LLM calls
* **High Complexity (5-10), Low Precision (1-4)**: Complex Crews
* **High Complexity (5-10), High Precision (5-10)**: Flows orchestrating Crews
### Step 4: Consider Additional Factors
Beyond complexity and precision, consider:
1. **Development time**: Crews are often faster to prototype
2. **Maintenance needs**: Flows provide better long-term maintainability
3. **Team expertise**: Consider your team's familiarity with different approaches
4. **Scalability requirements**: Flows typically scale better for complex applications
5. **Integration needs**: Consider how the solution will integrate with existing systems
## Conclusion
Choosing between Crews and Flows—or combining them—is a critical architectural decision that impacts the effectiveness, maintainability, and scalability of your CrewAI application. By evaluating your use case along the dimensions of complexity and precision, you can make informed decisions that align with your specific requirements.
Remember that the best approach often evolves as your application matures. Start with the simplest solution that meets your needs, and be prepared to refine your architecture as you gain experience and your requirements become clearer.
## Step 2: Explore the Project Structure
Let's take a moment to understand the project structure created by the CLI. CrewAI follows best practices for Python projects, making it easy to maintain and extend your code as your crews become more complex.
```
research_crew/
├── .gitignore
├── pyproject.toml
├── README.md
├── .env
└── src/
└── research_crew/
├── __init__.py
├── main.py
├── crew.py
├── tools/
│ ├── custom_tool.py
│ └── __init__.py
└── config/
├── agents.yaml
└── tasks.yaml
```
This structure follows best practices for Python projects and makes it easy to organize your code. The separation of configuration files (in YAML) from implementation code (in Python) makes it easy to modify your crew's behavior without changing the underlying code.
## Step 3: Configure Your Agents
Now comes the fun part - defining your AI agents! In CrewAI, agents are specialized entities with specific roles, goals, and backstories that shape their behavior. Think of them as characters in a play, each with their own personality and purpose.
For our research crew, we'll create two agents:
1. A **researcher** who excels at finding and organizing information
2. An **analyst** who can interpret research findings and create insightful reports
Let's modify the `agents.yaml` file to define these specialized agents. Be sure
to set `llm` to the provider you are using.
```yaml
# src/research_crew/config/agents.yaml
researcher:
role: >
Senior Research Specialist for {topic}
goal: >
Find comprehensive and accurate information about {topic}
with a focus on recent developments and key insights
backstory: >
You are an experienced research specialist with a talent for
finding relevant information from various sources. You excel at
organizing information in a clear and structured manner, making
complex topics accessible to others.
llm: provider/model-id # e.g. openai/gpt-4o, google/gemini-2.0-flash, anthropic/claude...
analyst:
role: >
Data Analyst and Report Writer for {topic}
goal: >
Analyze research findings and create a comprehensive, well-structured
report that presents insights in a clear and engaging way
backstory: >
You are a skilled analyst with a background in data interpretation
and technical writing. You have a talent for identifying patterns
and extracting meaningful insights from research data, then
communicating those insights effectively through well-crafted reports.
llm: provider/model-id # e.g. openai/gpt-4o, google/gemini-2.0-flash, anthropic/claude...
```
Notice how each agent has a distinct role, goal, and backstory. These elements aren't just descriptive - they actively shape how the agent approaches its tasks. By crafting these carefully, you can create agents with specialized skills and perspectives that complement each other.
## Step 4: Define Your Tasks
With our agents defined, we now need to give them specific tasks to perform. Tasks in CrewAI represent the concrete work that agents will perform, with detailed instructions and expected outputs.
For our research crew, we'll define two main tasks:
1. A **research task** for gathering comprehensive information
2. An **analysis task** for creating an insightful report
Let's modify the `tasks.yaml` file:
```yaml
# src/research_crew/config/tasks.yaml
research_task:
description: >
Conduct thorough research on {topic}. Focus on:
1. Key concepts and definitions
2. Historical development and recent trends
3. Major challenges and opportunities
4. Notable applications or case studies
5. Future outlook and potential developments
Make sure to organize your findings in a structured format with clear sections.
expected_output: >
A comprehensive research document with well-organized sections covering
all the requested aspects of {topic}. Include specific facts, figures,
and examples where relevant.
agent: researcher
analysis_task:
description: >
Analyze the research findings and create a comprehensive report on {topic}.
Your report should:
1. Begin with an executive summary
2. Include all key information from the research
3. Provide insightful analysis of trends and patterns
4. Offer recommendations or future considerations
5. Be formatted in a professional, easy-to-read style with clear headings
expected_output: >
A polished, professional report on {topic} that presents the research
findings with added analysis and insights. The report should be well-structured
with an executive summary, main sections, and conclusion.
agent: analyst
context:
- research_task
output_file: output/report.md
```
Note the `context` field in the analysis task - this is a powerful feature that allows the analyst to access the output of the research task. This creates a workflow where information flows naturally between agents, just as it would in a human team.
## Step 5: Configure Your Crew
Now it's time to bring everything together by configuring our crew. The crew is the container that orchestrates how agents work together to complete tasks.
Let's modify the `crew.py` file:
```python
# src/research_crew/crew.py
from crewai import Agent, Crew, Process, Task
from crewai.project import CrewBase, agent, crew, task
from crewai_tools import SerperDevTool
from crewai.agents.agent_builder.base_agent import BaseAgent
from typing import List
@CrewBase
class ResearchCrew():
"""Research crew for comprehensive topic analysis and reporting"""
agents: List[BaseAgent]
tasks: List[Task]
@agent
def researcher(self) -> Agent:
return Agent(
config=self.agents_config['researcher'], # type: ignore[index]
verbose=True,
tools=[SerperDevTool()]
)
@agent
def analyst(self) -> Agent:
return Agent(
config=self.agents_config['analyst'], # type: ignore[index]
verbose=True
)
@task
def research_task(self) -> Task:
return Task(
config=self.tasks_config['research_task'] # type: ignore[index]
)
@task
def analysis_task(self) -> Task:
return Task(
config=self.tasks_config['analysis_task'], # type: ignore[index]
output_file='output/report.md'
)
@crew
def crew(self) -> Crew:
"""Creates the research crew"""
return Crew(
agents=self.agents,
tasks=self.tasks,
process=Process.sequential,
verbose=True,
)
```
In this code, we're:
1. Creating the researcher agent and equipping it with the SerperDevTool to search the web
2. Creating the analyst agent
3. Setting up the research and analysis tasks
4. Configuring the crew to run tasks sequentially (the analyst will wait for the researcher to finish)
This is where the magic happens - with just a few lines of code, we've defined a collaborative AI system where specialized agents work together in a coordinated process.
## Step 6: Set Up Your Main Script
Now, let's set up the main script that will run our crew. This is where we provide the specific topic we want our crew to research.
```python
#!/usr/bin/env python
# src/research_crew/main.py
import os
from research_crew.crew import ResearchCrew
# Create output directory if it doesn't exist
os.makedirs('output', exist_ok=True)
def run():
"""
Run the research crew.
"""
inputs = {
'topic': 'Artificial Intelligence in Healthcare'
}
# Create and run the crew
result = ResearchCrew().crew().kickoff(inputs=inputs)
# Print the result
print("\n\n=== FINAL REPORT ===\n\n")
print(result.raw)
print("\n\nReport has been saved to output/report.md")
if __name__ == "__main__":
run()
```
This script prepares the environment, specifies our research topic, and kicks off the crew's work. The power of CrewAI is evident in how simple this code is - all the complexity of managing multiple AI agents is handled by the framework.
## Step 7: Set Up Your Environment Variables
Create a `.env` file in your project root with your API keys:
```sh
SERPER_API_KEY=your_serper_api_key
# Add your provider's API key here too.
```
See the [LLM Setup guide](/en/concepts/llms#setting-up-your-llm) for details on configuring your provider of choice. You can get a Serper API key from [Serper.dev](https://serper.dev/).
## Step 8: Install Dependencies
Install the required dependencies using the CrewAI CLI:
```bash
crewai install
```
This command will:
1. Read the dependencies from your project configuration
2. Create a virtual environment if needed
3. Install all required packages
## Step 9: Run Your Crew
Now for the exciting moment - it's time to run your crew and see AI collaboration in action!
```bash
crewai run
```
When you run this command, you'll see your crew spring to life. The researcher will gather information about the specified topic, and the analyst will then create a comprehensive report based on that research. You'll see the agents' thought processes, actions, and outputs in real-time as they work together to complete their tasks.
## Step 10: Review the Output
Once the crew completes its work, you'll find the final report in the `output/report.md` file. The report will include:
1. An executive summary
2. Detailed information about the topic
3. Analysis and insights
4. Recommendations or future considerations
Take a moment to appreciate what you've accomplished - you've created a system where multiple AI agents collaborated on a complex task, each contributing their specialized skills to produce a result that's greater than what any single agent could achieve alone.
## Exploring Other CLI Commands
CrewAI offers several other useful CLI commands for working with crews:
```bash
# View all available commands
crewai --help
# Run the crew
crewai run
# Test the crew
crewai test
# Reset crew memories
crewai reset-memories
# Replay from a specific task
crewai replay -t 
## Step 2: Understanding the Project Structure
The generated project has the following structure. Take a moment to familiarize yourself with it, as understanding this structure will help you create more complex flows in the future.
```
guide_creator_flow/
├── .gitignore
├── pyproject.toml
├── README.md
├── .env
├── main.py
├── crews/
│ └── poem_crew/
│ ├── config/
│ │ ├── agents.yaml
│ │ └── tasks.yaml
│ └── poem_crew.py
└── tools/
└── custom_tool.py
```
This structure provides a clear separation between different components of your flow:
* The main flow logic in the `main.py` file
* Specialized crews in the `crews` directory
* Custom tools in the `tools` directory
We'll modify this structure to create our guide creator flow, which will orchestrate the process of generating comprehensive learning guides.
## Step 3: Add a Content Writer Crew
Our flow will need a specialized crew to handle the content creation process. Let's use the CrewAI CLI to add a content writer crew:
```bash
crewai flow add-crew content-crew
```
This command automatically creates the necessary directories and template files for your crew. The content writer crew will be responsible for writing and reviewing sections of our guide, working within the overall flow orchestrated by our main application.
## Step 4: Configure the Content Writer Crew
Now, let's modify the generated files for the content writer crew. We'll set up two specialized agents - a writer and a reviewer - that will collaborate to create high-quality content for our guide.
1. First, update the agents configuration file to define our content creation team:
Remember to set `llm` to the provider you are using.
```yaml
# src/guide_creator_flow/crews/content_crew/config/agents.yaml
content_writer:
role: >
Educational Content Writer
goal: >
Create engaging, informative content that thoroughly explains the assigned topic
and provides valuable insights to the reader
backstory: >
You are a talented educational writer with expertise in creating clear, engaging
content. You have a gift for explaining complex concepts in accessible language
and organizing information in a way that helps readers build their understanding.
llm: provider/model-id # e.g. openai/gpt-4o, google/gemini-2.0-flash, anthropic/claude...
content_reviewer:
role: >
Educational Content Reviewer and Editor
goal: >
Ensure content is accurate, comprehensive, well-structured, and maintains
consistency with previously written sections
backstory: >
You are a meticulous editor with years of experience reviewing educational
content. You have an eye for detail, clarity, and coherence. You excel at
improving content while maintaining the original author's voice and ensuring
consistent quality across multiple sections.
llm: provider/model-id # e.g. openai/gpt-4o, google/gemini-2.0-flash, anthropic/claude...
```
These agent definitions establish the specialized roles and perspectives that will shape how our AI agents approach content creation. Notice how each agent has a distinct purpose and expertise.
2. Next, update the tasks configuration file to define the specific writing and reviewing tasks:
```yaml
# src/guide_creator_flow/crews/content_crew/config/tasks.yaml
write_section_task:
description: >
Write a comprehensive section on the topic: "{section_title}"
Section description: {section_description}
Target audience: {audience_level} level learners
Your content should:
1. Begin with a brief introduction to the section topic
2. Explain all key concepts clearly with examples
3. Include practical applications or exercises where appropriate
4. End with a summary of key points
5. Be approximately 500-800 words in length
Format your content in Markdown with appropriate headings, lists, and emphasis.
Previously written sections:
{previous_sections}
Make sure your content maintains consistency with previously written sections
and builds upon concepts that have already been explained.
expected_output: >
A well-structured, comprehensive section in Markdown format that thoroughly
explains the topic and is appropriate for the target audience.
agent: content_writer
review_section_task:
description: >
Review and improve the following section on "{section_title}":
{draft_content}
Target audience: {audience_level} level learners
Previously written sections:
{previous_sections}
Your review should:
1. Fix any grammatical or spelling errors
2. Improve clarity and readability
3. Ensure content is comprehensive and accurate
4. Verify consistency with previously written sections
5. Enhance the structure and flow
6. Add any missing key information
Provide the improved version of the section in Markdown format.
expected_output: >
An improved, polished version of the section that maintains the original
structure but enhances clarity, accuracy, and consistency.
agent: content_reviewer
context:
- write_section_task
```
These task definitions provide detailed instructions to our agents, ensuring they produce content that meets our quality standards. Note how the `context` parameter in the review task creates a workflow where the reviewer has access to the writer's output.
3. Now, update the crew implementation file to define how our agents and tasks work together:
```python
# src/guide_creator_flow/crews/content_crew/content_crew.py
from crewai import Agent, Crew, Process, Task
from crewai.project import CrewBase, agent, crew, task
from crewai.agents.agent_builder.base_agent import BaseAgent
from typing import List
@CrewBase
class ContentCrew():
"""Content writing crew"""
agents: List[BaseAgent]
tasks: List[Task]
@agent
def content_writer(self) -> Agent:
return Agent(
config=self.agents_config['content_writer'], # type: ignore[index]
verbose=True
)
@agent
def content_reviewer(self) -> Agent:
return Agent(
config=self.agents_config['content_reviewer'], # type: ignore[index]
verbose=True
)
@task
def write_section_task(self) -> Task:
return Task(
config=self.tasks_config['write_section_task'] # type: ignore[index]
)
@task
def review_section_task(self) -> Task:
return Task(
config=self.tasks_config['review_section_task'], # type: ignore[index]
context=[self.write_section_task()]
)
@crew
def crew(self) -> Crew:
"""Creates the content writing crew"""
return Crew(
agents=self.agents,
tasks=self.tasks,
process=Process.sequential,
verbose=True,
)
```
This crew definition establishes the relationship between our agents and tasks, setting up a sequential process where the content writer creates a draft and then the reviewer improves it. While this crew can function independently, in our flow it will be orchestrated as part of a larger system.
## Step 5: Create the Flow
Now comes the exciting part - creating the flow that will orchestrate the entire guide creation process. This is where we'll combine regular Python code, direct LLM calls, and our content creation crew into a cohesive system.
Our flow will:
1. Get user input for a topic and audience level
2. Make a direct LLM call to create a structured guide outline
3. Process each section sequentially using the content writer crew
4. Combine everything into a final comprehensive document
Let's create our flow in the `main.py` file:
```python
#!/usr/bin/env python
import json
import os
from typing import List, Dict
from pydantic import BaseModel, Field
from crewai import LLM
from crewai.flow.flow import Flow, listen, start
from guide_creator_flow.crews.content_crew.content_crew import ContentCrew
# Define our models for structured data
class Section(BaseModel):
title: str = Field(description="Title of the section")
description: str = Field(description="Brief description of what the section should cover")
class GuideOutline(BaseModel):
title: str = Field(description="Title of the guide")
introduction: str = Field(description="Introduction to the topic")
target_audience: str = Field(description="Description of the target audience")
sections: List[Section] = Field(description="List of sections in the guide")
conclusion: str = Field(description="Conclusion or summary of the guide")
# Define our flow state
class GuideCreatorState(BaseModel):
topic: str = ""
audience_level: str = ""
guide_outline: GuideOutline = None
sections_content: Dict[str, str] = {}
class GuideCreatorFlow(Flow[GuideCreatorState]):
"""Flow for creating a comprehensive guide on any topic"""
@start()
def get_user_input(self):
"""Get input from the user about the guide topic and audience"""
print("\n=== Create Your Comprehensive Guide ===\n")
# Get user input
self.state.topic = input("What topic would you like to create a guide for? ")
# Get audience level with validation
while True:
audience = input("Who is your target audience? (beginner/intermediate/advanced) ").lower()
if audience in ["beginner", "intermediate", "advanced"]:
self.state.audience_level = audience
break
print("Please enter 'beginner', 'intermediate', or 'advanced'")
print(f"\nCreating a guide on {self.state.topic} for {self.state.audience_level} audience...\n")
return self.state
@listen(get_user_input)
def create_guide_outline(self, state):
"""Create a structured outline for the guide using a direct LLM call"""
print("Creating guide outline...")
# Initialize the LLM
llm = LLM(model="openai/gpt-4o-mini", response_format=GuideOutline)
# Create the messages for the outline
messages = [
{"role": "system", "content": "You are a helpful assistant designed to output JSON."},
{"role": "user", "content": f"""
Create a detailed outline for a comprehensive guide on "{state.topic}" for {state.audience_level} level learners.
The outline should include:
1. A compelling title for the guide
2. An introduction to the topic
3. 4-6 main sections that cover the most important aspects of the topic
4. A conclusion or summary
For each section, provide a clear title and a brief description of what it should cover.
"""}
]
# Make the LLM call with JSON response format
response = llm.call(messages=messages)
# Parse the JSON response
outline_dict = json.loads(response)
self.state.guide_outline = GuideOutline(**outline_dict)
# Ensure output directory exists before saving
os.makedirs("output", exist_ok=True)
# Save the outline to a file
with open("output/guide_outline.json", "w") as f:
json.dump(outline_dict, f, indent=2)
print(f"Guide outline created with {len(self.state.guide_outline.sections)} sections")
return self.state.guide_outline
@listen(create_guide_outline)
def write_and_compile_guide(self, outline):
"""Write all sections and compile the guide"""
print("Writing guide sections and compiling...")
completed_sections = []
# Process sections one by one to maintain context flow
for section in outline.sections:
print(f"Processing section: {section.title}")
# Build context from previous sections
previous_sections_text = ""
if completed_sections:
previous_sections_text = "# Previously Written Sections\n\n"
for title in completed_sections:
previous_sections_text += f"## {title}\n\n"
previous_sections_text += self.state.sections_content.get(title, "") + "\n\n"
else:
previous_sections_text = "No previous sections written yet."
# Run the content crew for this section
result = ContentCrew().crew().kickoff(inputs={
"section_title": section.title,
"section_description": section.description,
"audience_level": self.state.audience_level,
"previous_sections": previous_sections_text,
"draft_content": ""
})
# Store the content
self.state.sections_content[section.title] = result.raw
completed_sections.append(section.title)
print(f"Section completed: {section.title}")
# Compile the final guide
guide_content = f"# {outline.title}\n\n"
guide_content += f"## Introduction\n\n{outline.introduction}\n\n"
# Add each section in order
for section in outline.sections:
section_content = self.state.sections_content.get(section.title, "")
guide_content += f"\n\n{section_content}\n\n"
# Add conclusion
guide_content += f"## Conclusion\n\n{outline.conclusion}\n\n"
# Save the guide
with open("output/complete_guide.md", "w") as f:
f.write(guide_content)
print("\nComplete guide compiled and saved to output/complete_guide.md")
return "Guide creation completed successfully"
def kickoff():
"""Run the guide creator flow"""
GuideCreatorFlow().kickoff()
print("\n=== Flow Complete ===")
print("Your comprehensive guide is ready in the output directory.")
print("Open output/complete_guide.md to view it.")
def plot():
"""Generate a visualization of the flow"""
flow = GuideCreatorFlow()
flow.plot("guide_creator_flow")
print("Flow visualization saved to guide_creator_flow.html")
if __name__ == "__main__":
kickoff()
```
Let's analyze what's happening in this flow:
1. We define Pydantic models for structured data, ensuring type safety and clear data representation
2. We create a state class to maintain data across different steps of the flow
3. We implement three main flow steps:
* Getting user input with the `@start()` decorator
* Creating a guide outline with a direct LLM call
* Processing sections with our content crew
4. We use the `@listen()` decorator to establish event-driven relationships between steps
This is the power of flows - combining different types of processing (user interaction, direct LLM calls, crew-based tasks) into a coherent, event-driven system.
## Step 6: Set Up Your Environment Variables
Create a `.env` file in your project root with your API keys. See the [LLM setup
guide](/en/concepts/llms#setting-up-your-llm) for details on configuring a provider.
```sh .env
OPENAI_API_KEY=your_openai_api_key
# or
GEMINI_API_KEY=your_gemini_api_key
# or
ANTHROPIC_API_KEY=your_anthropic_api_key
```
## Step 7: Install Dependencies
Install the required dependencies:
```bash
crewai install
```
## Step 8: Run Your Flow
Now it's time to see your flow in action! Run it using the CrewAI CLI:
```bash
crewai flow kickoff
```
When you run this command, you'll see your flow spring to life:
1. It will prompt you for a topic and audience level
2. It will create a structured outline for your guide
3. It will process each section, with the content writer and reviewer collaborating on each
4. Finally, it will compile everything into a comprehensive guide
This demonstrates the power of flows to orchestrate complex processes involving multiple components, both AI and non-AI.
## Step 9: Visualize Your Flow
One of the powerful features of flows is the ability to visualize their structure:
```bash
crewai flow plot
```
This will create an HTML file that shows the structure of your flow, including the relationships between different steps and the data that flows between them. This visualization can be invaluable for understanding and debugging complex flows.
## Step 10: Review the Output
Once the flow completes, you'll find two files in the `output` directory:
1. `guide_outline.json`: Contains the structured outline of the guide
2. `complete_guide.md`: The comprehensive guide with all sections
Take a moment to review these files and appreciate what you've built - a system that combines user input, direct AI interactions, and collaborative agent work to produce a complex, high-quality output.
## The Art of the Possible: Beyond Your First Flow
What you've learned in this guide provides a foundation for creating much more sophisticated AI systems. Here are some ways you could extend this basic flow:
### Enhancing User Interaction
You could create more interactive flows with:
* Web interfaces for input and output
* Real-time progress updates
* Interactive feedback and refinement loops
* Multi-stage user interactions
### Adding More Processing Steps
You could expand your flow with additional steps for:
* Research before outline creation
* Image generation for illustrations
* Code snippet generation for technical guides
* Final quality assurance and fact-checking
### Creating More Complex Flows
You could implement more sophisticated flow patterns:
* Conditional branching based on user preferences or content type
* Parallel processing of independent sections
* Iterative refinement loops with feedback
* Integration with external APIs and services
### Applying to Different Domains
The same patterns can be applied to create flows for:
* **Interactive storytelling**: Create personalized stories based on user input
* **Business intelligence**: Process data, generate insights, and create reports
* **Product development**: Facilitate ideation, design, and planning
* **Educational systems**: Create personalized learning experiences
## Key Features Demonstrated
This guide creator flow demonstrates several powerful features of CrewAI:
1. **User interaction**: The flow collects input directly from the user
2. **Direct LLM calls**: Uses the LLM class for efficient, single-purpose AI interactions
3. **Structured data with Pydantic**: Uses Pydantic models to ensure type safety
4. **Sequential processing with context**: Writes sections in order, providing previous sections for context
5. **Multi-agent crews**: Leverages specialized agents (writer and reviewer) for content creation
6. **State management**: Maintains state across different steps of the process
7. **Event-driven architecture**: Uses the `@listen` decorator to respond to events
## Understanding the Flow Structure
Let's break down the key components of flows to help you understand how to build your own:
### 1. Direct LLM Calls
Flows allow you to make direct calls to language models when you need simple, structured responses:
```python
llm = LLM(
model="model-id-here", # gpt-4o, gemini-2.0-flash, anthropic/claude...
response_format=GuideOutline
)
response = llm.call(messages=messages)
```
This is more efficient than using a crew when you need a specific, structured output.
### 2. Event-Driven Architecture
Flows use decorators to establish relationships between components:
```python
@start()
def get_user_input(self):
# First step in the flow
# ...
@listen(get_user_input)
def create_guide_outline(self, state):
# This runs when get_user_input completes
# ...
```
This creates a clear, declarative structure for your application.
### 3. State Management
Flows maintain state across steps, making it easy to share data:
```python
class GuideCreatorState(BaseModel):
topic: str = ""
audience_level: str = ""
guide_outline: GuideOutline = None
sections_content: Dict[str, str] = {}
```
This provides a type-safe way to track and transform data throughout your flow.
### 4. Crew Integration
Flows can seamlessly integrate with crews for complex collaborative tasks:
```python
result = ContentCrew().crew().kickoff(inputs={
"section_title": section.title,
# ...
})
```
This allows you to use the right tool for each part of your application - direct LLM calls for simple tasks and crews for complex collaboration.
## Next Steps
Now that you've built your first flow, you can:
1. Experiment with more complex flow structures and patterns
2. Try using `@router()` to create conditional branches in your flows
3. Explore the `and_` and `or_` functions for more complex parallel execution
4. Connect your flow to external APIs, databases, or user interfaces
5. Combine multiple specialized crews in a single flow
| Component | Description | Key Features |
| :------------ | :------------------------: | :-------------------------------------------------------------------------------------------------------------------------------- |
| **Crew** | The top-level organization | • Manages AI agent teams
| Component | Description | Key Features |
| :--------------- | :-------------------------------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Flow** | Structured workflow orchestration | • Manages execution paths
## Best Practices
1. **Be specific in your image generation prompts** to get the best results.
2. **Consider generation time** - Image generation can take some time, so factor this into your task planning.
3. **Follow usage policies** - Always comply with OpenAI's usage policies when generating images.
## Troubleshooting
1. **Check API access** - Ensure your OpenAI API key has access to DALL-E.
2. **Version compatibility** - Check that you're using the latest version of crewAI and crewai-tools.
3. **Tool configuration** - Verify that the DALL-E tool is correctly added to the agent's tool list.
# Force Tool Output as Result
Source: https://docs.crewai.com/en/learn/force-tool-output-as-result
Learn how to force tool output as the result in an Agent's task in CrewAI.
## Introduction
In CrewAI, you can force the output of a tool as the result of an agent's task.
This feature is useful when you want to ensure that the tool output is captured and returned as the task result, avoiding any agent modification during the task execution.
## Forcing Tool Output as Result
To force the tool output as the result of an agent's task, you need to set the `result_as_answer` parameter to `True` when adding a tool to the agent.
This parameter ensures that the tool output is captured and returned as the task result, without any modifications by the agent.
Here's an example of how to force the tool output as the result of an agent's task:
```python Code
from crewai.agent import Agent
from my_tool import MyCustomTool
# Create a coding agent with the custom tool
coding_agent = Agent(
role="Data Scientist",
goal="Produce amazing reports on AI",
backstory="You work with data and AI",
tools=[MyCustomTool(result_as_answer=True)],
)
# Assuming the tool's execution and result population occurs within the system
task_result = coding_agent.execute_task(task)
```
## Workflow in Action
**Advanced Testing Features:**
* **Multi-Model Comparison**: Test multiple LLMs simultaneously across the same tasks and inputs. Compare performance between GPT-4o, Claude, Llama, Groq, Cerebras, and other leading models in parallel to identify the best fit for your specific use case.
* **Statistical Rigor**: Configure multiple iterations with consistent inputs to measure reliability and performance variance. This helps identify models that not only perform well but do so consistently across runs.
* **Real-World Validation**: Use your actual crew inputs and scenarios rather than synthetic benchmarks. The platform allows you to test with your specific industry context, company information, and real use cases for more accurate evaluation.
* **Comprehensive Analytics**: Access detailed performance metrics, execution times, and cost analysis across all tested models. This enables data-driven decision making rather than relying on general model reputation or theoretical capabilities.
* **Team Collaboration**: Share testing results and model performance data across your team, enabling collaborative decision-making and consistent model selection strategies across projects.
Go to [app.crewai.com](https://app.crewai.com) to get started!
**Checkout:** [View the live trace example](https://app.langdb.ai/sharing/threads/3becbfed-a1be-ae84-ea3c-4942867a3e22)
## Features
### AI Gateway Capabilities
* **Access to 350+ LLMs**: Connect to all major language models through a single integration
* **Virtual Models**: Create custom model configurations with specific parameters and routing rules
* **Virtual MCP**: Enable compatibility and integration with MCP (Model Context Protocol) systems for enhanced agent communication
* **Guardrails**: Implement safety measures and compliance controls for agent behavior
### Observability & Tracing
* **Automatic Tracing**: Single `init()` call captures all CrewAI interactions
* **End-to-End Visibility**: Monitor agent workflows from start to finish
* **Tool Usage Tracking**: Track which tools agents use and their outcomes
* **Model Call Monitoring**: Detailed insights into LLM interactions
* **Performance Analytics**: Monitor latency, token usage, and costs
* **Debugging Support**: Step-through execution for troubleshooting
* **Real-time Monitoring**: Live traces and metrics dashboard
## Setup Instructions
### What You'll See
* **Agent Interactions**: Complete flow of agent conversations and task handoffs
* **Tool Usage**: Which tools were called, their inputs, and outputs
* **Model Calls**: Detailed LLM interactions with prompts image.pngand responses
* **Performance Metrics**: Latency, token usage, and cost tracking
* **Execution Timeline**: Step-by-step view of the entire workflow
## Troubleshooting
### Common Issues
* **No traces appearing**: Ensure `init()` is called before any CrewAI imports
* **Authentication errors**: Verify your LangDB API key and project ID
## Resources
## Setup Instructions
Evaluate captured logs automatically from the UI based on filters and sampling
Use human evaluation or rating to assess the quality of your logs and evaluate them.
Evaluate any component of your trace or log to gain insights into your agent’s behavior.
## Troubleshooting
### Common Issues
* **No traces appearing**: Ensure your API key and repository ID are correct
* Ensure you've **`called instrument_crewai()`** ***before*** running your crew. This initializes logging hooks correctly.
* Set `debug=True` in your `instrument_crewai()` call to surface any internal errors:
```python
instrument_crewai(logger, debug=True)
```
* Configure your agents with `verbose=True` to capture detailed logs:
```python
agent = CrewAgent(..., verbose=True)
```
* Double-check that `instrument_crewai()` is called **before** creating or executing agents. This might be obvious, but it's a common oversight.
## Resources
### Features
* **Tracing Dashboard**: Monitor activities of your crewAI agents with detailed dashboards that include inputs, outputs and metadata of spans.
* **Automated Tracing**: A fully automated integration with crewAI, which can be enabled by running `mlflow.crewai.autolog()`.
* **Manual Trace Instrumentation with minor efforts**: Customize trace instrumentation through MLflow's high-level fluent APIs such as decorators, function wrappers and context managers.
* **OpenTelemetry Compatibility**: MLflow Tracing supports exporting traces to an OpenTelemetry Collector, which can then be used to export traces to various backends such as Jaeger, Zipkin, and AWS X-Ray.
* **Package and Deploy Agents**: Package and deploy your crewAI agents to an inference server with a variety of deployment targets.
* **Securely Host LLMs**: Host multiple LLM from various providers in one unified endpoint through MFflow gateway.
* **Evaluation**: Evaluate your crewAI agents with a wide range of metrics using a convenient API `mlflow.evaluate()`.
## Setup Instructions
The best UX to view a CrewAI trace. Post comments anywhere you want. Use AI to debug.
## Core Features
* **Trace Viewer**: Track thoughts, tools, and decisions in sequence
* **Inline Comments**: Tag teammates on any trace step
* **Feedback & Evaluation**: Mark outputs as correct or incorrect
* **Error Highlighting**: Automatic flagging of API/tool failures
* **Task Conversion**: Convert comments into assigned tasks
* **Ask the Trace (AI)**: Chat with your trace using Neatlogs AI bot
* **Public Sharing**: Publish trace links to your community
## Quick Setup with CrewAI
### Features
* **Analytics Dashboard**: Monitor your Agents health and performance with detailed dashboards that track metrics, costs, and user interactions.
* **OpenTelemetry-native Observability SDK**: Vendor-neutral SDKs to send traces and metrics to your existing observability tools like Grafana, DataDog and more.
* **Cost Tracking for Custom and Fine-Tuned Models**: Tailor cost estimations for specific models using custom pricing files for precise budgeting.
* **Exceptions Monitoring Dashboard**: Quickly spot and resolve issues by tracking common exceptions and errors with a monitoring dashboard.
* **Compliance and Security**: Detect potential threats such as profanity and PII leaks.
* **Prompt Injection Detection**: Identify potential code injection and secret leaks.
* **API Keys and Secrets Management**: Securely handle your LLM API keys and secrets centrally, avoiding insecure practices.
* **Prompt Management**: Manage and version Agent prompts using PromptHub for consistent and easy access across Agents.
* **Model Playground** Test and compare different models for your CrewAI agents before deployment.
## Setup Instructions
Opik provides comprehensive support for every stage of your CrewAI application development:
* **Log Traces and Spans**: Automatically track LLM calls and application logic to debug and analyze development and production systems. Manually or programmatically annotate, view, and compare responses across projects.
* **Evaluate Your LLM Application's Performance**: Evaluate against a custom test set and run built-in evaluation metrics or define your own metrics in the SDK or UI.
* **Test Within Your CI/CD Pipeline**: Establish reliable performance baselines with Opik's LLM unit tests, built on PyTest. Run online evaluations for continuous monitoring in production.
* **Monitor & Analyze Production Data**: Understand your models' performance on unseen data in production and generate datasets for new dev iterations.
## Setup
Comet provides a hosted version of the Opik platform, or you can run the platform locally.
To use the hosted version, simply [create a free Comet account](https://www.comet.com/signup?utm_medium=github\&utm_source=crewai_docs) and grab you API Key.
To run the Opik platform locally, see our [installation guide](https://www.comet.com/docs/opik/self-host/overview/) for more information.
For this guide we will use CrewAI’s quickstart example.
## Introduction
Portkey enhances CrewAI with production-readiness features, turning your experimental agent crews into robust systems by providing:
* **Complete observability** of every agent step, tool use, and interaction
* **Built-in reliability** with fallbacks, retries, and load balancing
* **Cost tracking and optimization** to manage your AI spend
* **Access to 200+ LLMs** through a single integration
* **Guardrails** to keep agent behavior safe and compliant
* **Version-controlled prompts** for consistent agent performance
### Installation & Setup
Traces provide a hierarchical view of your crew's execution, showing the sequence of LLM calls, tool invocations, and state transitions.
```python
# Add trace_id to enable hierarchical tracing in Portkey
portkey_llm = LLM(
model="gpt-4o",
base_url=PORTKEY_GATEWAY_URL,
api_key="dummy",
extra_headers=createHeaders(
api_key="YOUR_PORTKEY_API_KEY",
virtual_key="YOUR_OPENAI_VIRTUAL_KEY",
trace_id="unique-session-id" # Add unique trace ID
)
)
```
Portkey logs every interaction with LLMs, including:
* Complete request and response payloads
* Latency and token usage metrics
* Cost calculations
* Tool calls and function executions
All logs can be filtered by metadata, trace IDs, models, and more, making it easy to debug specific crew runs.
Portkey provides built-in dashboards that help you:
* Track cost and token usage across all crew runs
* Analyze performance metrics like latency and success rates
* Identify bottlenecks in your agent workflows
* Compare different crew configurations and LLMs
You can filter and segment all metrics by custom metadata to analyze specific crew types, user groups, or use cases.
Add custom metadata to your CrewAI LLM configuration to enable powerful filtering and segmentation:
```python
portkey_llm = LLM(
model="gpt-4o",
base_url=PORTKEY_GATEWAY_URL,
api_key="dummy",
extra_headers=createHeaders(
api_key="YOUR_PORTKEY_API_KEY",
virtual_key="YOUR_OPENAI_VIRTUAL_KEY",
metadata={
"crew_type": "research_crew",
"environment": "production",
"_user": "user_123", # Special _user field for user analytics
"request_source": "mobile_app"
}
)
)
```
This metadata can be used to filter logs, traces, and metrics on the Portkey dashboard, allowing you to analyze specific crew runs, users, or environments.
This enables:
* Per-user cost tracking and budgeting
* Personalized user analytics
* Team or organization-level metrics
* Environment-specific monitoring (staging vs. production)
Official CrewAI documentation
Get personalized guidance on implementing this integration
```python
from crewai import LLM
# Create an LLM instance with TrueFoundry AI Gateway
truefoundry_llm = LLM(
model="openai-main/gpt-4o", # Similarly, you can call any model from any provider
base_url="your_truefoundry_gateway_base_url",
api_key="your_truefoundry_api_key"
)
# Use in your CrewAI agents
from crewai import Agent
@agent
def researcher(self) -> Agent:
return Agent(
config=self.agents_config['researcher'],
llm=truefoundry_llm,
verbose=True
)
```
With Truefoundry's AI gateway, you can monitor and analyze:
* **Performance Metrics**: Track key latency metrics like Request Latency, Time to First Token (TTFS), and Inter-Token Latency (ITL) with P99, P90, and P50 percentiles
* **Cost and Token Usage**: Gain visibility into your application's costs with detailed breakdowns of input/output tokens and the associated expenses for each model
* **Usage Patterns**: Understand how your application is being used with detailed analytics on user activity, model distribution, and team-based usage
* **Rate limit and Load balancing**: You can set up rate limiting, load balancing and fallback for your models
## Tracing
For a more detailed understanding on tracing, please see [getting-started-tracing](https://docs.truefoundry.com/docs/tracing/tracing-getting-started).For tracing, you can add the Traceloop SDK:
For tracing, you can add the Traceloop SDK:
```bash
pip install traceloop-sdk
```
```python
from traceloop.sdk import Traceloop
# Initialize enhanced tracing
Traceloop.init(
api_endpoint="https://your-truefoundry-endpoint/api/tracing",
headers={
"Authorization": f"Bearer {your_truefoundry_pat_token}",
"TFY-Tracing-Project": "your_project_name",
},
)
```
This provides additional trace correlation across your entire CrewAI workflow.
# Weave Integration
Source: https://docs.crewai.com/en/observability/weave
Learn how to use Weights & Biases (W&B) Weave to track, experiment with, evaluate, and improve your CrewAI applications.
# Weave Overview
[Weights & Biases (W\&B) Weave](https://weave-docs.wandb.ai/) is a framework for tracking, experimenting with, evaluating, deploying, and improving LLM-based applications.
Weave provides comprehensive support for every stage of your CrewAI application development:
* **Tracing & Monitoring**: Automatically track LLM calls and application logic to debug and analyze production systems
* **Systematic Iteration**: Refine and iterate on prompts, datasets, and models
* **Evaluation**: Use custom or pre-built scorers to systematically assess and enhance agent performance
* **Guardrails**: Protect your agents with pre- and post-safeguards for content moderation and prompt safety
Weave automatically captures traces for your CrewAI applications, enabling you to monitor and analyze your agents' performance, interactions, and execution flow. This helps you build better evaluation datasets and optimize your agent workflows.
## Setup Instructions
Orchestrate multi‑agent systems and flows with guardrails, memory, knowledge, tools, and observability. Production‑ready by default.
시각적 에이전트 빌더를 통해 다음과 같은 기능을 사용할 수 있습니다:
* 폼 기반 인터페이스를 통한 직관적 에이전트 구성
* 실시간 테스트 및 검증
* 사전 구성된 에이전트 유형 템플릿 라이브러리
* 에이전트 속성 및 행동의 손쉬운 커스터마이즈
Prompt Tracing을 통해 다음과 같은 작업이 가능합니다:
* LLM에 전송된 모든 prompt의 전체 기록 보기
* token 사용량 및 비용 추적
* agent reasoning 실패 디버깅
* 팀 내에서 prompt 시퀀스 공유
* 다양한 prompt 전략 비교
* 컴플라이언스 및 감사를 위한 trace 내보내기
위 예제에서는 OpenAI를 사용하여 무작위 도시를 생성하고, 해당 도시에 대한 재미있는 사실을 생성하는 간단한 Flow를 만들었습니다. 이 Flow는 `generate_city`와 `generate_fun_fact`라는 두 가지 작업으로 구성되어 있습니다. `generate_city` 작업이 Flow의 시작점이며, `generate_fun_fact` 작업이 `generate_city` 작업의 출력을 감지합니다.
각 Flow 인스턴스는 상태(state)에 자동으로 고유 식별자(UUID)를 부여 받아, 흐름 실행을 추적하고 관리하는 데 도움이 됩니다. 상태에는 실행 중에 유지되는 추가 데이터(예: 생성된 도시와 재미있는 사실)도 저장할 수 있습니다.
Flow를 실행하면 다음과 같은 과정을 따릅니다:
1. 상태를 위한 고유 ID를 생성
2. 무작위 도시를 생성하여 상태에 저장
3. 해당 도시에 대한 재미있는 사실을 생성하여 상태에 저장
4. 결과를 콘솔에 출력
상태의 고유 ID와 저장된 데이터는 흐름 실행을 추적하고, 작업 간의 컨텍스트를 유지하는 데 유용합니다.
**참고:** OpenAI API 요청 인증을 위해 `OPENAI_API_KEY`를 `.env` 파일에 설정해야 합니다. 이 키는 필수입니다.
### @start()
`@start()` 데코레이터는 메서드를 Flow의 시작 지점으로 표시하는 데 사용됩니다. Flow가 시작되면 `@start()`로 데코레이트된 모든 메서드가 병렬로 실행됩니다. 하나의 Flow에서 여러 개의 start 메서드를 가질 수 있으며, Flow가 시작될 때 이들은 모두 실행됩니다.
### @listen()
`@listen()` 데코레이터는 Flow 내에서 다른 태스크의 출력을 수신하는 리스너로 메서드를 표시하는 데 사용됩니다. `@listen()`으로 데코레이션된 메서드는 지정된 태스크가 출력을 내보낼 때 실행됩니다. 이 메서드는 자신이 리스닝하고 있는 태스크의 출력을 인자로 접근할 수 있습니다.
#### 사용법
`@listen()` 데코레이터는 여러 가지 방법으로 사용할 수 있습니다:
1. **메서드 이름으로 리스닝하기**: 리스닝하고자 하는 메서드의 이름을 문자열로 전달할 수 있습니다. 해당 메서드가 완료되면, 리스너 메서드가 트리거됩니다.
```python Code
@listen("generate_city")
def generate_fun_fact(self, random_city):
# Implementation
```
2. **메서드 자체로 리스닝하기**: 메서드 자체를 전달할 수도 있습니다. 해당 메서드가 완료되면, 리스너 메서드가 트리거됩니다.
```python Code
@listen(generate_city)
def generate_fun_fact(self, random_city):
# Implementation
```
### Flow 출력
Flow의 출력을 접근하고 다루는 것은 AI 워크플로우를 더 큰 애플리케이션이나 시스템에 통합하는 데 필수적입니다. CrewAI Flow는 최종 출력물을 쉽게 가져오고, 중간 결과에 접근하며, Flow의 전체 상태를 관리할 수 있는 직관적인 메커니즘을 제공합니다.
#### 최종 출력값 가져오기
Flow를 실행하면, 최종 출력값은 마지막으로 완료된 메서드에 의해 결정됩니다. `kickoff()` 메서드는 이 마지막 메서드의 결과를 반환합니다.
최종 출력값을 확인하는 방법은 다음과 같습니다:
이 예제에서 `second_method`가 마지막으로 완료된 메서드이므로, 해당 메서드의 결과가 Flow의 최종 출력값이 됩니다.\
`kickoff()` 메서드는 이 최종 출력값을 반환하며, 이 값은 콘솔에 출력됩니다.\
`plot()` 메서드는 HTML 파일을 생성하며, 이를 통해 flow를 쉽게 이해할 수 있습니다.
#### 상태에 접근하고 업데이트하기
최종 출력을 가져오는 것 외에도, Flow 내에서 상태(state)에 접근하고 업데이트할 수 있습니다. 상태는 Flow의 다양한 메소드 간 데이터를 저장하고 공유하는 데 사용할 수 있습니다. Flow가 실행된 후에는, 실행 중에 추가되거나 업데이트된 정보를 조회하기 위해 상태에 접근할 수 있습니다.
다음은 상태를 업데이트하고 접근하는 방법의 예시입니다:
이 예시에서 상태는 `first_method`와 `second_method` 모두에 의해 업데이트됩니다.
Flow가 실행된 후, 이러한 메소드들에 의해 수행된 업데이트 내용을 확인하려면 최종 상태에 접근할 수 있습니다.
최종 메소드의 출력이 반환되고 상태에 접근할 수 있도록 함으로써, CrewAI Flow는 AI 워크플로우의 결과를 더 큰 애플리케이션이나 시스템에 쉽게 통합할 수 있게 하며,
Flow 실행 과정 전반에 걸쳐 상태를 유지하고 접근하면서도 이를 용이하게 만듭니다.
## 플로우 상태 관리
상태를 효과적으로 관리하는 것은 신뢰할 수 있고 유지 보수가 용이한 AI 워크플로를 구축하는 데 매우 중요합니다. CrewAI 플로우는 비정형 및 정형 상태 관리를 위한 강력한 메커니즘을 제공하여, 개발자가 자신의 애플리케이션에 가장 적합한 접근 방식을 선택할 수 있도록 합니다.
### 비구조적 상태 관리
비구조적 상태 관리에서는 모든 상태가 `Flow` 클래스의 `state` 속성에 저장됩니다.\
이 방식은 엄격한 스키마를 정의하지 않고도 개발자가 상태 속성을 즉석에서 추가하거나 수정할 수 있는 유연성을 제공합니다.\
비구조적 상태에서도 CrewAI Flows는 각 상태 인스턴스에 대한 고유 식별자(UUID)를 자동으로 생성하고 유지합니다.
```python Code
from crewai.flow.flow import Flow, listen, start
class UnstructuredExampleFlow(Flow):
@start()
def first_method(self):
# The state automatically includes an 'id' field
print(f"State ID: {self.state['id']}")
self.state['counter'] = 0
self.state['message'] = "Hello from structured flow"
@listen(first_method)
def second_method(self):
self.state['counter'] += 1
self.state['message'] += " - updated"
@listen(second_method)
def third_method(self):
self.state['counter'] += 1
self.state['message'] += " - updated again"
print(f"State after third_method: {self.state}")
flow = UnstructuredExampleFlow()
flow.plot("my_flow_plot")
flow.kickoff()
```
**참고:** `id` 필드는 흐름의 실행 전체에 걸쳐 자동으로 생성되어 보존됩니다. 이를 직접 관리하거나 설정할 필요가 없으며, 새로운 데이터로 상태를 업데이트할 때도 자동으로 유지됩니다.
**핵심 포인트:**
* **유연성:** `self.state`에 미리 정해진 제약 없이 속성을 동적으로 추가할 수 있습니다.
* **단순성:** 상태 구조가 최소이거나 크게 달라지는 단순한 워크플로우에 이상적입니다.
### 구조화된 상태 관리
구조화된 상태 관리는 미리 정의된 스키마를 활용하여 워크플로 전반에 걸쳐 일관성과 타입 안전성을 보장합니다. Pydantic의 `BaseModel`과 같은 모델을 사용하면 상태의 정확한 형태를 정의할 수 있어, 개발 환경에서 더 나은 검증 및 자동 완성이 가능합니다.
CrewAI Flows의 각 상태는 인스턴스 추적 및 관리를 돕기 위해 자동으로 고유 식별자(UUID)를 할당받습니다. 이 ID는 Flow 시스템에 의해 자동으로 생성되고 관리됩니다.
```python Code
from crewai.flow.flow import Flow, listen, start
from pydantic import BaseModel
class ExampleState(BaseModel):
# Note: 'id' field is automatically added to all states
counter: int = 0
message: str = ""
class StructuredExampleFlow(Flow[ExampleState]):
@start()
def first_method(self):
# Access the auto-generated ID if needed
print(f"State ID: {self.state.id}")
self.state.message = "Hello from structured flow"
@listen(first_method)
def second_method(self):
self.state.counter += 1
self.state.message += " - updated"
@listen(second_method)
def third_method(self):
self.state.counter += 1
self.state.message += " - updated again"
print(f"State after third_method: {self.state}")
flow = StructuredExampleFlow()
flow.kickoff()
```
**핵심 포인트:**
* **정의된 스키마:** `ExampleState`는 상태 구조를 명확히 정의하여 코드 가독성과 유지보수성을 향상시킵니다.
* **타입 안전성:** Pydantic을 활용하면 상태의 속성이 지정된 타입을 준수하도록 보장하여 런타임 오류를 줄일 수 있습니다.
* **자동 완성:** IDE에서 정의된 상태 모델을 기반으로 더 나은 자동 완성과 오류 확인이 가능합니다.
### 비구조적 상태 관리와 구조적 상태 관리 선택하기
* **비구조적 상태 관리를 사용할 때:**
* 워크플로의 상태가 단순하거나 매우 동적일 때.
* 엄격한 상태 정의보다 유연성이 우선시될 때.
* 스키마 정의의 오버헤드 없이 빠른 프로토타이핑이 필요할 때.
* **구조적 상태 관리를 사용할 때:**
* 워크플로에 잘 정의되고 일관된 상태 구조가 필요할 때.
* 애플리케이션의 신뢰성을 위해 타입 안전성과 검증이 중요할 때.
* 더 나은 개발자 경험을 위해 IDE의 자동 완성 및 타입 체크 기능을 활용하고자 할 때.
CrewAI Flows는 비구조적 및 구조적 상태 관리 옵션을 모두 제공함으로써, 개발자들이 다양한 애플리케이션 요구 사항에 맞춰 유연하면서도 견고한 AI 워크플로를 구축할 수 있도록 지원합니다.
## 플로우 지속성
@persist 데코레이터는 CrewAI 플로우에서 자동 상태 지속성을 활성화하여, 플로우 상태를 재시작이나 다른 워크플로우 실행 간에도 유지할 수 있도록 합니다. 이 데코레이터는 클래스 수준이나 메서드 수준 모두에 적용할 수 있어, 상태 지속성을 관리하는 데 유연성을 제공합니다.
### 클래스 레벨 영속성
클래스 레벨에서 @persist 데코레이터를 적용하면 모든 flow 메서드 상태가 자동으로 영속됩니다:
```python
@persist # 기본적으로 SQLiteFlowPersistence 사용
class MyFlow(Flow[MyState]):
@start()
def initialize_flow(self):
# 이 메서드는 상태가 자동으로 영속됩니다
self.state.counter = 1
print("Initialized flow. State ID:", self.state.id)
@listen(initialize_flow)
def next_step(self):
# 상태(self.state.id 포함)는 자동으로 다시 로드됩니다
self.state.counter += 1
print("Flow state is persisted. Counter:", self.state.counter)
```
### 메서드 수준의 지속성
더 세밀한 제어를 위해, @persist를 특정 메서드에 적용할 수 있습니다:
```python
class AnotherFlow(Flow[dict]):
@persist # Persists only this method's state
@start()
def begin(self):
if "runs" not in self.state:
self.state["runs"] = 0
self.state["runs"] += 1
print("Method-level persisted runs:", self.state["runs"])
```
### 작동 방식
1. **고유 상태 식별**
* 각 flow 상태에는 자동으로 고유한 UUID가 할당됩니다.
* 이 ID는 상태 업데이트 및 메소드 호출 시에도 유지됩니다.
* 구조화된 상태(Pydantic BaseModel)와 비구조화된 상태(딕셔너리) 모두를 지원합니다.
2. **기본 SQLite 백엔드**
* SQLiteFlowPersistence는 기본 저장 백엔드입니다.
* 상태는 자동으로 로컬 SQLite 데이터베이스에 저장됩니다.
* 데이터베이스 작업 실패 시 명확한 메시지를 제공하는 견고한 오류 처리가 제공됩니다.
3. **오류 처리**
* 데이터베이스 작업에 대한 포괄적인 오류 메시지가 제공됩니다.
* 저장 및 로드 중에 상태가 자동으로 검증됩니다.
* 지속성 작업에 문제가 발생할 경우 명확한 피드백을 제공합니다.
### 중요한 고려사항
* **상태 유형**: 구조화된(Pydantic BaseModel) 상태와 비구조화된(딕셔너리) 상태 모두 지원됩니다
* **자동 ID**: `id` 필드는 존재하지 않을 경우 자동으로 추가됩니다
* **상태 복구**: 실패하거나 재시작된 flow는 이전 상태를 자동으로 불러올 수 있습니다
* **커스텀 구현**: 특수한 저장소 요구 사항을 위해 직접 FlowPersistence 구현을 제공할 수 있습니다
### 기술적 이점
1. **저수준 접근을 통한 정밀한 제어**
* 고급 사용 사례를 위한 영속성 작업에 대한 직접 접근
* 메서드 수준의 영속성 데코레이터를 통한 세밀한 제어
* 내장된 상태 검사 및 디버깅 기능
* 상태 변경 및 영속성 작업에 대한 완전한 가시성
2. **향상된 신뢰성**
* 시스템 장애 또는 재시작 후 자동 상태 복구
* 데이터 무결성을 위한 트랜잭션 기반 상태 업데이트
* 명확한 오류 메시지를 제공하는 포괄적인 오류 처리
* 상태 저장 및 로드 작업 시 강력한 검증
3. **확장 가능한 아키텍처**
* FlowPersistence 인터페이스를 통한 사용자 정의 가능한 영속성 백엔드
* SQLite를 넘어선 특수 저장 솔루션 지원
* 구조화된(Pydantic) 상태와 비구조화(dict) 상태 모두와 호환
* 기존 CrewAI 흐름 패턴과의 원활한 통합
영속성 시스템의 아키텍처는 기술적 정밀성과 맞춤화 옵션을 강조하여, 개발자가 내장된 신뢰성 기능의 이점을 누리면서 상태 관리에 대한 완전한 제어권을 유지할 수 있게 해줍니다.
## 흐름 제어
### 조건부 로직: `or`
Flows에서 `or_` 함수는 여러 메서드를 감지하고 지정된 메서드 중 하나에서 출력이 발생하면 리스너 메서드를 트리거합니다.
이 Flow를 실행하면, `logger` 메서드는 `start_method` 또는 `second_method`의 출력에 의해 트리거됩니다.\
`or_` 함수는 여러 메서드를 감지하고 지정된 메서드 중 하나에서 출력이 발생하면 리스너 메서드를 트리거하는 데 사용됩니다.
### 조건부 로직: `and`
Flows에서 `and_` 함수는 여러 메서드를 리슨하고, 지정된 모든 메서드가 출력을 발생시킬 때만 리스너 메서드가 트리거되도록 합니다.
이 Flow를 실행하면, `logger` 메서드는 `start_method`와 `second_method`가 모두 출력을 발생시켰을 때만 트리거됩니다.\
`and_` 함수는 여러 메서드를 리슨하고, 지정된 모든 메서드가 출력을 발생시킬 때만 리스너 메서드를 트리거하는 데 사용됩니다.
### Router
Flows의 `@router()` 데코레이터를 사용하면 메서드의 출력값에 따라 조건부 라우팅 로직을 정의할 수 있습니다.\
메서드의 출력에 따라 서로 다른 경로를 지정할 수 있어 실행 흐름을 동적으로 제어할 수 있습니다.
위 예제에서 `start_method`는 랜덤 불리언 값을 생성하여 state에 저장합니다.\
`second_method`는 `@router()` 데코레이터를 사용해 불리언 값에 따라 조건부 라우팅 로직을 정의합니다.\
불리언 값이 `True`이면 메서드는 `"success"`를 반환하고, `False`이면 `"failed"`를 반환합니다.\
`third_method`와 `fourth_method`는 `second_method`의 출력값을 기다렸다가 반환된 값에 따라 실행됩니다.
이 Flow를 실행하면, `start_method`에서 생성된 랜덤 불리언 값에 따라 출력값이 달라집니다.
## 플로우에 에이전트 추가하기
에이전트는 플로우에 원활하게 통합할 수 있으며, 단순하고 집중된 작업 실행이 필요할 때 전체 Crew의 경량 대안으로 활용됩니다. 아래는 에이전트를 플로우 내에서 사용하여 시장 조사를 수행하는 예시입니다:
```python
import asyncio
from typing import Any, Dict, List
from crewai_tools import SerperDevTool
from pydantic import BaseModel, Field
from crewai.agent import Agent
from crewai.flow.flow import Flow, listen, start
# Define a structured output format
class MarketAnalysis(BaseModel):
key_trends: List[str] = Field(description="List of identified market trends")
market_size: str = Field(description="Estimated market size")
competitors: List[str] = Field(description="Major competitors in the space")
# Define flow state
class MarketResearchState(BaseModel):
product: str = ""
analysis: MarketAnalysis | None = None
# Create a flow class
class MarketResearchFlow(Flow[MarketResearchState]):
@start()
def initialize_research(self) -> Dict[str, Any]:
print(f"Starting market research for {self.state.product}")
return {"product": self.state.product}
@listen(initialize_research)
async def analyze_market(self) -> Dict[str, Any]:
# Create an Agent for market research
analyst = Agent(
role="Market Research Analyst",
goal=f"Analyze the market for {self.state.product}",
backstory="You are an experienced market analyst with expertise in "
"identifying market trends and opportunities.",
tools=[SerperDevTool()],
verbose=True,
)
# Define the research query
query = f"""
Research the market for {self.state.product}. Include:
1. Key market trends
2. Market size
3. Major competitors
Format your response according to the specified structure.
"""
# Execute the analysis with structured output format
result = await analyst.kickoff_async(query, response_format=MarketAnalysis)
if result.pydantic:
print("result", result.pydantic)
else:
print("result", result)
# Return the analysis to update the state
return {"analysis": result.pydantic}
@listen(analyze_market)
def present_results(self, analysis) -> None:
print("\nMarket Analysis Results")
print("=====================")
if isinstance(analysis, dict):
# If we got a dict with 'analysis' key, extract the actual analysis object
market_analysis = analysis.get("analysis")
else:
market_analysis = analysis
if market_analysis and isinstance(market_analysis, MarketAnalysis):
print("\nKey Market Trends:")
for trend in market_analysis.key_trends:
print(f"- {trend}")
print(f"\nMarket Size: {market_analysis.market_size}")
print("\nMajor Competitors:")
for competitor in market_analysis.competitors:
print(f"- {competitor}")
else:
print("No structured analysis data available.")
print("Raw analysis:", analysis)
# Usage example
async def run_flow():
flow = MarketResearchFlow()
flow.plot("MarketResearchFlowPlot")
result = await flow.kickoff_async(inputs={"product": "AI-powered chatbots"})
return result
# Run the flow
if __name__ == "__main__":
asyncio.run(run_flow())
```
이 예시는 플로우에서 에이전트를 사용할 때의 몇 가지 주요 기능을 보여줍니다:
1. **구조화된 출력**: Pydantic 모델을 사용하여 예상 출력 형식(`MarketAnalysis`)을 정의함으로써 플로우 전체에서 타입 안정성과 구조화된 데이터를 보장합니다.
2. **상태 관리**: 플로우 상태(`MarketResearchState`)는 단계 간의 컨텍스트를 유지하고 입력과 출력을 모두 저장합니다.
3. **도구 통합**: 에이전트는 기능 강화를 위해 `WebsiteSearchTool`과 같은 도구를 사용할 수 있습니다.
## Flows에 Crews 추가하기
CrewAI에서 여러 crews로 flow를 생성하는 것은 간단합니다.
다음 명령어를 실행하여 여러 crews가 포함된 flow를 생성하는 데 필요한 모든 스캐폴딩이 포함된 새 CrewAI 프로젝트를 생성할 수 있습니다.
```bash
crewai create flow name_of_flow
```
이 명령어는 필요한 폴더 구조를 갖춘 새 CrewAI 프로젝트를 생성합니다. 생성된 프로젝트에는 이미 동작 중인 미리 구축된 crew인 `poem_crew`가 포함되어 있습니다. 이 crew를 템플릿으로 사용하여 복사, 붙여넣기, 수정함으로써 다른 crew를 만들 수 있습니다.
### 폴더 구조
`crewai create flow name_of_flow` 명령을 실행하면 다음과 유사한 폴더 구조를 볼 수 있습니다:
| 디렉터리/파일 | 설명 |
| :--------------------- | :------------------------------------ |
| `name_of_flow/` | flow의 루트 디렉터리입니다. |
| ├── `crews/` | 특정 crew에 대한 디렉터리를 포함합니다. |
| │ └── `poem_crew/` | "poem\_crew"의 설정 및 스크립트가 포함된 디렉터리입니다. |
| │ ├── `config/` | "poem\_crew"의 설정 파일 디렉터리입니다. |
| │ │ ├── `agents.yaml` | "poem\_crew"의 agent를 정의하는 YAML 파일입니다. |
| │ │ └── `tasks.yaml` | "poem\_crew"의 task를 정의하는 YAML 파일입니다. |
| │ ├── `poem_crew.py` | "poem\_crew"의 기능을 위한 스크립트입니다. |
| ├── `tools/` | flow에서 사용되는 추가 도구를 위한 디렉터리입니다. |
| │ └── `custom_tool.py` | 사용자 정의 도구 구현 파일입니다. |
| ├── `main.py` | flow를 실행하는 메인 스크립트입니다. |
| ├── `README.md` | 프로젝트 설명 및 안내 문서입니다. |
| ├── `pyproject.toml` | 프로젝트의 종속성 및 설정을 위한 구성 파일입니다. |
| └── `.gitignore` | 버전 관리에서 무시할 파일과 디렉터리를 지정합니다. |
### 크루 빌드하기
`crews` 폴더에서는 여러 개의 크루를 정의할 수 있습니다. 각 크루는 자체 폴더를 가지며, 설정 파일과 크루 정의 파일을 포함합니다. 예를 들어, `poem_crew` 폴더에는 다음과 같은 파일이 있습니다:
* `config/agents.yaml`: 크루의 agent를 정의합니다.
* `config/tasks.yaml`: 크루의 task를 정의합니다.
* `poem_crew.py`: agent, task, 그리고 크루 자체를 포함한 crew 정의가 들어 있습니다.
`poem_crew`를 복사, 붙여넣기, 그리고 편집하여 다른 크루를 생성할 수 있습니다.
### `main.py`에서 Crew 연결하기
`main.py` 파일은 flow를 생성하고 crew들을 서로 연결하는 곳입니다. `Flow` 클래스를 사용하고, `@start`와 `@listen` 데코레이터를 사용하여 실행 흐름을 지정하여 flow를 정의할 수 있습니다.
다음은 `main.py` 파일에서 `poem_crew`를 연결하는 예제입니다:
```python Code
#!/usr/bin/env python
from random import randint
from pydantic import BaseModel
from crewai.flow.flow import Flow, listen, start
from .crews.poem_crew.poem_crew import PoemCrew
class PoemState(BaseModel):
sentence_count: int = 1
poem: str = ""
class PoemFlow(Flow[PoemState]):
@start()
def generate_sentence_count(self):
print("Generating sentence count")
self.state.sentence_count = randint(1, 5)
@listen(generate_sentence_count)
def generate_poem(self):
print("Generating poem")
result = PoemCrew().crew().kickoff(inputs={"sentence_count": self.state.sentence_count})
print("Poem generated", result.raw)
self.state.poem = result.raw
@listen(generate_poem)
def save_poem(self):
print("Saving poem")
with open("poem.txt", "w") as f:
f.write(self.state.poem)
def kickoff():
poem_flow = PoemFlow()
poem_flow.kickoff()
def plot():
poem_flow = PoemFlow()
poem_flow.plot("PoemFlowPlot")
if __name__ == "__main__":
kickoff()
plot()
```
이 예제에서 `PoemFlow` 클래스는 문장 수를 생성하고, `PoemCrew`를 사용하여 시를 생성한 후, 시를 파일에 저장하는 flow를 정의합니다. 이 flow는 `kickoff()` 메서드를 호출하여 시작됩니다. `plot()` 메서드로 PoemFlowPlot이 생성됩니다.
### 플로우 실행하기
(선택 사항) 플로우를 실행하기 전에, 다음 명령어를 실행하여 의존성을 설치할 수 있습니다:
```bash
crewai install
```
모든 의존성이 설치되면, 다음 명령어를 실행하여 가상 환경을 활성화해야 합니다:
```bash
source .venv/bin/activate
```
가상 환경을 활성화한 후, 아래 명령어 중 하나를 실행하여 플로우를 실행할 수 있습니다:
```bash
crewai flow kickoff
```
또는
```bash
uv run kickoff
```
플로우가 실행되면, 콘솔에서 출력을 확인할 수 있습니다.
## 플롯 플로우
AI 워크플로우를 시각화하면 플로우의 구조와 실행 경로에 대한 중요한 인사이트를 얻을 수 있습니다. CrewAI는 플로우의 인터랙티브 플롯을 생성할 수 있는 강력한 시각화 도구를 제공하여 AI 워크플로우를 보다 쉽게 이해하고 최적화할 수 있도록 도와줍니다.
### 플롯(Plots)이란 무엇인가요?
CrewAI에서 플롯(Plots)은 AI 워크플로우의 그래픽 표현입니다. 플롯은 다양한 태스크와 그들의 연결, 그리고 태스크 간 데이터 흐름을 시각적으로 보여줍니다. 이러한 시각화는 작업 순서를 이해하고, 병목 현상을 식별하며, 워크플로우 논리가 기대에 부합하는지 확인하는 데 도움이 됩니다.
### 플롯 생성 방법
CrewAI는 플로우의 플롯을 생성하는 두 가지 편리한 방법을 제공합니다:
#### 옵션 1: `plot()` 메서드 사용하기
flow 인스턴스와 직접 작업하는 경우, flow 객체에서 `plot()` 메서드를 호출하여 플롯을 생성할 수 있습니다. 이 메서드는 flow의 인터랙티브 플롯이 포함된 HTML 파일을 생성합니다.
```python Code
# Assuming you have a flow instance
flow.plot("my_flow_plot")
```
이렇게 하면 현재 디렉토리에 `my_flow_plot.html`이라는 파일이 생성됩니다. 이 파일을 웹 브라우저에서 열어 인터랙티브 플롯을 볼 수 있습니다.
#### 옵션 2: 커맨드 라인 사용
구조화된 CrewAI 프로젝트 내에서 작업 중이라면 커맨드 라인을 사용하여 플롯을 생성할 수 있습니다. 이는 전체 플로우 설정을 시각화하고자 하는 대규모 프로젝트에서 특히 유용합니다.
```bash
crewai flow plot
```
이 명령은 플로우의 플롯이 포함된 HTML 파일을 생성하며, 이는 `plot()` 메서드와 유사합니다. 파일은 프로젝트 디렉터리에 저장되며, 웹 브라우저에서 열어 플로우를 탐색할 수 있습니다.
### 플롯 이해하기
생성된 플롯은 flow 내의 작업을 나타내는 노드와 실행 흐름을 나타내는 방향성이 있는 엣지를 표시합니다. 플롯은 인터랙티브하게 제공되어, 확대/축소를 하거나 노드 위에 마우스를 올려 추가 정보를 볼 수 있습니다.
flow를 시각화하면 워크플로의 구조를 더욱 명확하게 이해할 수 있어 디버깅, 최적화, 그리고 AI 프로세스를 다른 사람들에게 설명하는 데 도움이 됩니다.
### 결론
플로우를 시각적으로 표현하는 것은 CrewAI의 강력한 기능으로, 복잡한 AI 워크플로우를 설계하고 관리하는 능력을 크게 향상시켜줍니다. `plot()` 메서드나 커맨드 라인 중 어떤 방법을 사용하더라도, 플롯을 생성하면 워크플로우의 시각적 표현을 얻을 수 있어 개발과 발표 모두에 도움이 됩니다.
## 다음 단계
추가적인 flow 예제를 살펴보고 싶으시다면, 저희 examples 레포지토리에서 다양한 추천 예제를 확인하실 수 있습니다. 아래는 각각 고유한 사용 사례를 보여주는 네 가지 구체적인 flow 예제로, 현재 문제 유형에 맞는 예시를 찾는 데 도움이 될 것입니다:
1. **이메일 자동 응답자 Flow**: 이 예제는 백그라운드 작업이 계속 실행되면서 이메일 응답을 자동화하는 무한 루프를 보여줍니다. 수동 개입 없이 반복적으로 수행해야 하는 작업에 적합한 사용 사례입니다. [예제 보기](https://github.com/crewAIInc/crewAI-examples/tree/main/email_auto_responder_flow)
2. **리드 점수 Flow**: 이 flow 예제는 human-in-the-loop 피드백을 추가하고 router를 사용하여 다양한 조건 분기를 처리하는 방법을 보여줍니다. 워크플로우에 동적 의사결정과 인간의 관리·감독을 통합하는 방식을 확인할 수 있는 훌륭한 예시입니다. [예제 보기](https://github.com/crewAIInc/crewAI-examples/tree/main/lead-score-flow)
3. **책 집필 Flow**: 이 예제는 여러 crew를 연속적으로 연결하는 데 탁월하며, 한 crew의 출력 결과가 다른 crew에 의해 사용됩니다. 구체적으로, 한 crew가 전체 책의 개요를 작성하고, 다른 crew가 그 개요를 바탕으로 챕터를 생성합니다. 결국 모든 것이 연결되어 완성된 책이 만들어집니다. 여러 작업 간 조율이 필요한 복잡한 다단계 프로세스에 적합한 flow입니다. [예제 보기](https://github.com/crewAIInc/crewAI-examples/tree/main/write_a_book_with_flows)
4. **미팅 어시스턴트 Flow**: 이 flow는 하나의 이벤트가 여러 후속 작업을 트리거하도록 브로드캐스트하는 방법을 보여줍니다. 예를 들어, 미팅이 끝난 후 Trello 보드를 업데이트하고 Slack 메시지를 전송하며 결과를 저장할 수 있습니다. 하나의 이벤트로부터 여러 결과를 처리하는 좋은 예시로, 포괄적인 작업 관리 및 알림 시스템에 이상적입니다. [예제 보기](https://github.com/crewAIInc/crewAI-examples/tree/main/meeting_assistant_flow)
이 예제들을 통해 반복되는 작업 자동화부터 동적 의사결정과 인간 피드백이 포함된 복잡한 다단계 프로세스 관리에 이르기까지 다양한 사용 사례에서 CrewAI Flows를 어떻게 활용할 수 있는지에 대한 통찰력을 얻을 수 있습니다.
또한, 아래의 CrewAI에서 flows를 사용하는 방법에 대한 YouTube 영상을 확인해보세요!
## 플로우 실행하기
플로우를 실행하는 방법에는 두 가지가 있습니다:
### Flow API 사용하기
플로우를 프로그래밍 방식으로 실행하려면, 플로우 클래스의 인스턴스를 생성하고 `kickoff()` 메서드를 호출하면 됩니다:
```python
flow = ExampleFlow()
result = flow.kickoff()
```
### CLI 사용하기
버전 0.103.0부터 `crewai run` 명령어를 사용하여 flow를 실행할 수 있습니다:
```shell
crewai run
```
이 명령어는 프로젝트가 pyproject.toml의 `type = "flow"` 설정을 기반으로 flow인지 자동으로 감지하여 해당 방식으로 실행합니다. 명령줄에서 flow를 실행하는 권장 방법입니다.
하위 호환성을 위해 다음 명령어도 사용할 수 있습니다:
```shell
crewai flow kickoff
```
하지만 `crewai run` 명령어가 이제 crew와 flow 모두에 작동하므로 더욱 선호되는 방법입니다.
# Knowledge
Source: https://docs.crewai.com/ko/concepts/knowledge
CrewAI에서 knowledge란 무엇이며 어떻게 사용하는지 알아봅니다.
## 개요
Knowledge in CrewAI는 AI 에이전트가 작업 중에 외부 정보 소스에 접근하고 이를 활용할 수 있게 해주는 강력한 시스템입니다.
이는 에이전트에게 작업할 때 참고할 수 있는 참조 도서관을 제공하는 것과 같습니다.
stop 파라미터를 보낼 필요가 없다면 LLM 호출에서 제외할 수 있습니다:
```python
from crewai import LLM
import os
os.environ["OPENAI_API_KEY"] = "
비주얼 Task 빌더의 주요 기능:
* 드래그 앤 드롭 방식의 Task 생성
* 시각적 Task 종속성과 흐름 관리
* 실시간 테스트 및 검증
* 손쉬운 공유 및 협업
## 지원되는 통합
### **커뮤니케이션 & 협업**
* **Gmail** - 이메일 및 임시 저장 관리
* **Slack** - 워크스페이스 알림 및 경고
* **Microsoft** - Office 365 및 Teams 통합
### **프로젝트 관리**
* **Jira** - 이슈 추적 및 프로젝트 관리
* **ClickUp** - 작업 및 생산성 관리
* **Asana** - 팀 작업 및 프로젝트 조정
* **Notion** - 페이지 및 데이터베이스 관리
* **Linear** - 소프트웨어 프로젝트 및 버그 추적
* **GitHub** - 저장소 및 이슈 관리
### **고객 관계 관리**
* **Salesforce** - CRM 계정 및 기회 관리
* **HubSpot** - 영업 파이프라인 및 연락처 관리
* **Zendesk** - 고객 지원 티켓 관리
### **비즈니스 & 금융**
* **Stripe** - 결제 처리 및 고객 관리
* **Shopify** - 전자상거래 스토어 및 상품 관리
### **생산성 및 저장소**
* **Google Sheets** - 스프레드시트 데이터 동기화
* **Google Calendar** - 일정 및 스케줄 관리
* **Box** - 파일 저장 및 문서 관리
추가 기능도 곧 제공됩니다!
## 사전 준비 사항
Authentication Integrations를 사용하기 전에 다음이 준비되어 있는지 확인하세요:
* [CrewAI Enterprise](https://app.crewai.com) 계정. 무료 체험으로 시작할 수 있습니다.
## 통합 설정
### 1. 계정 연결하기
1. [CrewAI Enterprise](https://app.crewai.com)로 이동합니다.
2. **Integrations** 탭으로 이동합니다 - [https://app.crewai.com/crewai\_plus/connectors](https://app.crewai.com/crewai_plus/connectors)
3. Authentication Integrations 섹션에서 원하는 서비스의 **Connect** 버튼을 클릭합니다.
4. OAuth 인증 과정을 완료합니다.
5. 사용 사례에 필요한 권한을 부여합니다.
6. 완료! [CrewAI Enterprise](https://app.crewai.com)의 **Integration** 탭에서 Enterprise Token을 받습니다.
### 2. 통합 도구 설치
최신 버전의 `crewai-tools` 패키지만 있으면 됩니다.
```bash
uv add crewai-tools
```
## 사용 예시
### 기본 사용법
### 다중 사용자 조직을 위한 Scoped Deployments
crew를 배포하고 각 통합을 특정 사용자에게 범위 지정할 수 있습니다. 예를 들어, google에 연결하는 crew는 특정 사용자의 gmail 계정을 사용할 수 있습니다.
### 도움 받기
## 사용자와 역할
워크스페이스의 각 구성원은 역할이 있으며, 이는 기능 접근 범위를 결정합니다.
가능한 작업:
* 사전 정의된 역할 사용 (Owner, Member)
* 권한을 세분화한 커스텀 역할 생성
* 설정 화면에서 언제든 역할 할당/변경
설정 위치: Settings → Roles
## 트레이스(Traces) 접근하기
### 2. Tasks & Agents
이 섹션에서는 crew 실행에 포함된 모든 task와 agent를 보여줍니다:
* task 이름 및 agent 할당
* 각 task에 사용된 agent 및 LLM
* 상태 (완료/실패)
* task의 개별 실행 시간
### 3. 최종 결과
모든 작업이 완료된 후 crew가 생성한 최종 결과를 표시합니다.
### 4. 실행 타임라인
각 작업이 시작되고 종료된 시점을 시각적으로 표현하여 병목 현상이나 병렬 실행 패턴을 파악하는 데 도움이 됩니다.
### 5. 상세 작업 보기
타임라인이나 작업 목록에서 특정 작업을 클릭하면 다음을 볼 수 있습니다:
* **작업 키**: 작업의 고유 식별자
* **작업 ID**: 시스템 내의 기술적 식별자
* **상태**: 현재 상태 (완료/진행 중/실패)
* **에이전트**: 해당 작업을 수행한 에이전트
* **LLM**: 이 작업에 사용된 언어 모델
* **시작/종료 시간**: 작업이 시작되고 완료된 시간
* **실행 시간**: 이 특정 작업의 소요 시간
* **작업 설명**: 에이전트에게 지시된 작업 내용
* **예상 출력**: 요청된 출력 형식
* **입력**: 이전 작업에서 이 작업에 제공된 입력값
* **출력**: 에이전트가 실제로 생성한 결과
## 디버깅을 위한 트레이스 사용
트레이스는 crew 문제 해결에 매우 유용합니다:
이 보기는 배포에 사용 가능한 모든 트리거 통합과 현재 연결 상태를 보여줍니다.
### 트리거 활성화 및 비활성화
각 트리거는 토글 스위치를 사용하여 쉽게 활성화하거나 비활성화할 수 있습니다:
* **활성화됨 (파란색 토글)**: 트리거가 활성 상태이며 지정된 이벤트가 발생할 때 배포를 자동으로 실행합니다
* **비활성화됨 (회색 토글)**: 트리거가 비활성 상태이며 이벤트에 응답하지 않습니다
토글을 클릭하기만 하면 트리거 상태를 변경할 수 있습니다. 변경 사항은 즉시 적용됩니다.
### 트리거 실행 모니터링
트리거된 실행의 성능과 기록을 추적합니다:
## 자동화 구축
자동화를 구축하기 전에 crew와 flow가 받을 트리거 페이로드의 구조를 이해하는 것이 도움이 됩니다.
### 페이로드 샘플 저장소
자동화를 구축하고 테스트하는 데 도움이 되도록 다양한 트리거 소스의 샘플 페이로드가 포함된 포괄적인 저장소를 유지 관리하고 있습니다:
**🔗 [CrewAI Enterprise 트리거 페이로드 샘플](https://github.com/crewAIInc/crewai-enterprise-trigger-payload-samples)**
이 저장소에는 다음이 포함되어 있습니다:
* **실제 페이로드 예제** - 다양한 트리거 소스(Gmail, Google Drive 등)에서 가져온 예제
* **페이로드 구조 문서** - 형식과 사용 가능한 필드를 보여주는 문서
### Crew와 트리거
기존 crew 정의는 트리거와 완벽하게 작동하며, 받은 페이로드를 분석하는 작업만 있으면 됩니다:
```python
@CrewBase
class MyAutomatedCrew:
@agent
def researcher(self) -> Agent:
return Agent(
config=self.agents_config['researcher'],
)
@task
def parse_trigger_payload(self) -> Task:
return Task(
config=self.tasks_config['parse_trigger_payload'],
agent=self.researcher(),
)
@task
def analyze_trigger_content(self) -> Task:
return Task(
config=self.tasks_config['analyze_trigger_data'],
agent=self.researcher(),
)
```
crew는 자동으로 트리거 페이로드를 받고 표준 CrewAI 컨텍스트 메커니즘을 통해 액세스할 수 있습니다.
### Flow와의 통합
flow의 경우 트리거 데이터 처리 방법을 더 세밀하게 제어할 수 있습니다:
#### 트리거 페이로드 액세스
flow의 모든 `@start()` 메서드는 `crewai_trigger_payload`라는 추가 매개변수를 허용합니다:
```python
from crewai.flow import Flow, start, listen
class MyAutomatedFlow(Flow):
@start()
def handle_trigger(self, crewai_trigger_payload: dict = None):
"""
이 start 메서드는 트리거 데이터를 받을 수 있습니다
"""
if crewai_trigger_payload:
# 트리거 데이터 처리
trigger_id = crewai_trigger_payload.get('id')
event_data = crewai_trigger_payload.get('payload', {})
# 다른 메서드에서 사용할 수 있도록 flow 상태에 저장
self.state.trigger_id = trigger_id
self.state.trigger_type = event_data
return event_data
# 수동 실행 처리
return None
@listen(handle_trigger)
def process_data(self, trigger_data):
"""
트리거 데이터 처리
"""
# ... 트리거 처리
```
#### Flow에서 Crew 트리거하기
트리거된 flow 내에서 crew를 시작할 때 트리거 페이로드를 전달합니다:
```python
@start()
def delegate_to_crew(self, crewai_trigger_payload: dict = None):
"""
전문 crew에 처리 위임
"""
crew = MySpecializedCrew()
# crew에 트리거 페이로드 전달
result = crew.crew().kickoff(
inputs={
'a_custom_parameter': "custom_value",
'crewai_trigger_payload': crewai_trigger_payload
},
)
return result
```
## 문제 해결
**트리거가 작동하지 않는 경우:**
* 트리거가 활성화되어 있는지 확인
* 통합 연결 상태 확인
**실행 실패:**
* 오류 세부 정보는 실행 로그 확인
* 개발 중인 경우 입력에 올바른 페이로드가 포함된 `crewai_trigger_payload` 매개변수가 포함되어 있는지 확인
자동화 트리거는 CrewAI 배포를 기존 비즈니스 프로세스 및 도구와 완벽하게 통합할 수 있는 반응형 이벤트 기반 시스템으로 변환합니다.
# Azure OpenAI 설정
Source: https://docs.crewai.com/ko/enterprise/guides/azure-openai-setup
엔터프라이즈 LLM 연결을 위해 Crew Studio와 함께 Azure OpenAI를 구성합니다
이 가이드는 Azure OpenAI와 Crew Studio를 연동하여 원활한 엔터프라이즈 AI 운영을 수행하는 방법을 안내합니다.
## 설정 프로세스
배포가 완료되면 다음을 확인할 수 있습니다:
* crew의 고유 URL
* crew API를 보호할 Bearer 토큰
* 배포를 삭제해야 하는 경우 "Delete" 버튼
Crew Studio를 사용하면 다음과 같은 작업이 가능합니다:
* Crew Assistant와 채팅하여 문제를 설명
* agent 및 task를 자동으로 생성
* 적절한 tool 선택
* 필요한 입력값 구성
* 커스터마이징을 위한 다운로드 가능한 코드 생성
* CrewAI Enterprise 플랫폼에 직접 배포
## 구성 단계
Crew Studio를 사용하기 전에 LLM 연결을 구성해야 합니다:
* 필요에 따라 추가 작업을 구성합니다.
* 모든 워크플로우 단계를 검토하여 올바르게 설정되었는지 확인합니다.
* 워크플로우를 활성화합니다.
### 2단계: 실행 시작
crew의 상세 페이지에서 실행을 시작할 수 있는 두 가지 옵션이 있습니다:
#### 옵션 A: 빠른 시작
1. Test Endpoints 섹션에서 `Kickoff` 링크를 클릭합니다.
2. JSON 에디터에서 crew에 필요한 입력 파라미터를 입력합니다.
3. `Send Request` 버튼을 클릭합니다.
#### 옵션 B: 시각적 인터페이스 사용
1. crew 상세 페이지에서 `Run` 탭을 클릭합니다.
2. 양식 필드에 필요한 입력값을 입력합니다.
3. `Run Crew` 버튼을 클릭합니다.
### 3단계: 실행 진행 상황 모니터링
실행을 시작한 후:
1. `kickoff_id`가 포함된 응답을 받게 됩니다. - **이 ID를 복사하세요**
2. 이 ID는 실행을 추적하는 데 필수적입니다
### 4단계: 실행 상태 확인
실행 진행 상황을 모니터링하려면:
1. Test Endpoints 섹션에서 "Status" 엔드포인트를 클릭하세요
2. 지정된 필드에 `kickoff_id`를 붙여넣으세요
3. "Get Status" 버튼을 클릭하세요
상태 응답에는 다음이 표시됩니다:
* 현재 실행 상태(`running`, `completed` 등)
* 진행 중인 작업에 대한 세부 정보
* 지금까지 생성된 모든 출력
### 5단계: 최종 결과 보기
실행이 완료되면:
1. 상태가 `completed`로 변경됩니다.
2. 전체 실행 결과와 출력을 확인할 수 있습니다.
3. 더 자세한 내용을 보려면 crew 상세 페이지의 `Executions` 탭을 확인하세요.
## 방법 2: API 사용
CrewAI Enterprise REST API를 사용하여 프로그래밍 방식으로 crews를 시작할 수도 있습니다.
### 인증
모든 API 요청에는 인증을 위한 베어러 토큰이 필요합니다:
```bash
curl -H "Authorization: Bearer YOUR_CREW_TOKEN" https://your-crew-url.crewai.com
```
베어러 토큰은 crew의 상세 페이지의 Status 탭에서 확인할 수 있습니다.
### 크루 상태 확인
작업을 실행하기 전에 크루가 정상적으로 실행되고 있는지 확인할 수 있습니다:
```bash
curl -H "Authorization: Bearer YOUR_CREW_TOKEN" https://your-crew-url.crewai.com
```
요청이 성공하면 크루가 정상적으로 동작 중임을 나타내는 메시지가 반환됩니다:
```
Healthy%
```
### 1단계: 필요한 입력값 확인
먼저, crew에서 요구하는 입력값이 무엇인지 확인합니다:
```bash
curl -X GET \
-H "Authorization: Bearer YOUR_CREW_TOKEN" \
https://your-crew-url.crewai.com/inputs
```
응답은 예를 들어 다음과 같이 필수 입력 파라미터 배열을 포함한 JSON 객체로 반환됩니다:
```json
{"inputs":["topic","current_year"]}
```
이 예시에서는 해당 crew에서 두 개의 입력값인 `topic`과 `current_year`를 필요로 함을 보여줍니다.
### 2단계: kickoff 실행
필수 입력값을 제공하여 실행을 시작합니다:
```bash
curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_CREW_TOKEN" \
-d '{"inputs": {"topic": "AI Agent Frameworks", "current_year": "2025"}}' \
https://your-crew-url.crewai.com/kickoff
```
응답에는 추적에 필요한 `kickoff_id`가 포함됩니다:
```json
{"kickoff_id":"abcd1234-5678-90ef-ghij-klmnopqrstuv"}
```
### 3단계: 실행 상태 확인
kickoff\_id를 사용하여 실행 진행 상황을 모니터링하세요:
```bash
curl -X GET \
-H "Authorization: Bearer YOUR_CREW_TOKEN" \
https://your-crew-url.crewai.com/status/abcd1234-5678-90ef-ghij-klmnopqrstuv
```
## 실행 처리
### 장기 실행
오랜 시간이 걸릴 수 있는 실행의 경우:
1. 주기적으로 상태를 확인하는 폴링 메커니즘을 구현하는 것을 고려하세요
2. 실행 완료 시 알림을 받을 수 있도록 웹훅(가능한 경우)을 사용하세요
3. 잠재적인 타임아웃에 대비하여 오류 처리를 구현하세요
### 실행 컨텍스트
실행 컨텍스트에는 다음이 포함됩니다:
* 시작 시 제공된 입력값
* 배포 중에 구성된 환경 변수
* 태스크 간에 유지되는 상태
### 실행 실패 디버깅
실행이 실패할 경우:
1. "Executions" 탭에서 자세한 로그를 확인하세요
2. "Traces" 탭에서 단계별 실행 세부 정보를 검토하세요
3. 트레이스 세부 정보에서 LLM 응답과 도구 사용 내역을 확인하세요
## 다음 단계
* 구성 요소 스타일을 애플리케이션 디자인에 맞게 맞춤화하세요
* 추가 구성을 위한 props를 추가하세요
* 애플리케이션의 상태 관리와 통합하세요
* 오류 처리 및 로딩 상태를 추가하세요
# Salesforce 트리거
Source: https://docs.crewai.com/ko/enterprise/guides/salesforce-trigger
Salesforce 워크플로우에서 CrewAI crew를 트리거하여 CRM 자동화
CrewAI Enterprise는 Salesforce에서 트리거되어 고객 관계 관리 워크플로우를 자동화하고 영업 운영을 강화할 수 있습니다.
## 개요
Salesforce는 기업이 영업, 서비스, 마케팅 운영을 효율화할 수 있도록 돕는 선도적인 고객 관계 관리(CRM) 플랫폼입니다. Salesforce에서 CrewAI 트리거를 설정하면 다음과 같은 작업을 수행할 수 있습니다:
* 리드 점수 산정 및 자격 심사 자동화
* 개인화된 영업 자료 생성
* AI 기반 응답으로 고객 서비스 강화
* 데이터 분석 및 보고 간소화
## 데모
## 시작하기
Salesforce 트리거를 설정하려면:
1. **지원팀 문의**: Salesforce 트리거 설정을 위해 CrewAI Enterprise 지원팀에 연락하세요.
2. **요구 사항 검토**: 필요한 Salesforce 권한과 API 액세스 권한이 있는지 확인하세요.
3. **연결 구성**: 지원팀과 협력하여 CrewAI와 귀하의 Salesforce 인스턴스 간의 연결을 설정하세요.
4. **트리거 테스트**: 트리거가 귀하의 특정 사용 사례에 맞게 올바르게 작동하는지 확인하세요.
## 사용 사례
일반적인 Salesforce + CrewAI 트리거 시나리오는 다음과 같습니다:
* **Lead 처리**: 들어오는 리드를 자동으로 분석하고 점수화
* **제안서 생성**: 기회 데이터를 기반으로 맞춤형 제안서 생성
* **고객 인사이트**: 고객 상호작용 이력에서 분석 보고서 생성
* **후속 조치 자동화**: 개인화된 후속 메시지 및 추천 생성
## 다음 단계
자세한 설정 지침 및 고급 구성 옵션에 대해서는 CrewAI Enterprise 지원팀에 문의해 주시기 바랍니다. 지원팀은 귀하의 특정 Salesforce 환경과 비즈니스 요구에 맞는 맞춤형 안내를 제공해 드릴 수 있습니다.
# Slack 트리거
Source: https://docs.crewai.com/ko/enterprise/guides/slack-trigger
슬래시 명령어를 사용해 Slack에서 CrewAI crew를 직접 트리거합니다
이 가이드는 CrewAI 트리거를 사용하여 Slack에서 직접 crew를 시작하는 방법을 설명합니다.
## 사전 요구 사항
* CrewAI Slack 트리거가 설치되어 있고 Slack 워크스페이스에 연결되어 있음
* CrewAI에서 하나 이상의 crew가 구성되어 있음
## 설정 단계
Slack이 나열되어 있고 연결되어 있는지 확인합니다.
* Enter를 누르거나 "**Kickoff crew**" 옵션을 선택합니다. "**Kickoff an AI Crew**"라는 제목의 대화상자가 나타납니다.
* crew에 입력값이 필요한 경우 "**Add Inputs**" 버튼을 클릭하여 입력값을 제공합니다.
* crew가 실행을 시작하면 Slack 채널에서 결과를 확인할 수 있습니다.
* 새로운 역할을 추가하려면 `Add Role` 버튼을 클릭하세요.
* 역할의 세부 정보와 권한을 입력한 후 `Create Role` 버튼을 클릭하여 역할을 생성하세요.
* 멤버가 초대를 수락하면 역할을 추가할 수 있습니다.
* 다시 `Roles` 탭으로 이동하세요
* 역할을 추가할 멤버로 이동한 후 `Role` 열에서 드롭다운을 클릭하세요
* 멤버에게 추가할 역할을 선택하세요
* `Update` 버튼을 클릭하여 역할을 저장하세요
이 작업을 수행하면 진행률 표시줄을 통해 추적할 수 있는 업데이트가 트리거됩니다. 시스템은 저장소에서 최신 코드를 가져와서 배포를 다시 빌드합니다.
## 2. 베어러 토큰 재설정
현재 토큰이 유출되었을 가능성이 있다고 의심되는 경우 등, 새 베어러 토큰을 생성해야 한다면 다음 단계를 따르세요:
1. CrewAI Enterprise 플랫폼에서 해당 crew로 이동하세요.
2. `Bearer Token` 섹션을 찾으세요.
3. 현재 토큰 옆에 있는 `Reset` 버튼을 클릭하세요.
2. `Environment Variables` 섹션을 찾습니다 (`Settings` 아이콘을 클릭해야 접근할 수 있습니다)
3. 제공된 필드에서 기존 변수를 수정하거나 새 변수를 추가합니다
4. 수정한 각 변수 옆의 `Update` 버튼을 클릭합니다
5. 마지막으로, 변경 사항을 적용하려면 페이지 하단의 `Update Deployment` 버튼을 클릭합니다
3. HTTP 액션 단계를 추가하세요.
* 액션을 `Send HTTP request`로 설정하세요.
* 메소드는 `POST`로 사용하세요.
* URL은 CrewAI Enterprise kickoff 엔드포인트로 설정하세요.
* 필요한 헤더 추가 (예: `Bearer Token`)
* Body에는 2단계에서 구성한 JSON content를 포함하세요.
* crew가 미리 정의된 시간에 kickoff됩니다.
2. 트리거로 webhook 단계를 추가하세요:
* 트리거 유형으로 `Catch Webhook`을 선택하세요.
* 이 작업을 통해 HTTP 요청을 수신하고 flow를 트리거하는 고유 URL이 생성됩니다.
* 이메일이 crew webhook 본문 텍스트를 사용하도록 구성하세요.
* 트리거 이벤트로 `New Pushed Message`를 선택합니다.
* 아직 Slack 계정을 연결하지 않았다면 연결하세요.
* Slack 메시지의 데이터를 사용하여 Crew의 입력값을 구성하세요.
* 3점 버튼을 선택한 후 'Push to Zapier'를 선택하세요.
CrewAI Enterprise는 오픈 소스 프레임워크의 강력함에 프로덕션 배포, 협업, 확장성을 위한 기능을 더했습니다. crew를 관리형 인프라에 배포하고, 실행을 실시간으로 모니터링하세요.
## 주요 기능
이 매트릭스를 통해 다양한 방식이 복잡성과 정밀성에 대한 요구 사항과 어떻게 일치하는지 시각적으로 확인할 수 있습니다. 각 사분면이 의미하는 바와 그것이 아키텍처 선택에 어떻게 도움이 되는지 함께 살펴보겠습니다.
## 복잡성-정밀도 행렬 설명
### 복잡성이란 무엇인가?
CrewAI 애플리케이션의 맥락에서 **복잡성**은 다음을 의미합니다:
* 요구되는 뚜렷한 단계 또는 작업 수
* 수행해야 할 작업의 다양성
* 서로 다른 구성 요소 간의 상호 의존성
* 조건부 로직과 분기의 필요성
* 전체 워크플로우의 정교함
### 정밀성이란 무엇인가?
**정밀성**은 이 맥락에서 다음을 의미합니다:
* 최종 결과물에 요구되는 정확성
* 구조화되고 예측 가능한 결과의 필요성
* 재현성의 중요성
* 각 단계에 대한 통제 수준
* 출력의 변동 허용치
### 네 가지 사분면
#### 1. 낮은 복잡도, 낮은 정밀도
**특징:**
* 단순하고 직관적인 작업
* 출력 결과의 일부 변형 허용
* 제한된 단계 수
* 창의적이거나 탐색적인 응용
**권장 접근법:** 최소한의 에이전트를 가진 Simple Crews
**예시 사용 사례:**
* 기본 콘텐츠 생성
* 아이디어 브레인스토밍
* 간단한 요약 작업
* 창의적 글쓰기 보조
#### 2. 낮은 복잡성, 높은 정밀도
**특징:**
* 정확하고 구조화된 결과물이 요구되는 단순한 워크플로우
* 재현 가능한 결과가 필요한 경우
* 단계는 제한적이지만, 높은 정확도가 요구됨
* 주로 데이터 처리 또는 변환이 포함됨
**권장 방식:** 직접적인 LLM 호출이나 구조화된 출력이 있는 간단한 Crew 사용
**예시 활용 사례:**
* 데이터 추출 및 변환
* 양식 작성 및 검증
* 구조화된 콘텐츠 생성(JSON, XML)
* 단순 분류 작업
#### 3. 높은 복잡성, 낮은 정밀도
**특징:**
* 여러 단계로 이루어진 다단계 프로세스
* 창의적이거나 탐색적인 출력물
* 구성 요소 간의 복잡한 상호작용
* 최종 결과의 변동성 허용
**권장 접근 방식:** 여러 전문화된 agent가 포함된 Complex Crew
**예시 사용 사례:**
* 연구 및 분석
* 콘텐츠 생성 파이프라인
* 탐색적 데이터 분석
* 창의적 문제 해결
#### 4. 높은 복잡성, 높은 정밀도
**특징:**
* 구조화된 산출물이 요구되는 복잡한 워크플로
* 엄격한 정확성 요구사항을 가진 여러 상호 의존적인 단계
* 정교한 처리와 정밀한 결과 모두 필요
* 종종 임무에 중요한 애플리케이션
**권장 접근 방식:** 검증 단계를 포함한 여러 Crew를 오케스트레이션하는 Flows
**예시 사용 사례:**
* 엔터프라이즈 의사결정 지원 시스템
* 복잡한 데이터 처리 파이프라인
* 다단계 문서 처리
* 규제 산업 애플리케이션
## 크루와 플로우 중에서 선택하기
### Crews를 선택해야 할 때
Crews는 다음과 같은 경우에 이상적입니다:
1. **협업 지능이 필요할 때** - 서로 다른 전문성을 가진 여러 agent들이 함께 작업해야 할 때
2. **문제가 창발적 사고를 요구할 때** - 다양한 관점과 접근 방식에서의 해결책이 이득이 될 때
3. **작업이 주로 창의적이거나 분석적일 때** - 작업이 리서치, 콘텐츠 제작, 분석을 포함할 때
4. **엄격한 구조보다는 적응력을 중시할 때** - agent의 자율성이 workflow에 도움이 될 때
5. **출력 형식이 다소 유연할 수 있을 때** - 출력 구조에 약간의 변동이 허용될 때
```python
# Example: Research Crew for market analysis
from crewai import Agent, Crew, Process, Task
# Create specialized agents
researcher = Agent(
role="Market Research Specialist",
goal="Find comprehensive market data on emerging technologies",
backstory="You are an expert at discovering market trends and gathering data."
)
analyst = Agent(
role="Market Analyst",
goal="Analyze market data and identify key opportunities",
backstory="You excel at interpreting market data and spotting valuable insights."
)
# Define their tasks
research_task = Task(
description="Research the current market landscape for AI-powered healthcare solutions",
expected_output="Comprehensive market data including key players, market size, and growth trends",
agent=researcher
)
analysis_task = Task(
description="Analyze the market data and identify the top 3 investment opportunities",
expected_output="Analysis report with 3 recommended investment opportunities and rationale",
agent=analyst,
context=[research_task]
)
# Create the crew
market_analysis_crew = Crew(
agents=[researcher, analyst],
tasks=[research_task, analysis_task],
process=Process.sequential,
verbose=True
)
# Run the crew
result = market_analysis_crew.kickoff()
```
### 플로우를 선택해야 할 때
플로우는 다음과 같은 경우에 이상적입니다:
1. **실행에 대한 정밀한 제어가 필요할 때** - 워크플로우에 정확한 순서 지정과 상태 관리가 필요한 경우
2. **애플리케이션에 복잡한 상태 요구사항이 있을 때** - 여러 단계에 걸쳐 상태를 유지하고 변환해야 하는 경우
3. **구조화되고 예측 가능한 출력이 필요할 때** - 애플리케이션에서 일관되고 포맷된 결과가 필요한 경우
4. **워크플로우에 조건부 로직이 포함될 때** - 중간 결과에 따라 다른 경로를 선택해야 하는 경우
5. **AI와 절차적 코드를 결합해야 할 때** - 솔루션에 AI 기능과 전통적인 프로그래밍이 모두 필요한 경우
```python
# Example: Customer Support Flow with structured processing
from crewai.flow.flow import Flow, listen, router, start
from pydantic import BaseModel
from typing import List, Dict
# Define structured state
class SupportTicketState(BaseModel):
ticket_id: str = ""
customer_name: str = ""
issue_description: str = ""
category: str = ""
priority: str = "medium"
resolution: str = ""
satisfaction_score: int = 0
class CustomerSupportFlow(Flow[SupportTicketState]):
@start()
def receive_ticket(self):
# In a real app, this might come from an API
self.state.ticket_id = "TKT-12345"
self.state.customer_name = "Alex Johnson"
self.state.issue_description = "Unable to access premium features after payment"
return "Ticket received"
@listen(receive_ticket)
def categorize_ticket(self, _):
# Use a direct LLM call for categorization
from crewai import LLM
llm = LLM(model="openai/gpt-4o-mini")
prompt = f"""
Categorize the following customer support issue into one of these categories:
- Billing
- Account Access
- Technical Issue
- Feature Request
- Other
Issue: {self.state.issue_description}
Return only the category name.
"""
self.state.category = llm.call(prompt).strip()
return self.state.category
@router(categorize_ticket)
def route_by_category(self, category):
# Route to different handlers based on category
return category.lower().replace(" ", "_")
@listen("billing")
def handle_billing_issue(self):
# Handle billing-specific logic
self.state.priority = "high"
# More billing-specific processing...
return "Billing issue handled"
@listen("account_access")
def handle_access_issue(self):
# Handle access-specific logic
self.state.priority = "high"
# More access-specific processing...
return "Access issue handled"
# Additional category handlers...
@listen("billing", "account_access", "technical_issue", "feature_request", "other")
def resolve_ticket(self, resolution_info):
# Final resolution step
self.state.resolution = f"Issue resolved: {resolution_info}"
return self.state.resolution
# Run the flow
support_flow = CustomerSupportFlow()
result = support_flow.kickoff()
```
### 크루와 플로우를 결합해야 할 때
가장 정교한 애플리케이션은 종종 크루와 플로우를 결합할 때 이점을 얻습니다:
1. **복잡한 다단계 프로세스** - 플로우를 사용해 전체 프로세스를 오케스트레이션하고, 크루를 통해 복잡한 하위 작업을 처리합니다.
2. **창의성과 구조가 모두 필요한 애플리케이션** - 창의적인 작업에는 크루를 사용하고, 구조적인 처리는 플로우로 처리합니다.
3. **엔터프라이즈급 AI 애플리케이션** - 플로우로 상태 및 프로세스 흐름을 관리하면서, 크루를 활용해 특화된 작업을 수행합니다.
```python
# Example: Content Production Pipeline combining Crews and Flows
from crewai.flow.flow import Flow, listen, start
from crewai import Agent, Crew, Process, Task
from pydantic import BaseModel
from typing import List, Dict
class ContentState(BaseModel):
topic: str = ""
target_audience: str = ""
content_type: str = ""
outline: Dict = {}
draft_content: str = ""
final_content: str = ""
seo_score: int = 0
class ContentProductionFlow(Flow[ContentState]):
@start()
def initialize_project(self):
# Set initial parameters
self.state.topic = "Sustainable Investing"
self.state.target_audience = "Millennial Investors"
self.state.content_type = "Blog Post"
return "Project initialized"
@listen(initialize_project)
def create_outline(self, _):
# Use a research crew to create an outline
researcher = Agent(
role="Content Researcher",
goal=f"Research {self.state.topic} for {self.state.target_audience}",
backstory="You are an expert researcher with deep knowledge of content creation."
)
outliner = Agent(
role="Content Strategist",
goal=f"Create an engaging outline for a {self.state.content_type}",
backstory="You excel at structuring content for maximum engagement."
)
research_task = Task(
description=f"Research {self.state.topic} focusing on what would interest {self.state.target_audience}",
expected_output="Comprehensive research notes with key points and statistics",
agent=researcher
)
outline_task = Task(
description=f"Create an outline for a {self.state.content_type} about {self.state.topic}",
expected_output="Detailed content outline with sections and key points",
agent=outliner,
context=[research_task]
)
outline_crew = Crew(
agents=[researcher, outliner],
tasks=[research_task, outline_task],
process=Process.sequential,
verbose=True
)
# Run the crew and store the result
result = outline_crew.kickoff()
# Parse the outline (in a real app, you might use a more robust parsing approach)
import json
try:
self.state.outline = json.loads(result.raw)
except:
# Fallback if not valid JSON
self.state.outline = {"sections": result.raw}
return "Outline created"
@listen(create_outline)
def write_content(self, _):
# Use a writing crew to create the content
writer = Agent(
role="Content Writer",
goal=f"Write engaging content for {self.state.target_audience}",
backstory="You are a skilled writer who creates compelling content."
)
editor = Agent(
role="Content Editor",
goal="Ensure content is polished, accurate, and engaging",
backstory="You have a keen eye for detail and a talent for improving content."
)
writing_task = Task(
description=f"Write a {self.state.content_type} about {self.state.topic} following this outline: {self.state.outline}",
expected_output="Complete draft content in markdown format",
agent=writer
)
editing_task = Task(
description="Edit and improve the draft content for clarity, engagement, and accuracy",
expected_output="Polished final content in markdown format",
agent=editor,
context=[writing_task]
)
writing_crew = Crew(
agents=[writer, editor],
tasks=[writing_task, editing_task],
process=Process.sequential,
verbose=True
)
# Run the crew and store the result
result = writing_crew.kickoff()
self.state.final_content = result.raw
return "Content created"
@listen(write_content)
def optimize_for_seo(self, _):
# Use a direct LLM call for SEO optimization
from crewai import LLM
llm = LLM(model="openai/gpt-4o-mini")
prompt = f"""
Analyze this content for SEO effectiveness for the keyword "{self.state.topic}".
Rate it on a scale of 1-100 and provide 3 specific recommendations for improvement.
Content: {self.state.final_content[:1000]}... (truncated for brevity)
Format your response as JSON with the following structure:
{{
"score": 85,
"recommendations": [
"Recommendation 1",
"Recommendation 2",
"Recommendation 3"
]
}}
"""
seo_analysis = llm.call(prompt)
# Parse the SEO analysis
import json
try:
analysis = json.loads(seo_analysis)
self.state.seo_score = analysis.get("score", 0)
return analysis
except:
self.state.seo_score = 50
return {"score": 50, "recommendations": ["Unable to parse SEO analysis"]}
# Run the flow
content_flow = ContentProductionFlow()
result = content_flow.kickoff()
```
## 실용적인 평가 프레임워크
특정 사용 사례에 맞는 올바른 접근 방식을 결정하려면 다음 단계별 평가 프레임워크를 따르세요:
### 1단계: 복잡성 평가
아래와 같은 기준으로 애플리케이션의 복잡성을 1\~10점 척도로 평가하세요:
1. **단계 수**: 얼마나 많은 개별 작업이 필요한가요?
* 1-3단계: 낮은 복잡성 (1-3)
* 4-7단계: 중간 복잡성 (4-7)
* 8단계 이상: 높은 복잡성 (8-10)
2. **상호 의존성**: 서로 다른 부분 간의 연결성은 어느 정도인가요?
* 의존성이 거의 없음: 낮은 복잡성 (1-3)
* 다소 의존성 있음: 중간 복잡성 (4-7)
* 복잡한 다중 의존성: 높은 복잡성 (8-10)
3. **조건부 논리**: 얼마나 많은 분기 및 의사결정이 필요한가요?
* 선형 프로세스: 낮은 복잡성 (1-3)
* 분기가 일부 있음: 중간 복잡성 (4-7)
* 복잡한 결정 트리: 높은 복잡성 (8-10)
4. **도메인 지식**: 요구되는 지식의 전문성은 어느 정도인가요?
* 일반적인 지식: 낮은 복잡성 (1-3)
* 일부 전문 지식 필요: 중간 복잡성 (4-7)
* 여러 도메인에 대한 깊은 전문성 필요: 높은 복잡성 (8-10)
평균 점수를 계산하여 전체 복잡성을 결정하세요.
### 2단계: 정밀도 요구사항 평가
정밀도 요구사항을 1-10점 척도로 평가하세요. 다음을 고려합니다:
1. **출력 구조**: 출력이 얼마나 구조화되어야 합니까?
* 자유형 텍스트: 낮은 정밀도 (1-3)
* 반구조화: 중간 정밀도 (4-7)
* 엄격한 포맷(JSON, XML): 높은 정밀도 (8-10)
2. **정확성 필요성**: 사실적 정확성이 얼마나 중요합니까?
* 창의적 콘텐츠: 낮은 정밀도 (1-3)
* 정보성 콘텐츠: 중간 정밀도 (4-7)
* 중요한 정보: 높은 정밀도 (8-10)
3. **재현성**: 실행마다 결과가 얼마나 일관되어야 합니까?
* 변동 허용: 낮은 정밀도 (1-3)
* 어느 정도 일관성 필요: 중간 정밀도 (4-7)
* 정확한 재현성 필요: 높은 정밀도 (8-10)
4. **오류 허용도**: 오류의 영향은 어느 정도입니까?
* 영향 적음: 낮은 정밀도 (1-3)
* 영향 보통: 중간 정밀도 (4-7)
* 영향 큼: 높은 정밀도 (8-10)
평균 점수를 계산하여 전체 정밀도 요구사항을 결정하세요.
### 3단계: 매트릭스에 매핑하기
복잡도와 정밀도 점수를 매트릭스에 표시하세요:
* **낮은 복잡도(1-4), 낮은 정밀도(1-4)**: Simple Crews
* **낮은 복잡도(1-4), 높은 정밀도(5-10)**: 직접적인 LLM 호출이 있는 Flows
* **높은 복잡도(5-10), 낮은 정밀도(1-4)**: Complex Crews
* **높은 복잡도(5-10), 높은 정밀도(5-10)**: Crews를 오케스트레이션하는 Flows
### 4단계: 추가 요소 고려
복잡성과 정밀성 외에도 다음을 고려하세요:
1. **개발 시간**: crew는 프로토타입을 더 빠르게 만들 수 있습니다
2. **유지보수 필요**: flow는 장기적인 유지보수에 더 적합합니다
3. **팀 전문성**: 팀이 다양한 접근법에 얼마나 익숙한지 고려하세요
4. **확장성 요구 사항**: flow는 일반적으로 복잡한 애플리케이션에 더 잘 확장됩니다
5. **통합 필요**: 솔루션이 기존 시스템과 어떻게 통합될지 고려하세요
## 결론
Crews와 Flows 중에서 선택하거나 결합하는 것은 CrewAI 애플리케이션의 효과성, 유지 관리성, 확장성에 영향을 미치는 중요한 아키텍처적 결정입니다. 복잡성과 정밀성이라는 차원에서 사용 사례를 평가함으로써, 귀하의 특정 요구 사항에 부합하는 정보에 기반한 결정을 내릴 수 있습니다.
가장 좋은 접근방식은 애플리케이션이 성숙해지면서 종종 진화한다는 점을 기억하세요. 귀하의 요구를 충족하는 가장 간단한 해결책으로 시작하고, 경험이 쌓이고 요구 사항이 명확해지면 아키텍처를 개선할 준비를 하세요.
## 2단계: 프로젝트 구조 살펴보기
CLI가 생성한 프로젝트 구조를 이해하는 시간을 가져봅시다. CrewAI는 Python 프로젝트의 모범 사례를 따르므로, crew가 더 복잡해질수록 코드를 쉽게 유지 관리하고 확장할 수 있습니다.
```
research_crew/
├── .gitignore
├── pyproject.toml
├── README.md
├── .env
└── src/
└── research_crew/
├── __init__.py
├── main.py
├── crew.py
├── tools/
│ ├── custom_tool.py
│ └── __init__.py
└── config/
├── agents.yaml
└── tasks.yaml
```
이 구조는 Python 프로젝트의 모범 사례를 따르며, 코드를 체계적으로 구성할 수 있도록 해줍니다. 설정 파일(YAML)과 구현 코드(Python)의 분리로 인해, 기본 코드를 변경하지 않고도 crew의 동작을 쉽게 수정할 수 있습니다.
## 3단계: 에이전트 구성하기
이제 재미있는 단계가 시작됩니다 - 여러분의 AI 에이전트를 정의하는 것입니다! CrewAI에서 에이전트는 특정 역할, 목표 및 배경을 가진 전문화된 엔터티로, 이들이 어떻게 행동할지를 결정합니다. 각각 고유한 성격과 목적을 지닌 연극의 등장인물로 생각하면 됩니다.
우리의 리서치 crew를 위해 두 명의 에이전트를 만들겠습니다:
1. 정보를 찾아 정리하는 데 뛰어난 **리서처**
2. 연구 결과를 해석하고 통찰력 있는 보고서를 작성할 수 있는 **애널리스트**
이러한 전문화된 에이전트를 정의하기 위해 `agents.yaml` 파일을 수정해봅시다. `llm` 항목은 사용 중인 제공업체에 맞게 설정하세요.
```yaml
# src/research_crew/config/agents.yaml
researcher:
role: >
Senior Research Specialist for {topic}
goal: >
Find comprehensive and accurate information about {topic}
with a focus on recent developments and key insights
backstory: >
You are an experienced research specialist with a talent for
finding relevant information from various sources. You excel at
organizing information in a clear and structured manner, making
complex topics accessible to others.
llm: provider/model-id # e.g. openai/gpt-4o, google/gemini-2.0-flash, anthropic/claude...
analyst:
role: >
Data Analyst and Report Writer for {topic}
goal: >
Analyze research findings and create a comprehensive, well-structured
report that presents insights in a clear and engaging way
backstory: >
You are a skilled analyst with a background in data interpretation
and technical writing. You have a talent for identifying patterns
and extracting meaningful insights from research data, then
communicating those insights effectively through well-crafted reports.
llm: provider/model-id # e.g. openai/gpt-4o, google/gemini-2.0-flash, anthropic/claude...
```
각 에이전트가 고유한 역할, 목표, 그리고 배경을 가지고 있다는 점에 주목하세요. 이 요소들은 단순한 설명 그 이상으로, 실제로 에이전트가 자신의 과업을 어떻게 접근하는지에 적극적으로 영향을 미칩니다. 이러한 부분을 신중하게 설계함으로써 서로 보완하는 전문적인 역량과 관점을 가진 에이전트를 만들 수 있습니다.
## 4단계: 작업 정의하기
이제 agent들을 정의했으니, 이들에게 수행할 구체적인 작업을 지정해야 합니다. CrewAI의 작업(task)은 agent가 수행할 구체적인 업무를 나타내며, 자세한 지침과 예상 결과물이 포함됩니다.
연구 crew를 위해 두 가지 주요 작업을 정의하겠습니다:
1. 포괄적인 정보 수집을 위한 **연구 작업**
2. 인사이트 있는 보고서 생성을 위한 **분석 작업**
`tasks.yaml` 파일을 다음과 같이 수정해 보겠습니다:
```yaml
# src/research_crew/config/tasks.yaml
research_task:
description: >
{topic}에 대해 철저한 연구를 수행하세요. 다음에 중점을 두세요:
1. 주요 개념 및 정의
2. 역사적 발전과 최근 동향
3. 주요 과제와 기회
4. 주목할 만한 적용 사례 또는 케이스 스터디
5. 향후 전망과 잠재적 발전
반드시 명확한 섹션으로 구성된 구조화된 형식으로 결과를 정리하세요.
expected_output: >
{topic}의 모든 요구 사항을 다루는, 잘 구성된 섹션이 포함된 포괄적인 연구 문서.
필요에 따라 구체적인 사실, 수치, 예시를 포함하세요.
agent: researcher
analysis_task:
description: >
연구 결과를 분석하고 {topic}에 대한 포괄적인 보고서를 작성하세요.
보고서에는 다음 내용이 포함되어야 합니다:
1. 간결한 요약(executive summary)으로 시작
2. 연구의 모든 주요 정보 포함
3. 동향과 패턴에 대한 통찰력 있는 분석 제공
4. 추천사항 또는 미래 고려 사항 제시
5. 명확한 제목과 함께 전문적이고 읽기 쉬운 형식으로 작성
expected_output: >
연구 결과와 추가 분석, 인사이트를 포함한 {topic}에 대한 정제되고 전문적인 보고서.
보고서는 간결한 요약, 본문, 결론 등으로 잘 구조화되어 있어야 합니다.
agent: analyst
context:
- research_task
output_file: output/report.md
```
분석 작업 내의 `context` 필드에 주목하세요. 이 강력한 기능을 통해 analyst가 연구 작업의 결과물을 참조할 수 있습니다. 이를 통해 정보가 human team에서처럼 agent 간에 자연스럽게 흐르는 워크플로우가 만들어집니다.
## 5단계: 크루 구성 설정하기
이제 크루를 구성하여 모든 것을 하나로 모을 시간입니다. 크루는 에이전트들이 함께 작업을 완료하는 방식을 조율하는 컨테이너 역할을 합니다.
`crew.py` 파일을 다음과 같이 수정해보겠습니다:
```python
# src/research_crew/crew.py
from crewai import Agent, Crew, Process, Task
from crewai.project import CrewBase, agent, crew, task
from crewai_tools import SerperDevTool
from crewai.agents.agent_builder.base_agent import BaseAgent
from typing import List
@CrewBase
class ResearchCrew():
"""Research crew for comprehensive topic analysis and reporting"""
agents: List[BaseAgent]
tasks: List[Task]
@agent
def researcher(self) -> Agent:
return Agent(
config=self.agents_config['researcher'], # type: ignore[index]
verbose=True,
tools=[SerperDevTool()]
)
@agent
def analyst(self) -> Agent:
return Agent(
config=self.agents_config['analyst'], # type: ignore[index]
verbose=True
)
@task
def research_task(self) -> Task:
return Task(
config=self.tasks_config['research_task'] # type: ignore[index]
)
@task
def analysis_task(self) -> Task:
return Task(
config=self.tasks_config['analysis_task'], # type: ignore[index]
output_file='output/report.md'
)
@crew
def crew(self) -> Crew:
"""Creates the research crew"""
return Crew(
agents=self.agents,
tasks=self.tasks,
process=Process.sequential,
verbose=True,
)
```
이 코드에서는 다음을 수행합니다:
1. researcher 에이전트를 생성하고, SerperDevTool을 장착하여 웹 검색 기능을 추가합니다.
2. analyst 에이전트를 생성합니다.
3. research와 analysis 작업(task)을 설정합니다.
4. 크루가 작업을 순차적으로 수행하도록 설정합니다(analyst가 researcher가 끝날 때까지 대기).
여기서 마법이 일어납니다. 몇 줄의 코드만으로도, 특화된 에이전트들이 조율된 프로세스 내에서 협업하는 협동 AI 시스템을 정의할 수 있습니다.
## 6단계: 메인 스크립트 설정
이제 우리 crew를 실행할 메인 스크립트를 설정해 보겠습니다. 이곳에서 crew가 리서치할 구체적인 주제를 지정합니다.
```python
#!/usr/bin/env python
# src/research_crew/main.py
import os
from research_crew.crew import ResearchCrew
# Create output directory if it doesn't exist
os.makedirs('output', exist_ok=True)
def run():
"""
Run the research crew.
"""
inputs = {
'topic': 'Artificial Intelligence in Healthcare'
}
# Create and run the crew
result = ResearchCrew().crew().kickoff(inputs=inputs)
# Print the result
print("\n\n=== FINAL REPORT ===\n\n")
print(result.raw)
print("\n\nReport has been saved to output/report.md")
if __name__ == "__main__":
run()
```
이 스크립트는 환경을 준비하고, 리서치 주제를 지정하며, crew의 작업을 시작합니다. CrewAI의 강력함은 이 코드가 얼마나 간단한지에서 드러납니다. 여러 AI 에이전트를 관리하는 모든 복잡함이 프레임워크에 의해 처리됩니다.
## 7단계: 환경 변수 설정하기
프로젝트 루트에 `.env` 파일을 생성하고 API 키를 입력하세요:
```sh
SERPER_API_KEY=your_serper_api_key
# Add your provider's API key here too.
```
선택한 provider를 구성하는 방법에 대한 자세한 내용은 [LLM 설정 가이드](/ko/concepts/llms#setting-up-your-llm)를 참고하세요. Serper API 키는 [Serper.dev](https://serper.dev/)에서 받을 수 있습니다.
## 8단계: 필수 종속성 설치
CrewAI CLI를 사용하여 필요한 종속성을 설치하세요:
```bash
crewai install
```
이 명령어는 다음을 수행합니다:
1. 프로젝트 구성에서 종속성을 읽어옵니다
2. 필요하다면 가상 환경을 생성합니다
3. 모든 필수 패키지를 설치합니다
## 9단계: Crew 실행하기
이제 흥미로운 순간입니다 - crew를 실행하여 AI 협업이 어떻게 이루어지는지 직접 확인해보세요!
```bash
crewai run
```
이 명령어를 실행하면 crew가 즉시 작동하는 모습을 볼 수 있습니다. researcher는 지정된 주제에 대한 정보를 수집하고, analyst가 그 연구를 바탕으로 종합 보고서를 작성합니다. 에이전트들의 사고 과정, 행동, 결과물이 실시간으로 표시되며 서로 협력하여 작업을 완수하는 모습을 확인할 수 있습니다.
## 10단계: 결과물 검토
crew가 작업을 완료하면, 최종 보고서는 `output/report.md` 파일에서 확인할 수 있습니다. 보고서에는 다음과 같은 내용이 포함됩니다:
1. 요약 보고서
2. 주제에 대한 상세 정보
3. 분석 및 인사이트
4. 권장사항 또는 향후 고려사항
지금까지 달성한 것을 잠시 돌아보세요. 여러분은 여러 AI 에이전트가 협업하여 각자의 전문적인 기술을 발휘함으로써, 단일 에이전트가 혼자서 이루어낼 수 있는 것보다 더 뛰어난 결과를 만들어내는 시스템을 구축한 것입니다.
## 기타 CLI 명령어 탐색
CrewAI는 crew 작업을 위한 몇 가지 유용한 CLI 명령어를 추가로 제공합니다:
```bash
# 모든 사용 가능한 명령어 보기
crewai --help
# crew 실행
crewai run
# crew 테스트
crewai test
# crew 메모리 초기화
crewai reset-memories
# 특정 task에서 재실행
crewai replay -t
## 2단계: 프로젝트 구조 이해하기
생성된 프로젝트는 다음과 같은 구조를 가지고 있습니다. 잠시 시간을 내어 이 구조에 익숙해지세요. 구조를 이해하면 앞으로 더 복잡한 flow를 만드는 데 도움이 됩니다.
```
guide_creator_flow/
├── .gitignore
├── pyproject.toml
├── README.md
├── .env
├── main.py
├── crews/
│ └── poem_crew/
│ ├── config/
│ │ ├── agents.yaml
│ │ └── tasks.yaml
│ └── poem_crew.py
└── tools/
└── custom_tool.py
```
이 구조는 flow의 다양한 구성 요소를 명확하게 분리해줍니다:
* `main.py` 파일의 main flow 로직
* `crews` 디렉터리의 특화된 crew들
* `tools` 디렉터리의 custom tool들
이제 이 구조를 수정하여 guide creator flow를 만들 것입니다. 이 flow는 포괄적인 학습 가이드 생성을 조직하는 역할을 합니다.
## 3단계: Content Writer Crew 추가
우리 flow에는 콘텐츠 생성 프로세스를 처리할 전문화된 crew가 필요합니다. CrewAI CLI를 사용하여 content writer crew를 추가해봅시다:
```bash
crewai flow add-crew content-crew
```
이 명령어는 자동으로 crew에 필요한 디렉터리와 템플릿 파일을 생성합니다. content writer crew는 가이드의 각 섹션을 작성하고 검토하는 역할을 담당하며, 메인 애플리케이션에 의해 조율되는 전체 flow 내에서 작업하게 됩니다.
## 4단계: 콘텐츠 작가 Crew 구성
이제 콘텐츠 작가 crew를 위해 생성된 파일을 수정해보겠습니다. 우리는 가이드의 고품질 콘텐츠를 만들기 위해 협업하는 두 명의 전문 에이전트 - 작가와 리뷰어 - 를 설정할 것입니다.
1. 먼저, 에이전트 구성 파일을 업데이트하여 콘텐츠 제작 팀을 정의합니다:
`llm`을 사용 중인 공급자로 설정해야 함을 기억하세요.
```yaml
# src/guide_creator_flow/crews/content_crew/config/agents.yaml
content_writer:
role: >
교육 콘텐츠 작가
goal: >
할당된 주제를 철저히 설명하고 독자에게 소중한 통찰력을 제공하는 흥미롭고 유익한 콘텐츠를 제작합니다
backstory: >
당신은 명확하고 흥미로운 콘텐츠를 만드는 데 능숙한 교육 전문 작가입니다. 복잡한 개념도 쉽게 설명하며,
정보를 독자가 이해하기 쉽게 조직할 수 있습니다.
llm: provider/model-id # 예: openai/gpt-4o, google/gemini-2.0-flash, anthropic/claude...
content_reviewer:
role: >
교육 콘텐츠 검토자 및 에디터
goal: >
콘텐츠가 정확하고, 포괄적이며, 잘 구조화되어 있고, 이전에 작성된 섹션과의 일관성을 유지하도록 합니다
backstory: >
당신은 수년간 교육 콘텐츠를 검토해 온 꼼꼼한 에디터입니다. 세부 사항, 명확성, 일관성에 뛰어나며,
원 저자의 목소리를 유지하면서도 콘텐츠의 품질을 향상시키는 데 능숙합니다.
llm: provider/model-id # 예: openai/gpt-4o, google/gemini-2.0-flash, anthropic/claude...
```
이 에이전트 정의는 AI 에이전트가 콘텐츠 제작을 접근하는 전문화된 역할과 관점을 구성합니다. 각 에이전트가 뚜렷한 목적과 전문성을 지니고 있음을 확인하세요.
2. 다음으로, 작업 구성 파일을 업데이트하여 구체적인 작성 및 검토 작업을 정의합니다:
```yaml
# src/guide_creator_flow/crews/content_crew/config/tasks.yaml
write_section_task:
description: >
주제에 대한 포괄적인 섹션을 작성하세요: "{section_title}"
섹션 설명: {section_description}
대상 독자: {audience_level} 수준 학습자
작성 시 아래 사항을 반드시 지켜주세요:
1. 섹션 주제에 대한 간략한 소개로 시작
2. 모든 주요 개념을 예시와 함께 명확하게 설명
3. 적절하다면 실용적인 활용 사례나 연습문제 포함
4. 주요 포인트 요약으로 마무리
5. 대략 500-800단어 분량
콘텐츠는 적절한 제목, 목록, 강조를 포함해 Markdown 형식으로 작성하세요.
이전에 작성된 섹션:
{previous_sections}
반드시 콘텐츠가 이전에 쓴 섹션과 일관성을 유지하고 앞에서 설명된 개념을 바탕으로 작성되도록 하세요.
expected_output: >
주제를 철저히 설명하고 대상 독자에게 적합한, 구조가 잘 잡힌 Markdown 형식의 포괄적 섹션
agent: content_writer
review_section_task:
description: >
아래 "{section_title}" 섹션의 내용을 검토하고 개선하세요:
{draft_content}
대상 독자: {audience_level} 수준 학습자
이전에 작성된 섹션:
{previous_sections}
검토 시 아래 사항을 반드시 지켜주세요:
1. 문법/철자 오류 수정
2. 명확성 및 가독성 향상
3. 내용이 포괄적이고 정확한지 확인
4. 이전에 쓴 섹션과 일관성 유지
5. 구조와 흐름 강화
6. 누락된 핵심 정보 추가
개선된 버전의 섹션을 Markdown 형식으로 제공하세요.
expected_output: >
원래의 구조를 유지하면서도 명확성, 정확성, 일관성을 향상시킨 세련된 개선본
agent: content_reviewer
context:
- write_section_task
```
이 작업 정의는 에이전트에게 세부적인 지침을 제공하여 우리의 품질 기준에 부합하는 콘텐츠를 생산하게 합니다. review 작업의 `context` 파라미터를 통해 리뷰어가 작가의 결과물에 접근할 수 있는 워크플로우가 생성됨에 주의하세요.
3. 이제 crew 구현 파일을 업데이트하여 에이전트와 작업이 어떻게 연동되는지 정의합니다:
```python
# src/guide_creator_flow/crews/content_crew/content_crew.py
from crewai import Agent, Crew, Process, Task
from crewai.project import CrewBase, agent, crew, task
from crewai.agents.agent_builder.base_agent import BaseAgent
from typing import List
@CrewBase
class ContentCrew():
"""Content writing crew"""
agents: List[BaseAgent]
tasks: List[Task]
@agent
def content_writer(self) -> Agent:
return Agent(
config=self.agents_config['content_writer'], # type: ignore[index]
verbose=True
)
@agent
def content_reviewer(self) -> Agent:
return Agent(
config=self.agents_config['content_reviewer'], # type: ignore[index]
verbose=True
)
@task
def write_section_task(self) -> Task:
return Task(
config=self.tasks_config['write_section_task'] # type: ignore[index]
)
@task
def review_section_task(self) -> Task:
return Task(
config=self.tasks_config['review_section_task'], # type: ignore[index]
context=[self.write_section_task()]
)
@crew
def crew(self) -> Crew:
"""Creates the content writing crew"""
return Crew(
agents=self.agents,
tasks=self.tasks,
process=Process.sequential,
verbose=True,
)
```
이 crew 정의는 에이전트와 작업 간의 관계를 설정하여, 콘텐츠 작가가 초안을 작성하고 리뷰어가 이를 개선하는 순차적 과정을 만듭니다. 이 crew는 독립적으로도 작동할 수 있지만, 우리의 플로우에서 더 큰 시스템의 일부로 오케스트레이션될 예정입니다.
## 5단계: 플로우(Flow) 생성
이제 가장 흥미로운 부분입니다 - 전체 가이드 생성 과정을 오케스트레이션할 플로우를 만드는 단계입니다. 이곳에서 우리는 일반 Python 코드, 직접적인 LLM 호출, 그리고 우리의 컨텐츠 제작 crew를 결합하여 일관된 시스템으로 만듭니다.
우리의 플로우는 다음과 같은 일을 수행합니다:
1. 주제와 대상 독자 수준에 대한 사용자 입력을 받습니다.
2. 구조화된 가이드 개요를 만들기 위해 직접 LLM 호출을 합니다.
3. 컨텐츠 writer crew를 사용하여 각 섹션을 순차적으로 처리합니다.
4. 모든 내용을 결합하여 최종 종합 문서를 완성합니다.
`main.py` 파일에 우리의 플로우를 생성해봅시다:
```python
#!/usr/bin/env python
import json
import os
from typing import List, Dict
from pydantic import BaseModel, Field
from crewai import LLM
from crewai.flow.flow import Flow, listen, start
from guide_creator_flow.crews.content_crew.content_crew import ContentCrew
# Define our models for structured data
class Section(BaseModel):
title: str = Field(description="Title of the section")
description: str = Field(description="Brief description of what the section should cover")
class GuideOutline(BaseModel):
title: str = Field(description="Title of the guide")
introduction: str = Field(description="Introduction to the topic")
target_audience: str = Field(description="Description of the target audience")
sections: List[Section] = Field(description="List of sections in the guide")
conclusion: str = Field(description="Conclusion or summary of the guide")
# Define our flow state
class GuideCreatorState(BaseModel):
topic: str = ""
audience_level: str = ""
guide_outline: GuideOutline = None
sections_content: Dict[str, str] = {}
class GuideCreatorFlow(Flow[GuideCreatorState]):
"""Flow for creating a comprehensive guide on any topic"""
@start()
def get_user_input(self):
"""Get input from the user about the guide topic and audience"""
print("\n=== Create Your Comprehensive Guide ===\n")
# Get user input
self.state.topic = input("What topic would you like to create a guide for? ")
# Get audience level with validation
while True:
audience = input("Who is your target audience? (beginner/intermediate/advanced) ").lower()
if audience in ["beginner", "intermediate", "advanced"]:
self.state.audience_level = audience
break
print("Please enter 'beginner', 'intermediate', or 'advanced'")
print(f"\nCreating a guide on {self.state.topic} for {self.state.audience_level} audience...\n")
return self.state
@listen(get_user_input)
def create_guide_outline(self, state):
"""Create a structured outline for the guide using a direct LLM call"""
print("Creating guide outline...")
# Initialize the LLM
llm = LLM(model="openai/gpt-4o-mini", response_format=GuideOutline)
# Create the messages for the outline
messages = [
{"role": "system", "content": "You are a helpful assistant designed to output JSON."},
{"role": "user", "content": f"""
Create a detailed outline for a comprehensive guide on "{state.topic}" for {state.audience_level} level learners.
The outline should include:
1. A compelling title for the guide
2. An introduction to the topic
3. 4-6 main sections that cover the most important aspects of the topic
4. A conclusion or summary
For each section, provide a clear title and a brief description of what it should cover.
"""}
]
# Make the LLM call with JSON response format
response = llm.call(messages=messages)
# Parse the JSON response
outline_dict = json.loads(response)
self.state.guide_outline = GuideOutline(**outline_dict)
# Ensure output directory exists before saving
os.makedirs("output", exist_ok=True)
# Save the outline to a file
with open("output/guide_outline.json", "w") as f:
json.dump(outline_dict, f, indent=2)
print(f"Guide outline created with {len(self.state.guide_outline.sections)} sections")
return self.state.guide_outline
@listen(create_guide_outline)
def write_and_compile_guide(self, outline):
"""Write all sections and compile the guide"""
print("Writing guide sections and compiling...")
completed_sections = []
# Process sections one by one to maintain context flow
for section in outline.sections:
print(f"Processing section: {section.title}")
# Build context from previous sections
previous_sections_text = ""
if completed_sections:
previous_sections_text = "# Previously Written Sections\n\n"
for title in completed_sections:
previous_sections_text += f"## {title}\n\n"
previous_sections_text += self.state.sections_content.get(title, "") + "\n\n"
else:
previous_sections_text = "No previous sections written yet."
# Run the content crew for this section
result = ContentCrew().crew().kickoff(inputs={
"section_title": section.title,
"section_description": section.description,
"audience_level": self.state.audience_level,
"previous_sections": previous_sections_text,
"draft_content": ""
})
# Store the content
self.state.sections_content[section.title] = result.raw
completed_sections.append(section.title)
print(f"Section completed: {section.title}")
# Compile the final guide
guide_content = f"# {outline.title}\n\n"
guide_content += f"## Introduction\n\n{outline.introduction}\n\n"
# Add each section in order
for section in outline.sections:
section_content = self.state.sections_content.get(section.title, "")
guide_content += f"\n\n{section_content}\n\n"
# Add conclusion
guide_content += f"## Conclusion\n\n{outline.conclusion}\n\n"
# Save the guide
with open("output/complete_guide.md", "w") as f:
f.write(guide_content)
print("\nComplete guide compiled and saved to output/complete_guide.md")
return "Guide creation completed successfully"
def kickoff():
"""Run the guide creator flow"""
GuideCreatorFlow().kickoff()
print("\n=== Flow Complete ===")
print("Your comprehensive guide is ready in the output directory.")
print("Open output/complete_guide.md to view it.")
def plot():
"""Generate a visualization of the flow"""
flow = GuideCreatorFlow()
flow.plot("guide_creator_flow")
print("Flow visualization saved to guide_creator_flow.html")
if __name__ == "__main__":
kickoff()
```
이 플로우에서 일어나는 과정을 분석해봅시다:
1. 구조화된 데이터에 대한 Pydantic 모델을 정의하여 타입 안전성과 명확한 데이터 표현을 보장합니다.
2. 플로우 단계별로 데이터를 유지하기 위한 state 클래스를 생성합니다.
3. 세 가지 주요 플로우 단계를 구현합니다:
* `@start()` 데코레이터로 사용자 입력을 받습니다.
* 직접 LLM 호출로 가이드 개요를 생성합니다.
* content crew로 각 섹션을 처리합니다.
4. `@listen()` 데코레이터를 활용해 단계 간 이벤트 기반 관계를 설정합니다.
이것이 바로 flows의 힘입니다 - 다양한 처리 유형(사용자 상호작용, 직접적인 LLM 호출, crew 기반 작업)을 하나의 일관된 이벤트 기반 시스템으로 결합할 수 있습니다.
## 6단계: 환경 변수 설정하기
프로젝트 루트에 `.env` 파일을 생성하고 API 키를 입력하세요. 공급자 구성에 대한 자세한 내용은 [LLM 설정 가이드](/ko/concepts/llms#setting-up-your-llm)를 참고하세요.
```sh .env
OPENAI_API_KEY=your_openai_api_key
# or
GEMINI_API_KEY=your_gemini_api_key
# or
ANTHROPIC_API_KEY=your_anthropic_api_key
```
## 7단계: 의존성 설치
필수 의존성을 설치합니다:
```bash
crewai install
```
## 8단계: Flow 실행하기
이제 여러분의 flow가 실제로 작동하는 모습을 볼 차례입니다! CrewAI CLI를 사용하여 flow를 실행하세요:
```bash
crewai flow kickoff
```
이 명령어를 실행하면 flow가 다음과 같이 작동하는 것을 확인할 수 있습니다:
1. 주제와 대상 수준을 입력하라는 메시지가 표시됩니다.
2. 가이드의 체계적인 개요를 생성합니다.
3. 각 섹션을 처리할 때 content writer와 reviewer가 협업합니다.
4. 마지막으로 모든 내용을 종합하여 완성도 높은 가이드를 만듭니다.
이는 여러 구성요소(인공지능 및 비인공지능 모두)가 포함된 복잡한 프로세스를 flows가 어떻게 조정할 수 있는지 보여줍니다.
## 9단계: Flow 시각화하기
flow의 강력한 기능 중 하나는 구조를 시각화할 수 있다는 점입니다.
```bash
crewai flow plot
```
이 명령은 flow의 구조를 보여주는 HTML 파일을 생성하며, 각 단계 간의 관계와 그 사이에 흐르는 데이터를 확인할 수 있습니다. 이러한 시각화는 복잡한 flow를 이해하고 디버깅하는 데 매우 유용합니다.
## 10단계: 출력물 검토하기
flow가 완료되면 `output` 디렉토리에서 두 개의 파일을 찾을 수 있습니다:
1. `guide_outline.json`: 가이드의 구조화된 개요가 포함되어 있습니다
2. `complete_guide.md`: 모든 섹션이 포함된 종합적인 가이드입니다
이 파일들을 잠시 검토하고 여러분이 구축한 시스템을 되돌아보세요. 이 시스템은 사용자 입력, 직접적인 AI 상호작용, 협업 에이전트 작업을 결합하여 복잡하고 고품질의 결과물을 만들어냅니다.
## 가능한 것의 예술: 첫 번째 Flow 그 이상
이 가이드에서 배운 내용은 훨씬 더 정교한 AI 시스템을 만드는 데 기반이 됩니다. 다음은 이 기본 flow를 확장할 수 있는 몇 가지 방법입니다:
### 사용자 상호작용 향상
더욱 인터랙티브한 플로우를 만들 수 있습니다:
* 입력 및 출력을 위한 웹 인터페이스
* 실시간 진행 상황 업데이트
* 인터랙티브한 피드백 및 개선 루프
* 다단계 사용자 상호작용
### 추가 처리 단계 추가하기
다음과 같은 추가 단계로 flow를 확장할 수 있습니다:
* 개요 작성 전 사전 리서치
* 일러스트를 위한 이미지 생성
* 기술 가이드용 코드 스니펫 생성
* 최종 품질 보증 및 사실 확인
### 더 복잡한 Flows 생성하기
더 정교한 flow 패턴을 구현할 수 있습니다:
* 사용자 선호도나 콘텐츠 유형에 따른 조건 분기
* 독립적인 섹션의 병렬 처리
* 피드백과 함께하는 반복적 개선 루프
* 외부 API 및 서비스와의 통합
### 다양한 도메인에 적용하기
동일한 패턴을 사용하여 다음과 같은 flow를 만들 수 있습니다:
* **대화형 스토리텔링**: 사용자 입력을 바탕으로 개인화된 이야기를 생성
* **비즈니스 인텔리전스**: 데이터를 처리하고, 인사이트를 도출하며, 리포트를 생성
* **제품 개발**: 아이디어 구상, 디자인, 기획을 지원
* **교육 시스템**: 개인화된 학습 경험을 제공
## 주요 특징 시연
이 guide creator flow에서는 CrewAI의 여러 강력한 기능을 시연합니다:
1. **사용자 상호작용**: flow는 사용자로부터 직접 입력을 수집합니다
2. **직접적인 LLM 호출**: 효율적이고 단일 목적의 AI 상호작용을 위해 LLM 클래스를 사용합니다
3. **Pydantic을 통한 구조화된 데이터**: 타입 안정성을 보장하기 위해 Pydantic 모델을 사용합니다
4. **컨텍스트를 활용한 순차 처리**: 섹션을 순서대로 작성하면서 이전 섹션을 컨텍스트로 제공합니다
5. **멀티 에이전트 crew**: 콘텐츠 생성을 위해 특화된 에이전트(writer 및 reviewer)를 활용합니다
6. **상태 관리**: 프로세스의 다양한 단계에 걸쳐 상태를 유지합니다
7. **이벤트 기반 아키텍처**: 이벤트에 응답하기 위해 `@listen` 데코레이터를 사용합니다
## 플로우 구조 이해하기
플로우의 주요 구성 요소를 분해하여 자신만의 플로우를 만드는 방법을 이해할 수 있도록 도와드리겠습니다:
### 1. 직접 LLM 호출
Flow를 사용하면 간단하고 구조화된 응답이 필요할 때 언어 모델에 직접 호출할 수 있습니다:
```python
llm = LLM(
model="model-id-here", # gpt-4o, gemini-2.0-flash, anthropic/claude...
response_format=GuideOutline
)
response = llm.call(messages=messages)
```
특정하고 구조화된 출력이 필요할 때 crew를 사용하는 것보다 더 효율적입니다.
### 2. 이벤트 기반 아키텍처
Flows는 데코레이터를 사용하여 컴포넌트 간의 관계를 설정합니다:
```python
@start()
def get_user_input(self):
# First step in the flow
# ...
@listen(get_user_input)
def create_guide_outline(self, state):
# This runs when get_user_input completes
# ...
```
이렇게 하면 애플리케이션에 명확하고 선언적인 구조가 만들어집니다.
### 3. 상태 관리
flow는 단계 간 상태를 유지하여 데이터를 쉽게 공유할 수 있습니다:
```python
class GuideCreatorState(BaseModel):
topic: str = ""
audience_level: str = ""
guide_outline: GuideOutline = None
sections_content: Dict[str, str] = {}
```
이 방식은 flow 전반에 걸쳐 데이터를 추적하고 변환하는 타입 안전(type-safe)한 방법을 제공합니다.
### 4. Crew 통합
Flow는 복잡한 협업 작업을 위해 crew와 원활하게 통합될 수 있습니다:
```python
result = ContentCrew().crew().kickoff(inputs={
"section_title": section.title,
# ...
})
```
이를 통해 애플리케이션의 각 부분에 적합한 도구를 사용할 수 있습니다. 단순한 작업에는 직접적인 LLM 호출을, 복잡한 협업에는 crew를 사용할 수 있습니다.
## 다음 단계
이제 첫 번째 flow를 구축했으니 다음을 시도해 볼 수 있습니다:
1. 더 복잡한 flow 구조와 패턴을 실험해 보세요.
2. `@router()`를 사용하여 flow에서 조건부 분기를 만들어 보세요.
3. 더 복잡한 병렬 실행을 위해 `and_` 및 `or_` 함수를 탐색해 보세요.
4. flow를 외부 API, 데이터베이스 또는 사용자 인터페이스에 연결해 보세요.
5. 여러 전문화된 crew를 하나의 flow에서 결합해 보세요.
| 구성 요소 | 설명 | 주요 특징 |
| :------------ | :-------------: | :----------------------------------------------------------------------------------- |
| **Crew** | 최상위 조직 | • AI agent 팀 관리
| 구성 요소 | 설명 | 주요 기능 |
| :--------------- | :-------------------------: | :--------------------------------------------------------------------------------- |
| **Flow** | 구조화된 workflow orchestration | • 실행 경로 관리
## 모범 사례
1. **이미지 생성 프롬프트를 구체적으로 작성하세요**. 그래야 최상의 결과를 얻을 수 있습니다.
2. **생성 시간을 고려하세요** - 이미지 생성에는 시간이 걸릴 수 있으므로 작업 계획에 이를 반영하세요.
3. **사용 정책을 준수하세요** - 이미지를 생성할 때 항상 OpenAI의 사용 정책을 준수해야 합니다.
## 문제 해결
1. **API 접근 확인** - OpenAI API 키가 DALL-E에 접근 권한이 있는지 확인하세요.
2. **버전 호환성** - 최신 버전의 crewAI와 crewai-tools를 사용하고 있는지 확인하세요.
3. **도구 구성** - DALL-E 도구가 agent의 도구 목록에 올바르게 추가되어 있는지 확인하세요.
# 도구 출력 결과로 강제 지정하기
Source: https://docs.crewai.com/ko/learn/force-tool-output-as-result
CrewAI에서 에이전트의 작업에서 도구 출력을 결과로 강제 지정하는 방법을 알아봅니다.
## 소개
CrewAI에서는 도구의 출력을 에이전트 작업의 결과로 강제로 사용할 수 있습니다.\
이 기능은 작업 실행 중에 에이전트가 출력을 수정하지 못하도록 하고, 도구의 출력이 반드시 캡처되어 작업 결과로 반환되도록 보장하고 싶을 때 유용합니다.
## 도구 출력을 결과로 강제 지정하기
도구의 출력을 에이전트 작업의 결과로 강제 지정하려면, 에이전트에 도구를 추가할 때 `result_as_answer` 매개변수를 `True`로 설정해야 합니다.\
이 매개변수는 도구의 출력이 에이전트에 의해 수정되지 않고 작업 결과로 캡처되어 반환되도록 보장합니다.
다음은 에이전트 작업의 결과로 도구 출력을 강제 지정하는 방법의 예시입니다:
```python Code
from crewai.agent import Agent
from my_tool import MyCustomTool
# Create a coding agent with the custom tool
coding_agent = Agent(
role="Data Scientist",
goal="Produce amazing reports on AI",
backstory="You work with data and AI",
tools=[MyCustomTool(result_as_answer=True)],
)
# Assuming the tool's execution and result population occurs within the system
task_result = coding_agent.execute_task(task)
```
## 워크플로우 실행
**고급 테스트 기능:**
* **다중 모델 비교**: 동일한 작업과 입력에 대해 여러 LLM을 동시에 테스트할 수 있습니다. GPT-4o, Claude, Llama, Groq, Cerebras 및 기타 선도적인 모델의 성능을 병렬로 비교하여 특정 사용 사례에 가장 적합한 모델을 식별할 수 있습니다.
* **통계적 엄밀성**: 일관된 입력값으로 여러 번 테스트를 구성하여 신뢰성과 성능 편차를 측정할 수 있습니다. 이를 통해 단순히 잘하는 모델이 아닌, 여러 번 실행해도 안정적으로 동작하는 모델을 식별할 수 있습니다.
* **실제 환경 검증**: 합성 벤치마크가 아닌 실제 crew 입력값과 시나리오를 사용할 수 있습니다. 플랫폼을 통해 산업 환경, 회사 정보, 실제 사용 사례 등 특정 맥락에 맞는 테스트가 가능하여 보다 정확한 평가가 이뤄집니다.
* **종합 분석 도구**: 테스트한 모든 모델의 세부 성능 지표, 실행 시간, 비용 분석을 확인할 수 있습니다. 이로써 모델의 일반적인 평판이나 이론적 능력에 기대지 않고 데이터 기반으로 의사결정을 내릴 수 있습니다.
* **팀 협업**: 팀 내에서 테스트 결과와 모델 성능 데이터를 공유할 수 있어, 협업적 의사결정과 프로젝트 전반에서 일관된 모델 선택 전략을 수립할 수 있습니다.
지금 [app.crewai.com](https://app.crewai.com)에서 시작하세요!
**확인:** [실시간 추적 예시 보기](https://app.langdb.ai/sharing/threads/3becbfed-a1be-ae84-ea3c-4942867a3e22)
## 기능
### AI 게이트웨이 기능
* **350개 이상의 LLM 접근**: 단일 통합을 통해 모든 주요 언어 모델에 연결
* **가상 모델**: 특정 매개변수와 라우팅 규칙으로 맞춤형 모델 구성 생성
* **가상 MCP**: 에이전트 간 향상된 통신을 위해 MCP(Model Context Protocol) 시스템과의 호환성 및 통합 지원
* **가드레일**: 에이전트 행동에 대한 안전 조치 및 컴플라이언스 제어 구현
### 가시성 및 추적
* **자동 추적**: 단일 `init()` 호출로 모든 CrewAI 상호작용을 캡처
* **엔드-투-엔드 가시성**: 에이전트 워크플로우를 시작부터 끝까지 모니터링
* **도구 사용 추적**: 에이전트가 사용하는 도구와 그 결과를 추적
* **모델 호출 모니터링**: LLM 상호작용에 대한 상세한 인사이트 제공
* **성능 분석**: 지연 시간, 토큰 사용량 및 비용 모니터링
* **디버깅 지원**: 문제 해결을 위한 단계별 실행
* **실시간 모니터링**: 라이브 트레이스 및 메트릭 대시보드
## 설치 안내
### 볼 수 있는 내용
* **에이전트 상호작용**: 에이전트 대화 및 작업 인계의 전체 흐름
* **도구 사용**: 호출된 도구, 입력값 및 출력값
* **모델 호출**: 프롬프트 및 응답과 함께하는 상세 LLM 상호작용
* **성능 지표**: 지연 시간, 토큰 사용량, 비용 추적
* **실행 타임라인**: 전체 워크플로우의 단계별 보기
## 문제 해결
### 일반적인 문제
* **추적이 나타나지 않음**: `init()`이 CrewAI 임포트 이전에 호출되었는지 확인하세요
* **인증 오류**: LangDB API 키와 프로젝트 ID를 확인하세요
## 리소스
## 설정 지침
필터 및 샘플링을 기준으로 UI에서 캡처된 로그를 자동으로 평가할 수 있습니다.
로그의 품질을 평가하고, 사람의 평가 또는 등급을 이용해 로그를 검토할 수 있습니다.
트레이스 또는 로그의 모든 컴포넌트를 평가하여 에이전트의 행동에 대한 통찰을 얻을 수 있습니다.
## 문제 해결
### 흔한 문제
* **추적(trace)가 나타나지 않음**: API 키와 저장소 ID가 올바른지 확인하세요.
* crew를 실행하기 ***전에*** 반드시 **`instrument_crewai()`를 호출**했는지 확인하세요. 이 함수가 로깅 훅(logging hook)을 올바르게 초기화합니다.
* 내부 오류를 드러내기 위해 `instrument_crewai()` 호출 시 `debug=True`로 설정하세요:
```python
instrument_crewai(logger, debug=True)
```
* 에이전트에서 상세 로그를 캡처하기 위해 `verbose=True`로 설정하세요:
```python
agent = CrewAgent(..., verbose=True)
```
* `instrument_crewai()`가 에이전트를 생성하거나 실행하기 **전에** 호출되는지 다시 한 번 확인하세요. 너무 당연해 보일 수 있지만, 자주 발생하는 실수입니다.
## 리소스
### 기능
* **트레이싱 대시보드**: crewAI 에이전트의 활동을 입력값, 출력값, 스팬의 메타데이터와 함께 자세한 대시보드로 모니터링할 수 있습니다.
* **자동 트레이싱**: 완전 자동화된 crewAI 통합 기능으로, `mlflow.crewai.autolog()`를 실행하여 활성화할 수 있습니다.
* **약간의 노력만으로 수동 추적 계측**: 데코레이터, 함수 래퍼, 컨텍스트 매니저 등 MLflow의 고수준 fluent API를 통해 추적 계측을 커스터마이즈할 수 있습니다.
* **OpenTelemetry 호환성**: MLflow Tracing은 OpenTelemetry Collector로 트레이스를 내보내는 것을 지원하며, 이를 통해 Jaeger, Zipkin, AWS X-Ray 등 다양한 백엔드로 트레이스를 내보낼 수 있습니다.
* **에이전트 패키징 및 배포**: crewAI 에이전트를 다양한 배포 대상으로 추론 서버에 패키징 및 배포할 수 있습니다.
* **LLM을 안전하게 호스팅**: 여러 공급자의 LLM을 MFflow 게이트웨이를 통해 하나의 통합 엔드포인트에서 호스팅할 수 있습니다.
* **평가**: 편리한 API `mlflow.evaluate()`를 사용하여 다양한 지표로 crewAI 에이전트를 평가할 수 있습니다.
## 설치 안내
CrewAI 트레이스를 보기 위한 최고의 UX. 원하는 곳 어디든 댓글을 남기세요. AI를 활용해 디버깅할 수 있습니다.
## 핵심 기능
* **Trace Viewer**: 사고, 도구, 결정을 순서대로 추적
* **인라인 댓글**: 모든 trace 단계에서 팀원을 태그
* **피드백 및 평가**: 출력물을 올바름 또는 틀림으로 표시
* **오류 하이라이팅**: API/도구 실패 자동 감지
* **작업 전환**: 댓글을 할당된 작업으로 변환
* **Ask the Trace (AI)**: Neatlogs AI 봇과 trace에서 채팅
* **공개 공유**: trace 링크를 커뮤니티에 게시
## CrewAI로 빠른 설정하기
### 기능
* **분석 대시보드**: 에이전트의 상태와 성능을 모니터링할 수 있는 대시보드를 통해 지표, 비용, 사용자 상호작용을 자세히 추적할 수 있습니다.
* **OpenTelemetry-네이티브 가시성 SDK**: Grafana, DataDog 등 기존 가시성 도구로 추적 및 지표를 전송할 수 있는 벤더 중립적 SDK를 제공합니다.
* **커스텀 및 파인튜닝 모델 비용 추적**: 정확한 예산 책정을 위해 커스텀 가격 파일을 사용하여 특정 모델의 비용 추정치를 맞춤화할 수 있습니다.
* **예외 모니터링 대시보드**: 모니터링 대시보드를 통해 일반적인 예외 및 오류를 추적하여 문제를 신속하게 찾아내고 해결할 수 있습니다.
* **컴플라이언스 및 보안**: 욕설 및 PII 유출과 같은 잠재적인 위협을 탐지합니다.
* **프롬프트 인젝션 탐지**: 잠재적인 코드 인젝션 및 비밀 유출을 식별합니다.
* **API 키 및 비밀 관리**: LLM API 키와 비밀을 중앙에서 안전하게 관리하여 안전하지 않은 관행을 방지합니다.
* **프롬프트 관리**: PromptHub을 사용하여 에이전트 프롬프트를 관리 및 버전 관리하고, 모든 에이전트에서 일관되고 쉽게 접근할 수 있습니다.
* **모델 플레이그라운드**: 배포 전에 CrewAI 에이전트에 사용할 다양한 모델을 테스트하고 비교할 수 있습니다.
## 설치 안내
Opik은 CrewAI 애플리케이션 개발의 모든 단계에서 포괄적인 지원을 제공합니다:
* **로그 트레이스 및 스팬**: 개발 및 프로덕션 시스템에서 LLM 호출과 애플리케이션 로직을 자동으로 추적하여 디버깅 및 분석이 가능합니다. 프로젝트 간 응답을 수동 또는 프로그램적으로 주석 달고, 조회하고, 비교할 수 있습니다.
* **LLM 애플리케이션 성능 평가**: 사용자 지정 테스트 세트로 평가하고, 내장된 평가 지표를 실행하거나 SDK 또는 UI에서 사용자만의 지표를 정의할 수 있습니다.
* **CI/CD 파이프라인 내 테스트**: PyTest 기반의 Opik LLM 단위 테스트로 신뢰할 수 있는 성능 기준선을 설정하세요. 프로덕션에서 연속 모니터링을 위한 온라인 평가도 실행할 수 있습니다.
* **프로덕션 데이터 모니터링 및 분석**: 프로덕션에서 보지 못한 데이터에 대한 모델의 성능을 이해하고, 새로운 개발 반복을 위한 데이터 세트를 생성할 수 있습니다.
## 설치
Comet은 호스팅된 Opik 플랫폼을 제공하거나, 로컬에서 플랫폼을 실행할 수도 있습니다.
호스팅 버전을 사용하려면 [무료 Comet 계정 만들기](https://www.comet.com/signup?utm_medium=github\&utm_source=crewai_docs) 후 API 키를 발급받으세요.
Opik 플랫폼을 로컬에서 실행하려면, [설치 가이드](https://www.comet.com/docs/opik/self-host/overview/)에서 자세한 정보를 확인하세요.
이 가이드에서는 CrewAI의 빠른 시작 예제를 사용합니다.
## 소개
Portkey는 CrewAI에 프로덕션 적합성을 위한 기능을 추가하여 실험적인 agent crew를 다음과 같이 견고한 시스템으로 전환합니다.
* **모든 agent 단계, 도구 사용, 상호작용에 대한 완전한 관찰 가능성**
* **내장된 신뢰성**: 폴백, 재시도, 로드 밸런싱 기능 제공
* **AI 비용 관리**를 위한 비용 추적 및 최적화
* **단일 통합을 통한 200개 이상의 LLM 접근**
* **agent의 행동을 안전하고 규정 준수로 유지하는 가드레일**
* **일관된 agent 성능을 위한 버전 관리되는 prompt**
### 설치 및 설정
Traces는 crew의 실행을 계층적으로 보여주며, LLM 호출, 도구 호출, 상태 전환의 순서를 확인할 수 있습니다.
```python
# Portkey에서 계층적 추적을 활성화하려면 trace_id를 추가하세요
portkey_llm = LLM(
model="gpt-4o",
base_url=PORTKEY_GATEWAY_URL,
api_key="dummy",
extra_headers=createHeaders(
api_key="YOUR_PORTKEY_API_KEY",
virtual_key="YOUR_OPENAI_VIRTUAL_KEY",
trace_id="unique-session-id" # 고유한 trace ID 추가
)
)
```
Portkey는 LLM과의 모든 상호작용을 로그로 남깁니다. 여기에는 다음이 포함됩니다:
* 전체 요청 및 응답 페이로드
* 지연 시간 및 토큰 사용량 지표
* 비용 계산
* 도구 호출 및 함수 실행
모든 로그는 메타데이터, trace ID, 모델 등으로 필터링할 수 있어 특정 crew 실행을 쉽게 디버깅할 수 있습니다.
Portkey는 사용자가 다음을 할 수 있도록 지원하는 내장 대시보드를 제공합니다:
* 모든 crew 실행에서 비용 및 토큰 사용량 추적
* 지연 시간, 성공률과 같은 성능 지표 분석
* agent workflow의 병목 지점 식별
* 서로 다른 crew 구성 및 LLM 비교
사용자는 모든 지표를 사용자 정의 메타데이터별로 필터링 및 세분화하여 특정 crew 유형, 사용자 그룹 또는 사용 사례를 분석할 수 있습니다.
CrewAI LLM 구성에 사용자 정의 메타데이터를 추가하여 강력한 필터링 및 세분화를 활성화할 수 있습니다:
```python
portkey_llm = LLM(
model="gpt-4o",
base_url=PORTKEY_GATEWAY_URL,
api_key="dummy",
extra_headers=createHeaders(
api_key="YOUR_PORTKEY_API_KEY",
virtual_key="YOUR_OPENAI_VIRTUAL_KEY",
metadata={
"crew_type": "research_crew",
"environment": "production",
"_user": "user_123", # 사용자 분석을 위한 특수 _user 필드
"request_source": "mobile_app"
}
)
)
```
이 메타데이터는 Portkey 대시보드에서 로그, trace, 지표를 필터링하는 데 사용될 수 있으며, 특정 crew 실행, 사용자 또는 환경을 분석할 수 있습니다.
이를 통해 다음이 가능합니다:
* 사용자별 비용 추적 및 예산 관리
* 개인화된 사용자 분석
* 팀 또는 조직 단위의 지표
* 환경별 모니터링(스테이징 vs. 프로덕션)
공식 CrewAI 문서
이 통합 구현에 대한 맞춤형 안내를 받아보세요
Weave는 CrewAI 애플리케이션 개발의 모든 단계에서 포괄적인 지원을 제공합니다:
* **트레이싱 및 모니터링**: LLM 호출과 애플리케이션 로직을 자동으로 추적하여 프로덕션 시스템을 디버그하고 분석
* **체계적인 반복**: prompt, 데이터셋, 모델을 개선하고 반복
* **평가**: 맞춤형 또는 사전 구축된 스코어러를 사용하여 agent 성능을 체계적으로 평가하고 향상
* **가드레일**: 콘텐츠 모더레이션과 prompt 안전성을 위한 사전 및 사후 보호조치로 agent를 보호
Weave는 CrewAI 애플리케이션의 트레이스를 자동으로 캡처하여 agent의 성능, 상호 작용 및 실행 흐름을 모니터링하고 분석할 수 있게 해줍니다. 이를 통해 더 나은 평가 데이터셋을 구축하고 agent 워크플로우를 최적화할 수 있습니다.
## 설치 안내
O Construtor Visual de Agentes permite:
* Configuração intuitiva de agentes com interfaces baseadas em formulários
* Testes e validação em tempo real
* Biblioteca de modelos com tipos de agentes pré-configurados
* Fácil personalização de atributos e comportamentos do agente
Com o Prompt Tracing você pode:
* Visualizar o histórico completo de todos os prompts enviados ao seu LLM
* Monitorar o uso de tokens e custos
* Depurar falhas de raciocínio dos agentes
* Compartilhar sequências de prompts com sua equipe
* Comparar diferentes estratégias de prompts
* Exportar rastreamentos para compliance e auditoria
Neste exemplo, o `second_method` é o último método a ser concluído, logo sua saída será a saída final do Flow.
O método `kickoff()` retorna essa saída, que é impressa no console. O método `plot()` irá gerar o arquivo HTML para visualizar o fluxo.
#### Acessando e Atualizando o Estado
Além de recuperar a saída final, você pode acessar e atualizar o estado dentro do seu Flow. O estado pode ser usado para armazenar e compartilhar dados entre diferentes métodos do Flow. Após a execução do Flow, você pode acessar o estado para recuperar informações adicionadas ou alteradas durante o processo.
Veja um exemplo de como atualizar e acessar o estado:
Neste exemplo, o estado é atualizado tanto por `first_method` quanto por `second_method`.
Após o término da execução, é possível acessar o estado final e observar as atualizações realizadas por esses métodos.
Ao garantir que a saída do método final seja retornada e oferecer acesso ao estado, o CrewAI Flows facilita a integração dos resultados dos seus workflows de IA em aplicações maiores,
além de permitir o gerenciamento e o acesso ao estado durante toda a execução do Flow.
## Gerenciamento de Estado em Flows
Gerenciar o estado de forma eficaz é fundamental para construir fluxos de trabalho de IA confiáveis e de fácil manutenção. O CrewAI Flows oferece mecanismos robustos para o gerenciamento de estado tanto não estruturado quanto estruturado,
permitindo que o desenvolvedor escolha a abordagem que melhor se adapta à sua aplicação.
### Gerenciamento de Estado Não Estruturado
No gerenciamento de estado não estruturado, todo o estado é armazenado no atributo `state` da classe `Flow`.
Essa abordagem oferece flexibilidade, permitindo que o desenvolvedor adicione ou modifique atributos do estado conforme necessário sem precisar definir um esquema rígido.
Mesmo com estados não estruturados, os flows do CrewAI geram e mantêm automaticamente um identificador único (UUID) para cada instância de estado.
```python Code
# (O código não é traduzido)
```
**Nota:** O campo `id` é gerado e preservado automaticamente durante toda a execução do flow. Não é necessário gerenciá-lo ou defini-lo manualmente, e ele permanecerá mesmo ao atualizar o estado com novos dados.
**Pontos-Chave:**
* **Flexibilidade:** É possível adicionar atributos dinamicamente ao `self.state` sem restrições pré-definidas.
* **Simplicidade:** Ideal para fluxos de trabalho diretos em que a estrutura do estado é mínima ou varia bastante.
### Gerenciamento de Estado Estruturado
No gerenciamento de estado estruturado, utilizam-se esquemas pré-definidos para garantir consistência e segurança de tipos em todo o workflow.
Ao usar modelos como o `BaseModel` da Pydantic, os desenvolvedores podem definir a forma exata do estado, melhorando a validação e fornecendo auto-complete nos ambientes de desenvolvimento.
Cada estado nos flows do CrewAI recebe automaticamente um identificador único (UUID) para ajudar no rastreamento e gerenciamento. Esse ID é gerado e mantido automaticamente pelo sistema de flows.
```python Code
# (O código não é traduzido)
```
**Pontos-Chave:**
* **Esquema Definido:** `ExampleState` deixa claro a estrutura do estado, aumentando a legibilidade e a manutenção do código.
* **Segurança de Tipos:** O uso da Pydantic garante que os atributos do estado tenham os tipos certos, reduzindo os erros em tempo de execução.
* **Auto-Completar:** IDEs conseguem oferecer auto-completar e checagem de erros, graças ao modelo definido do estado.
### Escolhendo entre Estado Não Estruturado e Estruturado
* **Use Estado Não Estruturado quando:**
* O estado do fluxo é simples ou altamente dinâmico.
* Flexibilidade é mais importante do que uma definição rígida do estado.
* Prototipagem rápida é necessária sem a sobrecarga de definição de esquemas.
* **Use Estado Estruturado quando:**
* O flow exige uma estrutura de estado bem definida e consistente.
* Segurança de tipos e validação são importantes para a confiabilidade da aplicação.
* É desejado usar recursos da IDE como auto-completar e checagem de tipos para uma melhor experiência de desenvolvimento.
Ao oferecer as duas opções de gerenciamento de estado, o CrewAI Flows permite que desenvolvedores criem fluxos de IA que sejam ao mesmo tempo flexíveis e robustos, atendendo a uma ampla variedade de requisitos de aplicação.
## Persistência de Flow
O decorador @persist permite a persistência automática do estado nos flows do CrewAI, garantindo que você mantenha o estado do flow entre reinicializações ou execuções diferentes do workflow. Esse decorador pode ser aplicado tanto ao nível de classe, quanto ao nível de método, oferecendo flexibilidade sobre como gerenciar a persistência do estado.
### Persistência no Nível de Classe
Quando aplicado no nível da classe, o decorador @persist garante a persistência automática de todos os estados dos métodos do flow:
```python
# (O código não é traduzido)
```
### Persistência no Nível de Método
Para um controle mais granular, você pode aplicar @persist em métodos específicos:
```python
# (O código não é traduzido)
```
### Como Funciona
1. **Identificação Única do Estado**
* Cada estado do flow recebe automaticamente um UUID único
* O ID é preservado entre atualizações do estado e chamadas de métodos
* Suporta tanto estados estruturados (Pydantic BaseModel) quanto não estruturados (dicionário)
2. **Backend SQLite Padrão**
* O SQLiteFlowPersistence é o backend de armazenamento padrão
* Os estados são salvos automaticamente em um banco de dados SQLite local
* O tratamento de erros é robusto, oferecendo mensagens claras caso ocorram falhas nas operações de banco de dados
3. **Tratamento de Erros**
* Mensagens de erro abrangentes para operações de banco de dados
* Validação automática do estado ao salvar e carregar
* Feedback claro quando houver problemas de persistência
### Considerações Importantes
* **Tipos de Estado**: São suportados tanto estados estruturados (Pydantic BaseModel) quanto não estruturados (dicionário)
* **ID Automático**: O campo `id` é adicionado automaticamente se não estiver presente
* **Recuperação de Estado**: Flows que falharem ou forem reiniciados podem recarregar automaticamente seu estado anterior
* **Implementação Personalizada**: Você pode fornecer sua própria implementação de FlowPersistence para necessidades de armazenamento especializadas
### Vantagens Técnicas
1. **Controle Preciso Através de Acesso de Baixo Nível**
* Acesso direto às operações de persistência para casos avançados
* Controle detalhado via decoradores de persistência no nível do método
* Inspeção de estado e recursos de depuração embutidos
* Visibilidade total das mudanças e operações de persistência do estado
2. **Maior Confiabilidade**
* Recuperação automática do estado após falhas no sistema ou reinicializações
* Atualizações de estado baseadas em transações para garantir integridade dos dados
* Mensagens de erro abrangentes e claras
* Validação robusta durante operações de salvar e carregar estado
3. **Arquitetura Extensível**
* Backend de persistência personalizável através da interface FlowPersistence
* Suporte para soluções de armazenamento especializadas além do SQLite
* Compatibilidade tanto com estados estruturados (Pydantic) quanto não estruturados (dict)
* Integração perfeita com os padrões de flow existentes no CrewAI
A arquitetura de persistência enfatiza precisão técnica e opções de personalização, permitindo que desenvolvedores mantenham controle total sobre o gerenciamento de estado enquanto se beneficiam dos recursos de confiabilidade integrados.
## Controle de Flow
### Lógica Condicional: `or`
A função `or_` nos flows permite escutar múltiplos métodos e acionar o método ouvinte quando qualquer um dos métodos especificados gerar uma saída.
Ao executar esse Flow, o método `logger` será acionado pela saída tanto do `start_method` quanto do `second_method`.
A função `or_` serve para escutar vários métodos e disparar o método ouvinte quando qualquer um emitir um resultado.
### Lógica Condicional: `and`
A função `and_` nos flows permite escutar múltiplos métodos e acionar o método ouvinte apenas quando todos os métodos especificados emitirem uma saída.
Ao executar esse Flow, o método `logger` só será disparado quando ambos `start_method` e `second_method` emitirem uma saída.
A função `and_` é usada para escutar vários métodos e acionar o método ouvinte apenas quando todas as condições forem atendidas.
### Router
O decorador `@router()` nos flows permite definir lógica de roteamento condicional baseada na saída de um método.
Você pode especificar diferentes rotas conforme a saída do método, permitindo controlar o fluxo de execução de forma dinâmica.
No exemplo, o `start_method` gera um valor booleano aleatório e armazena no estado.
O `second_method` usa o decorador `@router()` para decidir o roteamento conforme o valor booleano.
Se o valor for `True`, retorna `"success"`, senão retorna `"failed"`.
Os métodos `third_method` e `fourth_method` escutam a saída do `second_method` e executam com base no valor retornado.
Ao executar esse Flow, a saída será diferente dependendo do valor booleano aleatório gerado pelo `start_method`.
## Adicionando Agentes aos Flows
Os agentes podem ser integrados facilmente aos seus flows, oferecendo uma alternativa leve às crews completas quando você precisar executar tarefas simples e focadas. Veja um exemplo de como utilizar um agente em um flow para realizar uma pesquisa de mercado:
```python
# (O código não é traduzido)
```
Esse exemplo demonstra diversos recursos fundamentais do uso de agentes em flows:
1. **Saída Estruturada**: O uso de modelos Pydantic para definir o formato esperado da saída (`MarketAnalysis`) garante segurança de tipos e dados estruturados em todo o flow.
2. **Gerenciamento de Estado**: O estado do flow (`MarketResearchState`) mantém o contexto entre as etapas e armazena entradas e saídas.
3. **Integração de Ferramentas**: Os agentes podem usar ferramentas (como `WebsiteSearchTool`) para potencializar suas habilidades.
## Adicionando Crews aos Flows
Criar um flow com múltiplas crews no CrewAI é simples.
Você pode gerar um novo projeto CrewAI que já inclui toda a estrutura para criar um flow com várias crews executando o seguinte comando:
```bash
crewai create flow name_of_flow
```
Esse comando irá gerar um novo projeto CrewAI com a estrutura de pastas necessária. O projeto gerado inclui uma crew pré-criada chamada `poem_crew`, já funcional. Você pode usar essa crew como modelo, copiando, colando e editando para criar outras crews.
### Estrutura de Pastas
Após rodar o comando `crewai create flow name_of_flow`, você verá uma estrutura parecida com:
| Diretório/Arquivo | Descrição |
| :--------------------- | :--------------------------------------------------------- |
| `name_of_flow/` | Diretório raiz do flow. |
| ├── `crews/` | Contém diretórios para crews específicas. |
| │ └── `poem_crew/` | Diretório da "poem\_crew" com configurações e scripts. |
| │ ├── `config/` | Arquivos de configuração da "poem\_crew". |
| │ │ ├── `agents.yaml` | YAML que define os agentes da "poem\_crew". |
| │ │ └── `tasks.yaml` | YAML que define as tarefas da "poem\_crew". |
| │ ├── `poem_crew.py` | Script da funcionalidade da "poem\_crew". |
| ├── `tools/` | Ferramentas adicionais usadas no flow. |
| │ └── `custom_tool.py` | Implementação de ferramenta customizada. |
| ├── `main.py` | Script principal do flow. |
| ├── `README.md` | Descrição do projeto e instruções. |
| ├── `pyproject.toml` | Arquivo de configurações e dependências do projeto. |
| └── `.gitignore` | Arquivos e pastas a serem ignorados no controle de versão. |
### Construindo suas Crews
Na pasta `crews`, você pode definir múltiplas crews. Cada crew tem sua própria pasta, com arquivos de configuração e o arquivo de definição da crew. Por exemplo, a pasta `poem_crew` contém:
* `config/agents.yaml`: Define os agentes da crew.
* `config/tasks.yaml`: Define as tarefas da crew.
* `poem_crew.py`: Contém a definição da crew, incluindo agentes, tarefas, etc.
Você pode copiar, colar e editar a `poem_crew` para criar outras crews.
### Conectando Crews no `main.py`
No arquivo `main.py`, você cria seu flow e conecta as crews. É possível definir o fluxo usando a classe `Flow` e os decoradores `@start` e `@listen` para definir a ordem de execução.
Veja um exemplo de como conectar a `poem_crew` no arquivo `main.py`:
```python Code
# (O código não é traduzido)
```
Neste exemplo, a classe `PoemFlow` define um fluxo que gera a quantidade de frases, usa a `PoemCrew` para gerar um poema e, depois, salva o poema em um arquivo. O flow inicia com o método `kickoff()`, e o gráfico é gerado pelo método `plot()`.
### Executando o Flow
(Opcional) Antes de rodar o flow, instale as dependências executando:
```bash
crewai install
```
Após instalar as dependências, ative o ambiente virtual com:
```bash
source .venv/bin/activate
```
Com o ambiente ativado, execute o flow usando um dos comandos:
```bash
crewai flow kickoff
```
ou
```bash
uv run kickoff
```
O flow será executado, e você verá a saída no console.
## Plotando Flows
Visualizar seus fluxos de trabalho de IA proporciona insights valiosos sobre a estrutura e os caminhos de execução dos flows. O CrewAI oferece uma ferramenta de visualização poderosa que permite gerar plots interativos dos flows, facilitando o entendimento e a otimização dos workflows de IA.
### O que são Plots?
No CrewAI, plots são representações gráficas dos fluxos de trabalho de IA. Eles mostram as tarefas, suas conexões e o fluxo de dados entre elas. Essa visualização ajuda a compreender a sequência de operações, identificar gargalos e garantir que a lógica do workflow está alinhada com o esperado.
### Como Gerar um Plot
O CrewAI oferece duas formas práticas de gerar plots dos seus flows:
#### Opção 1: Usando o método `plot()`
Se estiver trabalhando diretamente com uma instância do flow, basta chamar o método `plot()` do objeto. Isso criará um arquivo HTML com o plot interativo do seu flow.
```python Code
# (O código não é traduzido)
```
Esse comando gera um arquivo chamado `my_flow_plot.html` no diretório atual. Abra esse arquivo em um navegador para visualizar o plot interativo.
#### Opção 2: Usando a Linha de Comando
Em projetos CrewAI estruturados, é possível gerar um plot pela linha de comando. Isso é útil para projetos maiores, onde você deseja visualizar toda a configuração do flow.
```bash
crewai flow plot
```
O comando gera um arquivo HTML com o plot do flow, semelhante ao método `plot()`. Basta abrir o arquivo no navegador para explorar o workflow.
### Entendendo o Plot
O plot gerado mostra nós representando as tarefas do seu flow, com setas indicando o fluxo de execução. A visualização é interativa, permitindo zoom, navegação e detalhes ao passar o mouse nos nós.
Ao visualizar seus flows, você tem clareza do formato do workflow, facilitando debug, otimização e comunicação dos seus processos de IA para outras pessoas.
### Conclusão
A plotagem dos flows é um recurso poderoso do CrewAI para aprimorar o design e o gerenciamento de fluxos de IA complexos. Usando o método `plot()` ou a linha de comando, você obtém uma visão visual dos workflows, benefício tanto para desenvolvimento quanto para apresentação.
## Próximos Passos
Se você deseja explorar exemplos adicionais de flows, acompanhe alguns exemplos em nosso repositório de exemplos. Aqui estão quatro sugestões específicas de flows, cada uma demonstrando casos de uso distintos para você escolher conforme seu problema:
1. **Email Auto Responder Flow**: Este exemplo demonstra um loop infinito, onde um job de background roda continuamente automatizando respostas de email. É ideal para tarefas rotineiras sem intervenção manual. [Ver Exemplo](https://github.com/crewAIInc/crewAI-examples/tree/main/email_auto_responder_flow)
2. **Lead Score Flow**: Destaca como adicionar feedback humano e manipular diferentes ramos condicionais usando router. Um ótimo aprendizado para workflows com decisão dinâmica e supervisão humana. [Ver Exemplo](https://github.com/crewAIInc/crewAI-examples/tree/main/lead-score-flow)
3. **Write a Book Flow**: Exemplo ideal para encadear múltiplas crews, onde a saída de uma é usada por outra. Uma crew faz um sumário do livro inteiro, outra gera capítulos... Tudo conectado para entregar um livro completo. Perfeito para processos longos e coordenados. [Ver Exemplo](https://github.com/crewAIInc/crewAI-examples/tree/main/write_a_book_with_flows)
4. **Meeting Assistant Flow**: Demonstra como transmitir um evento para desencadear múltiplas ações posteriores. Exemplo: ao finalizar uma reunião, atualizar um Trello, enviar mensagem no Slack e salvar resultados ao mesmo tempo. Indicado para gerenciamento completo de tarefas e notificações. [Ver Exemplo](https://github.com/crewAIInc/crewAI-examples/tree/main/meeting_assistant_flow)
Explore esses exemplos para descobrir como aproveitar CrewAI Flows em diferentes contextos – desde automação de tarefas repetitivas até o gerenciamento de processos dinâmicos com decisões e feedback humano.
Além disso, confira nosso vídeo no YouTube sobre como utilizar flows no CrewAI abaixo!
## Executando Flows
Existem duas formas de executar um flow:
### Usando a API do Flow
Você pode executar um flow programaticamente criando uma instância da sua classe de flow e chamando o método `kickoff()`:
```python
# Exemplo de execução de flow em português
flow = ExemploFlow()
resultado = flow.kickoff()
```
### Usando a CLI
A partir da versão 0.103.0, é possível executar flows usando o comando `crewai run`:
```shell
crewai run
```
O comando detecta automaticamente se seu projeto é um flow (com base na configuração `type = "flow"` no pyproject.toml) e executa conforme o esperado. Esse é o método recomendado para executar flows pelo terminal.
Por compatibilidade retroativa, também é possível usar:
```shell
crewai flow kickoff
```
No entanto, o comando `crewai run` é agora o preferido, pois funciona tanto para crews quanto para flows.
# Knowledge
Source: https://docs.crewai.com/pt-BR/concepts/knowledge
O que é knowledge em CrewAI e como usá-lo.
## Visão Geral
Knowledge no CrewAI é um sistema poderoso que permite que agentes de IA acessem e utilizem fontes de informação externas durante suas tarefas.
Pense nisso como dar aos seus agentes uma biblioteca de referência que eles podem consultar enquanto trabalham.
stop, basta omiti-lo na chamada do LLM:
```python
from crewai import LLM
import os
os.environ["OPENAI_API_KEY"] = "
O Construtor Visual de Tarefas permite:
* Criação de tarefas via arrastar-e-soltar
* Visualização de dependências e fluxo de tarefas
* Testes e validações em tempo real
* Fácil compartilhamento e colaboração
## Integrações Suportadas
### **Comunicação & Colaboração**
* **Gmail** - Gerencie e-mails e rascunhos
* **Slack** - Notificações e alertas do workspace
* **Microsoft** - Integração com Office 365 e Teams
### **Gerenciamento de Projetos**
* **Jira** - Rastreamento de issues e gerenciamento de projetos
* **ClickUp** - Gerenciamento de tarefas e produtividade
* **Asana** - Coordenação de tarefas e projetos de equipe
* **Notion** - Gerenciamento de páginas e bases de dados
* **Linear** - Gerenciamento de projetos de software e bugs
* **GitHub** - Gerenciamento de repositórios e issues
### **Gestão de Relacionamento com o Cliente**
* **Salesforce** - Gerenciamento de contas e oportunidades de CRM
* **HubSpot** - Gestão de pipeline de vendas e contatos
* **Zendesk** - Administração de chamados de suporte ao cliente
### **Negócios & Finanças**
* **Stripe** - Processamento de pagamentos e gerenciamento de clientes
* **Shopify** - Gestão de loja de e-commerce e produtos
### **Produtividade & Armazenamento**
* **Google Sheets** - Sincronização de dados de planilhas
* **Google Calendar** - Gerenciamento de eventos e agendas
* **Box** - Armazenamento de arquivos e gerenciamento de documentos
e mais estão por vir!
## Pré-requisitos
Antes de usar as Integrações de Autenticação, certifique-se de que você possui:
* Uma conta [CrewAI Enterprise](https://app.crewai.com). Você pode começar com uma avaliação gratuita.
## Configurando Integrações
### 1. Conecte sua Conta
1. Acesse o [CrewAI Enterprise](https://app.crewai.com)
2. Vá até a aba **Integrações** - [https://app.crewai.com/crewai\_plus/connectors](https://app.crewai.com/crewai_plus/connectors)
3. Clique em **Conectar** no serviço desejado na seção Integrações de Autenticação
4. Complete o fluxo de autenticação OAuth
5. Conceda as permissões necessárias para seu caso de uso
6. Pronto! Obtenha seu Token Enterprise do [CrewAI Enterprise](https://app.crewai.com) na aba **Integration**
### 2. Instale as Ferramentas de Integração
Tudo o que você precisa é da versão mais recente do pacote `crewai-tools`.
```bash
uv add crewai-tools
```
## Exemplos de Uso
### Uso Básico
### Implantações com Escopo para organizações multiusuário
Você pode implantar seu crew e associar cada integração a um usuário específico. Por exemplo, um crew que se conecta ao Google pode usar a conta do Gmail de um usuário específico.
### Precisa de Ajuda?
## Usuários e Funções
Cada membro da sua workspace possui uma função, que determina o acesso aos recursos.
Você pode:
* Usar funções pré-definidas (Owner, Member)
* Criar funções personalizadas com permissões específicas
* Atribuir funções a qualquer momento no painel de configurações
A configuração de usuários e funções é feita em Settings → Roles.
## Acessando os Traces
### 2. Tarefas & Agentes
Esta seção mostra todas as tarefas e agentes que fizeram parte da execução do crew:
* Nome da tarefa e atribuição do agente
* Agentes e LLMs usados em cada tarefa
* Status (concluído/falhou)
* Tempo de execução individual da tarefa
### 3. Saída Final
Exibe o resultado final produzido pelo crew após a conclusão de todas as tarefas.
### 4. Linha do Tempo da Execução
Uma representação visual de quando cada tarefa começou e terminou, ajudando a identificar gargalos ou padrões de execução paralela.
### 5. Visão Detalhada da Tarefa
Ao clicar em uma tarefa específica na linha do tempo ou na lista de tarefas, você verá:
* **Task Key**: Identificador único da tarefa
* **Task ID**: Identificador técnico no sistema
* **Status**: Estado atual (concluída/em execução/falhou)
* **Agente**: Qual agente executou a tarefa
* **LLM**: Modelo de linguagem usado nesta tarefa
* **Início/Fim**: Quando a tarefa foi iniciada e concluída
* **Tempo de Execução**: Duração desta tarefa específica
* **Descrição da Tarefa**: O que o agente foi instruído a fazer
* **Expected Output**: Qual formato de saída foi solicitado
* **Input**: Qualquer entrada fornecida a essa tarefa vinda de tarefas anteriores
* **Output**: O resultado real produzido pelo agente
## Usando Traces para Depuração
Traces são indispensáveis para solucionar problemas nos seus crews:
Esta visualização mostra todas as integrações de trigger disponíveis para sua implantação, junto com seus status de conexão atuais.
### Habilitando e Desabilitando Triggers
Cada trigger pode ser facilmente habilitado ou desabilitado usando o botão de alternância:
* **Habilitado (alternância azul)**: O trigger está ativo e executará automaticamente sua implantação quando os eventos especificados ocorrerem
* **Desabilitado (alternância cinza)**: O trigger está inativo e não responderá a eventos
Simplesmente clique na alternância para mudar o estado do trigger. As alterações entram em vigor imediatamente.
### Monitorando Execuções de Trigger
Acompanhe o desempenho e histórico de suas execuções acionadas:
## Construindo Automação
Antes de construir sua automação, é útil entender a estrutura dos payloads de trigger que suas crews e flows receberão.
### Repositório de Amostras de Payload
Mantemos um repositório abrangente com amostras de payload de várias fontes de trigger para ajudá-lo a construir e testar suas automações:
**🔗 [Amostras de Payload de Trigger CrewAI Enterprise](https://github.com/crewAIInc/crewai-enterprise-trigger-payload-samples)**
Este repositório contém:
* **Exemplos reais de payload** de diferentes fontes de trigger (Gmail, Google Drive, etc.)
* **Documentação da estrutura de payload** mostrando o formato e campos disponíveis
### Triggers com Crew
Suas definições de crew existentes funcionam perfeitamente com triggers, você só precisa ter uma tarefa para analisar o payload recebido:
```python
@CrewBase
class MinhaCrewAutomatizada:
@agent
def pesquisador(self) -> Agent:
return Agent(
config=self.agents_config['pesquisador'],
)
@task
def analisar_payload_trigger(self) -> Task:
return Task(
config=self.tasks_config['analisar_payload_trigger'],
agent=self.pesquisador(),
)
@task
def analisar_conteudo_trigger(self) -> Task:
return Task(
config=self.tasks_config['analisar_dados_trigger'],
agent=self.pesquisador(),
)
```
A crew receberá automaticamente e pode acessar o payload do trigger através dos mecanismos de contexto padrão do CrewAI.
### Integração com Flows
Para flows, você tem mais controle sobre como os dados do trigger são tratados:
#### Acessando Payload do Trigger
Todos os métodos `@start()` em seus flows aceitarão um parâmetro adicional chamado `crewai_trigger_payload`:
```python
from crewai.flow import Flow, start, listen
class MeuFlowAutomatizado(Flow):
@start()
def lidar_com_trigger(self, crewai_trigger_payload: dict = None):
"""
Este método start pode receber dados do trigger
"""
if crewai_trigger_payload:
# Processa os dados do trigger
trigger_id = crewai_trigger_payload.get('id')
dados_evento = crewai_trigger_payload.get('payload', {})
# Armazena no estado do flow para uso por outros métodos
self.state.trigger_id = trigger_id
self.state.trigger_type = dados_evento
return dados_evento
# Lida com execução manual
return None
@listen(lidar_com_trigger)
def processar_dados(self, dados_trigger):
"""
Processa os dados do trigger
"""
# ... processa o trigger
```
#### Acionando Crews a partir de Flows
Ao iniciar uma crew dentro de um flow que foi acionado, passe o payload do trigger conforme ele:
```python
@start()
def delegar_para_crew(self, crewai_trigger_payload: dict = None):
"""
Delega processamento para uma crew especializada
"""
crew = MinhaCrewEspecializada()
# Passa o payload do trigger para a crew
resultado = crew.crew().kickoff(
inputs={
'parametro_personalizado': "valor_personalizado",
'crewai_trigger_payload': crewai_trigger_payload
},
)
return resultado
```
## Solução de Problemas
**Trigger não está sendo disparado:**
* Verifique se o trigger está habilitado
* Verifique o status de conexão da integração
**Falhas de execução:**
* Verifique os logs de execução para detalhes do erro
* Se você está desenvolvendo, certifique-se de que as entradas incluem o parâmetro `crewai_trigger_payload` com o payload correto
Os triggers de automação transformam suas implantações CrewAI em sistemas responsivos orientados por eventos que podem se integrar perfeitamente com seus processos de negócio e ferramentas existentes.
# Configuração do Azure OpenAI
Source: https://docs.crewai.com/pt-BR/enterprise/guides/azure-openai-setup
Configure o Azure OpenAI com o Crew Studio para conexões empresariais de LLM
Este guia orienta você na conexão do Azure OpenAI com o Crew Studio para operações de IA empresarial sem interrupções.
## Processo de Configuração
Após a conclusão, você verá:
* A URL exclusiva do seu crew
* Um Bearer token para proteger sua API crew
* Um botão "Delete" caso precise remover a implantação
Com o Crew Studio, você pode:
* Conversar com o Crew Assistant para descrever seu problema
* Gerar automaticamente agentes e tarefas
* Selecionar as ferramentas apropriadas
* Configurar os inputs necessários
* Gerar código para download e personalização
* Fazer deploy diretamente na plataforma CrewAI Enterprise
## Etapas de Configuração
Antes de começar a usar o Crew Studio, você precisa configurar suas conexões LLM:
* Configure quaisquer ações adicionais necessárias
* Revise as etapas do seu workflow para garantir que tudo está configurado corretamente
* Ative o workflow
### Passo 2: Iniciar Execução
Na página de detalhes do seu crew, você tem duas opções para iniciar uma execução:
#### Opção A: Kickoff Rápido
1. Clique no link `Kickoff` na seção Test Endpoints
2. Insira os parâmetros de entrada necessários para seu crew no editor JSON
3. Clique no botão `Send Request`
#### Opção B: Usando a Interface Visual
1. Clique na aba `Run` na página de detalhes do crew
2. Insira os inputs necessários nos campos do formulário
3. Clique no botão `Run Crew`
### Passo 3: Monitorar o Progresso da Execução
Após iniciar a execução:
1. Você receberá uma resposta contendo um `kickoff_id` - **copie este ID**
2. Esse ID é fundamental para o acompanhamento da sua execução
### Passo 4: Verificar o Status da Execução
Para monitorar o andamento da sua execução:
1. Clique no endpoint "Status" na seção Test Endpoints
2. Cole o `kickoff_id` no campo indicado
3. Clique no botão "Get Status"
A resposta de status mostrará:
* Estado atual da execução (`running`, `completed`, etc.)
* Detalhes sobre quais tarefas estão em andamento
* Quaisquer outputs gerados até o momento
### Passo 5: Visualizar Resultados Finais
Quando a execução for concluída:
1. O status mudará para `completed`
2. Você poderá visualizar todos os resultados e outputs da execução
3. Para uma visão mais detalhada, acesse a aba `Executions` na página de detalhes do crew
## Método 2: Usando a API
Você também pode iniciar crews programaticamente usando a REST API do CrewAI Enterprise.
### Autenticação
Todas as requisições à API exigem um bearer token para autenticação:
```bash
curl -H "Authorization: Bearer YOUR_CREW_TOKEN" https://your-crew-url.crewai.com
```
Seu bearer token está disponível na aba Status na página de detalhes do seu crew.
### Verificando o Status do Crew
Antes de executar operações, você pode verificar se seu crew está funcionando corretamente:
```bash
curl -H "Authorization: Bearer YOUR_CREW_TOKEN" https://your-crew-url.crewai.com
```
Uma resposta de sucesso trará uma mensagem indicando que o crew está operacional:
```
Healthy%
```
### Passo 1: Recuperar Entradas Necessárias
Primeiro, descubra quais entradas seu crew exige:
```bash
curl -X GET \
-H "Authorization: Bearer YOUR_CREW_TOKEN" \
https://your-crew-url.crewai.com/inputs
```
A resposta será um objeto JSON contendo um array de parâmetros de entrada obrigatórios, por exemplo:
```json
{"inputs":["topic","current_year"]}
```
Este exemplo mostra que este crew em particular requer dois inputs: `topic` e `current_year`.
### Passo 2: Iniciar Execução
Inicie a execução fornecendo os inputs obrigatórios:
```bash
curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_CREW_TOKEN" \
-d '{"inputs": {"topic": "AI Agent Frameworks", "current_year": "2025"}}' \
https://your-crew-url.crewai.com/kickoff
```
A resposta incluirá um `kickoff_id` que você precisará para o acompanhamento:
```json
{"kickoff_id":"abcd1234-5678-90ef-ghij-klmnopqrstuv"}
```
### Passo 3: Verificar Status da Execução
Acompanhe o progresso da execução usando o kickoff\_id:
```bash
curl -X GET \
-H "Authorization: Bearer YOUR_CREW_TOKEN" \
https://your-crew-url.crewai.com/status/abcd1234-5678-90ef-ghij-klmnopqrstuv
```
## Gerenciando Execuções
### Execuções de Longa Duração
Para execuções que possam demandar mais tempo:
1. Considere implementar um mecanismo de polling para verificar status periodicamente
2. Utilize webhooks (se disponíveis) para notificação quando a execução for concluída
3. Implemente tratamento de erros para possíveis timeouts
### Contexto da Execução
O contexto da execução inclui:
* Inputs fornecidos no momento do kickoff
* Variáveis de ambiente configuradas durante o deploy
* Qualquer estado mantido entre as tarefas
### Depuração de Execuções com Falha
Se uma execução falhar:
1. Verifique a aba "Executions" para logs detalhados
2. Avalie a aba "Traces" para detalhes passo a passo da execução
3. Procure por respostas LLM e uso de ferramentas nos detalhes do trace
## Próximos Passos
* Personalize o estilo do componente para combinar com o design da sua aplicação
* Adicione props adicionais para configuração
* Integre com o gerenciamento de estado da sua aplicação
* Adicione tratamento de erros e estados de carregamento
# Trigger Salesforce
Source: https://docs.crewai.com/pt-BR/enterprise/guides/salesforce-trigger
Dispare equipes CrewAI a partir de fluxos de trabalho do Salesforce para automação de CRM
A CrewAI Enterprise pode ser acionada a partir do Salesforce para automatizar fluxos de trabalho de gestão de relacionamento com o cliente e aprimorar suas operações de vendas.
## Visão Geral
O Salesforce é uma das principais plataformas de gestão de relacionamento com o cliente (CRM), que ajuda empresas a otimizar operações de vendas, atendimento e marketing. Ao configurar triggers da CrewAI a partir do Salesforce, você pode:
* Automatizar a classificação e qualificação de leads
* Gerar materiais de vendas personalizados
* Aprimorar o atendimento ao cliente com respostas baseadas em IA
* Otimizar análise e relatórios de dados
## Demonstração
## Primeiros Passos
Para configurar triggers no Salesforce:
1. **Contato com o Suporte**: Entre em contato com o suporte da CrewAI Enterprise para obter assistência na configuração dos triggers no Salesforce
2. **Revisar Requisitos**: Certifique-se de possuir as permissões necessárias no Salesforce e acesso à API
3. **Configurar Conexão**: Trabalhe com a equipe de suporte para estabelecer a conexão entre a CrewAI e sua instância do Salesforce
4. **Testar Triggers**: Verifique se os triggers funcionam corretamente para os seus casos de uso específicos
## Casos de Uso
Cenários comuns de uso de triggers Salesforce + CrewAI incluem:
* **Processamento de Leads**: Analisar e classificar leads recebidos automaticamente
* **Geração de Propostas**: Criar propostas personalizadas com base nos dados das oportunidades
* **Insights de Clientes**: Gerar relatórios de análise a partir do histórico de interações com clientes
* **Automação de Follow-up**: Criar mensagens de follow-up e recomendações personalizadas
## Próximos Passos
Para instruções detalhadas de configuração e opções avançadas, entre em contato com o suporte da CrewAI Enterprise, que pode fornecer orientações personalizadas para o seu ambiente Salesforce e necessidades de negócio.
# Slack Trigger
Source: https://docs.crewai.com/pt-BR/enterprise/guides/slack-trigger
Acione crews do CrewAI diretamente do Slack usando comandos de barra
Este guia explica como iniciar um crew diretamente do Slack usando triggers do CrewAI.
## Pré-requisitos
* Trigger do CrewAI para Slack instalado e conectado ao seu workspace do Slack
* Pelo menos um crew configurado no CrewAI
## Etapas de Configuração
Verifique se o Slack está listado e conectado.
* Pressione Enter ou selecione a opção "**Kickoff crew**". Uma caixa de diálogo intitulada "**Kickoff an AI Crew**" aparecerá.
* Se o seu crew exigir algum input, clique no botão "**Add Inputs**" para fornecê-los.
* O crew começará a ser executado e você verá os resultados no canal do Slack.
* Clique no botão `Add Role` para adicionar uma nova função.
* Insira os detalhes e as permissões da função e clique no botão `Create Role` para criar a função.
* Após o membro aceitar o convite, você poderá adicionar uma função a ele.
* Volte para a aba `Roles`
* Vá até o membro ao qual deseja adicionar uma função e, na coluna `Role`, clique no menu suspenso
* Selecione a função que deseja atribuir ao membro
* Clique no botão `Update` para salvar a função
Isso irá acionar uma atualização que pode ser acompanhada pela barra de progresso. O sistema irá buscar o código mais recente do seu repositório e reconstruir sua implantação.
## 2. Redefinindo o Bearer Token
Se precisar gerar um novo bearer token (por exemplo, se suspeitar que o token atual possa ter sido comprometido):
1. Navegue até sua crew na plataforma CrewAI Enterprise
2. Encontre a seção `Bearer Token`
3. Clique no botão `Reset` ao lado do token atual
2. Localize a seção `Environment Variables` (você deverá clicar no ícone de `Settings` para acessá-la)
3. Edite as variáveis existentes ou adicione novas nos campos fornecidos
4. Clique no botão `Update` ao lado de cada variável que você modificar
5. Por fim, clique no botão `Update Deployment` na parte inferior da página para aplicar as alterações
3. Adicione uma etapa de ação HTTP
* Configure a ação como `Send HTTP request`
* Use o método `POST`
* Defina a URL para o endpoint de kickoff do CrewAI Enterprise
* Adicione os headers necessários (ex.: `Bearer Token`)
* No corpo, inclua o conteúdo JSON conforme configurado na etapa 2
* O crew será iniciado no horário pré-definido.
2. Adicione uma etapa de webhook como gatilho:
* Selecione `Catch Webhook` como tipo de gatilho
* Isso irá gerar uma URL única que receberá requisições HTTP e disparará seu flow
* Configure o e-mail para usar o corpo de texto do webhook do crew
* Selecione `New Pushed Message` como o Evento de Trigger.
* Conecte sua conta Slack, caso ainda não tenha feito isso.
* Configure as entradas para o Crew usando os dados da mensagem do Slack.
* Selecione o botão de três pontos e então escolha Push to Zapier
CrewAI Enterprise expande o poder do framework open-source com funcionalidades projetadas para implantações em produção, colaboração e escalabilidade. Implemente seus crews em uma infraestrutura gerenciada e monitore sua execução em tempo real.
## Principais Funcionalidades
Essa matriz ajuda a visualizar como diferentes abordagens se alinham com os requisitos variados de complexidade e precisão. Vamos explorar o significado de cada quadrante e como isso orienta suas escolhas arquiteturais.
## Explicando a Matriz Complexidade-Precisão
### O que é Complexidade?
No contexto das aplicações CrewAI, **complexidade** refere-se a:
* O número de etapas ou operações distintas necessárias
* A diversidade de tarefas que precisam ser realizadas
* As interdependências entre diferentes componentes
* A necessidade de lógica condicional e ramificações
* A sofisticação do fluxo de trabalho como um todo
### O que é Precisão?
**Precisão** nesse contexto refere-se a:
* O grau de exatidão exigido no resultado final
* A necessidade de resultados estruturados e previsíveis
* A importância da reprodutibilidade
* O nível de controle necessário sobre cada etapa
* A tolerância à variação nos resultados
### Os Quatro Quadrantes
#### 1. Baixa Complexidade, Baixa Precisão
**Características:**
* Tarefas simples e diretas
* Tolerância a alguma variação nos resultados
* Número limitado de etapas
* Aplicações criativas ou exploratórias
**Abordagem Recomendada:** Crews simples com poucos agentes
**Exemplos de Casos de Uso:**
* Geração básica de conteúdo
* Brainstorming de ideias
* Tarefas simples de sumarização
* Assistência à escrita criativa
#### 2. Baixa Complexidade, Alta Precisão
**Características:**
* Fluxos de trabalho simples que exigem resultados exatos e estruturados
* Necessidade de resultados reproduzíveis
* Poucas etapas, mas alto requisito de precisão
* Frequentemente envolve processamento ou transformação de dados
**Abordagem Recomendada:** Flows com chamadas diretas a LLM ou Crews simples com saídas estruturadas
**Exemplos de Casos de Uso:**
* Extração e transformação de dados
* Preenchimento e validação de formulários
* Geração estruturada de conteúdo (JSON, XML)
* Tarefas simples de classificação
#### 3. Alta Complexidade, Baixa Precisão
**Características:**
* Processos multiestágio com muitas etapas
* Saídas criativas ou exploratórias
* Interações complexas entre componentes
* Tolerância à variação nos resultados finais
**Abordagem Recomendada:** Crews complexas com múltiplos agentes especializados
**Exemplos de Casos de Uso:**
* Pesquisa e análise
* Pipelines de criação de conteúdo
* Análise exploratória de dados
* Solução criativa de problemas
#### 4. Alta Complexidade, Alta Precisão
**Características:**
* Fluxos de trabalho complexos que requerem saídas estruturadas
* Múltiplas etapas interdependentes com rígida exigência de precisão
* Necessidade tanto de processamento sofisticado quanto de resultados precisos
* Frequentemente aplicações críticas
**Abordagem Recomendada:** Flows orquestrando múltiplas Crews com etapas de validação
**Exemplos de Casos de Uso:**
* Sistemas corporativos de suporte à decisão
* Pipelines complexos de processamento de dados
* Processamento de documentos em múltiplos estágios
* Aplicações em indústrias reguladas
## Escolhendo Entre Crews e Flows
### Quando Escolher Crews
Crews são ideais quando:
1. **Você precisa de inteligência colaborativa** - Múltiplos agentes com especializações diferentes precisam trabalhar juntos
2. **O problema requer pensamento emergente** - A solução se beneficia de diferentes perspectivas e abordagens
3. **A tarefa é principalmente criativa ou analítica** - O trabalho envolve pesquisa, criação de conteúdo ou análise
4. **Você valoriza adaptabilidade mais do que estrutura rígida** - O fluxo de trabalho pode se beneficiar da autonomia dos agentes
5. **O formato da saída pode ser um pouco flexível** - Alguma variação na estrutura do resultado é aceitável
```python
# Example: Research Crew for market analysis
from crewai import Agent, Crew, Process, Task
# Create specialized agents
researcher = Agent(
role="Market Research Specialist",
goal="Find comprehensive market data on emerging technologies",
backstory="You are an expert at discovering market trends and gathering data."
)
analyst = Agent(
role="Market Analyst",
goal="Analyze market data and identify key opportunities",
backstory="You excel at interpreting market data and spotting valuable insights."
)
# Define their tasks
research_task = Task(
description="Research the current market landscape for AI-powered healthcare solutions",
expected_output="Comprehensive market data including key players, market size, and growth trends",
agent=researcher
)
analysis_task = Task(
description="Analyze the market data and identify the top 3 investment opportunities",
expected_output="Analysis report with 3 recommended investment opportunities and rationale",
agent=analyst,
context=[research_task]
)
# Create the crew
market_analysis_crew = Crew(
agents=[researcher, analyst],
tasks=[research_task, analysis_task],
process=Process.sequential,
verbose=True
)
# Run the crew
result = market_analysis_crew.kickoff()
```
### Quando Escolher Flows
Flows são ideais quando:
1. **Você precisa de controle preciso da execução** - O fluxo de trabalho exige sequenciamento exato e gerenciamento de estado
2. **A aplicação tem requisitos complexos de estado** - Você precisa manter e transformar estado ao longo de múltiplas etapas
3. **Você precisa de saídas estruturadas e previsíveis** - A aplicação exige resultados consistentes e formatados
4. **O fluxo de trabalho envolve lógica condicional** - Caminhos diferentes precisam ser seguidos com base em resultados intermediários
5. **Você precisa combinar IA com código procedural** - A solução demanda tanto capacidades de IA quanto programação tradicional
```python
# Example: Customer Support Flow with structured processing
from crewai.flow.flow import Flow, listen, router, start
from pydantic import BaseModel
from typing import List, Dict
# Define structured state
class SupportTicketState(BaseModel):
ticket_id: str = ""
customer_name: str = ""
issue_description: str = ""
category: str = ""
priority: str = "medium"
resolution: str = ""
satisfaction_score: int = 0
class CustomerSupportFlow(Flow[SupportTicketState]):
@start()
def receive_ticket(self):
# In a real app, this might come from an API
self.state.ticket_id = "TKT-12345"
self.state.customer_name = "Alex Johnson"
self.state.issue_description = "Unable to access premium features after payment"
return "Ticket received"
@listen(receive_ticket)
def categorize_ticket(self, _):
# Use a direct LLM call for categorization
from crewai import LLM
llm = LLM(model="openai/gpt-4o-mini")
prompt = f"""
Categorize the following customer support issue into one of these categories:
- Billing
- Account Access
- Technical Issue
- Feature Request
- Other
Issue: {self.state.issue_description}
Return only the category name.
"""
self.state.category = llm.call(prompt).strip()
return self.state.category
@router(categorize_ticket)
def route_by_category(self, category):
# Route to different handlers based on category
return category.lower().replace(" ", "_")
@listen("billing")
def handle_billing_issue(self):
# Handle billing-specific logic
self.state.priority = "high"
# More billing-specific processing...
return "Billing issue handled"
@listen("account_access")
def handle_access_issue(self):
# Handle access-specific logic
self.state.priority = "high"
# More access-specific processing...
return "Access issue handled"
# Additional category handlers...
@listen("billing", "account_access", "technical_issue", "feature_request", "other")
def resolve_ticket(self, resolution_info):
# Final resolution step
self.state.resolution = f"Issue resolved: {resolution_info}"
return self.state.resolution
# Run the flow
support_flow = CustomerSupportFlow()
result = support_flow.kickoff()
```
### Quando Combinar Crews e Flows
As aplicações mais sofisticadas frequentemente se beneficiam da combinação de Crews e Flows:
1. **Processos complexos em múltiplos estágios** - Use Flows para orquestrar o processo geral e Crews para sub-tarefas complexas
2. **Aplicações que exigem criatividade e estrutura** - Use Crews para tarefas criativas e Flows para processamento estruturado
3. **Aplicações corporativas de IA** - Use Flows para gerenciar estado e fluxo de processo enquanto aproveita Crews para tarefas especializadas
```python
# Example: Content Production Pipeline combining Crews and Flows
from crewai.flow.flow import Flow, listen, start
from crewai import Agent, Crew, Process, Task
from pydantic import BaseModel
from typing import List, Dict
class ContentState(BaseModel):
topic: str = ""
target_audience: str = ""
content_type: str = ""
outline: Dict = {}
draft_content: str = ""
final_content: str = ""
seo_score: int = 0
class ContentProductionFlow(Flow[ContentState]):
@start()
def initialize_project(self):
# Set initial parameters
self.state.topic = "Sustainable Investing"
self.state.target_audience = "Millennial Investors"
self.state.content_type = "Blog Post"
return "Project initialized"
@listen(initialize_project)
def create_outline(self, _):
# Use a research crew to create an outline
researcher = Agent(
role="Content Researcher",
goal=f"Research {self.state.topic} for {self.state.target_audience}",
backstory="You are an expert researcher with deep knowledge of content creation."
)
outliner = Agent(
role="Content Strategist",
goal=f"Create an engaging outline for a {self.state.content_type}",
backstory="You excel at structuring content for maximum engagement."
)
research_task = Task(
description=f"Research {self.state.topic} focusing on what would interest {self.state.target_audience}",
expected_output="Comprehensive research notes with key points and statistics",
agent=researcher
)
outline_task = Task(
description=f"Create an outline for a {self.state.content_type} about {self.state.topic}",
expected_output="Detailed content outline with sections and key points",
agent=outliner,
context=[research_task]
)
outline_crew = Crew(
agents=[researcher, outliner],
tasks=[research_task, outline_task],
process=Process.sequential,
verbose=True
)
# Run the crew and store the result
result = outline_crew.kickoff()
# Parse the outline (in a real app, you might use a more robust parsing approach)
import json
try:
self.state.outline = json.loads(result.raw)
except:
# Fallback if not valid JSON
self.state.outline = {"sections": result.raw}
return "Outline created"
@listen(create_outline)
def write_content(self, _):
# Use a writing crew to create the content
writer = Agent(
role="Content Writer",
goal=f"Write engaging content for {self.state.target_audience}",
backstory="You are a skilled writer who creates compelling content."
)
editor = Agent(
role="Content Editor",
goal="Ensure content is polished, accurate, and engaging",
backstory="You have a keen eye for detail and a talent for improving content."
)
writing_task = Task(
description=f"Write a {self.state.content_type} about {self.state.topic} following this outline: {self.state.outline}",
expected_output="Complete draft content in markdown format",
agent=writer
)
editing_task = Task(
description="Edit and improve the draft content for clarity, engagement, and accuracy",
expected_output="Polished final content in markdown format",
agent=editor,
context=[writing_task]
)
writing_crew = Crew(
agents=[writer, editor],
tasks=[writing_task, editing_task],
process=Process.sequential,
verbose=True
)
# Run the crew and store the result
result = writing_crew.kickoff()
self.state.final_content = result.raw
return "Content created"
@listen(write_content)
def optimize_for_seo(self, _):
# Use a direct LLM call for SEO optimization
from crewai import LLM
llm = LLM(model="openai/gpt-4o-mini")
prompt = f"""
Analyze this content for SEO effectiveness for the keyword "{self.state.topic}".
Rate it on a scale of 1-100 and provide 3 specific recommendations for improvement.
Content: {self.state.final_content[:1000]}... (truncated for brevity)
Format your response as JSON with the following structure:
{{
"score": 85,
"recommendations": [
"Recommendation 1",
"Recommendation 2",
"Recommendation 3"
]
}}
"""
seo_analysis = llm.call(prompt)
# Parse the SEO analysis
import json
try:
analysis = json.loads(seo_analysis)
self.state.seo_score = analysis.get("score", 0)
return analysis
except:
self.state.seo_score = 50
return {"score": 50, "recommendations": ["Unable to parse SEO analysis"]}
# Run the flow
content_flow = ContentProductionFlow()
result = content_flow.kickoff()
```
## Framework Prático de Avaliação
Para determinar a abordagem certa para seu caso de uso específico, siga este framework passo a passo:
### Passo 1: Avalie a Complexidade
Classifique a complexidade do seu aplicativo numa escala de 1-10 considerando:
1. **Número de etapas**: Quantas operações distintas são necessárias?
* 1-3 etapas: Baixa complexidade (1-3)
* 4-7 etapas: Média complexidade (4-7)
* 8+ etapas: Alta complexidade (8-10)
2. **Interdependências**: Quão interligadas estão as partes diferentes?
* Poucas dependências: Baixa complexidade (1-3)
* Algumas dependências: Média complexidade (4-7)
* Muitas dependências complexas: Alta complexidade (8-10)
3. **Lógica condicional**: Quanto de ramificação e tomada de decisão é necessário?
* Processo linear: Baixa complexidade (1-3)
* Alguma ramificação: Média complexidade (4-7)
* Árvores de decisão complexas: Alta complexidade (8-10)
4. **Conhecimento de domínio**: Quão especializado deve ser o conhecimento requerido?
* Conhecimento geral: Baixa complexidade (1-3)
* Algum conhecimento especializado: Média complexidade (4-7)
* Grande especialização em múltiplos domínios: Alta complexidade (8-10)
Calcule a média das pontuações para determinar sua complexidade geral.
### Passo 2: Avalie os Requisitos de Precisão
Classifique seus requisitos de precisão numa escala de 1-10 considerando:
1. **Estrutura da saída**: Quão estruturado o resultado deve ser?
* Texto livre: Baixa precisão (1-3)
* Semi-estruturado: Média precisão (4-7)
* Estritamente formatado (JSON, XML): Alta precisão (8-10)
2. **Necessidade de exatidão**: Qual a importância da precisão factual?
* Conteúdo criativo: Baixa precisão (1-3)
* Conteúdo informacional: Média precisão (4-7)
* Informação crítica: Alta precisão (8-10)
3. **Reprodutibilidade**: Quão consistentes devem ser os resultados entre execuções?
* Variação aceitável: Baixa precisão (1-3)
* Alguma consistência necessária: Média precisão (4-7)
* Exata reprodutibilidade: Alta precisão (8-10)
4. **Tolerância a erros**: Qual o impacto de erros?
* Baixo impacto: Baixa precisão (1-3)
* Impacto moderado: Média precisão (4-7)
* Alto impacto: Alta precisão (8-10)
Calcule a média das pontuações para determinar seu requisito geral de precisão.
### Passo 3: Mapeie na Matriz
Plote as pontuações de complexidade e precisão na matriz:
* **Baixa Complexidade (1-4), Baixa Precisão (1-4)**: Crews simples
* **Baixa Complexidade (1-4), Alta Precisão (5-10)**: Flows com chamadas diretas a LLM
* **Alta Complexidade (5-10), Baixa Precisão (1-4)**: Crews complexas
* **Alta Complexidade (5-10), Alta Precisão (5-10)**: Flows orquestrando Crews
### Passo 4: Considere Fatores Adicionais
Além de complexidade e precisão, considere:
1. **Tempo de desenvolvimento**: Crews costumam ser mais rápidas para prototipar
2. **Necessidades de manutenção**: Flows proporcionam melhor manutenção a longo prazo
3. **Expertise do time**: Considere a familiaridade de sua equipe com as abordagens
4. **Requisitos de escalabilidade**: Flows normalmente escalam melhor para aplicações complexas
5. **Necessidades de integração**: Considere como a solução se integrará aos sistemas existentes
## Conclusão
Escolher entre Crews e Flows — ou combiná-los — é uma decisão arquitetônica crítica que impacta a efetividade, manutenibilidade e escalabilidade da sua aplicação CrewAI. Ao avaliar seu caso de uso nas dimensões de complexidade e precisão, você toma decisões inteligentes que alinham-se aos seus requisitos.
Lembre-se de que a melhor abordagem geralmente evolui na medida em que sua aplicação amadurece. Comece com a solução mais simples que atenda às suas necessidades e esteja preparado para refinar sua arquitetura conforme for ganhando experiência e seus requisitos se tornarem mais claros.
## Passo 2: Explore a Estrutura do Projeto
Vamos dedicar um momento para entender a estrutura do projeto criada pela CLI. A CrewAI segue boas práticas para projetos Python, tornando fácil manter e estender seu código à medida que suas crews se tornam mais complexas.
```
research_crew/
├── .gitignore
├── pyproject.toml
├── README.md
├── .env
└── src/
└── research_crew/
├── __init__.py
├── main.py
├── crew.py
├── tools/
│ ├── custom_tool.py
│ └── __init__.py
└── config/
├── agents.yaml
└── tasks.yaml
```
Esta estrutura segue as melhores práticas para projetos Python e facilita a organização do seu código. A separação dos arquivos de configuração (em YAML) do código de implementação (em Python) permite modificar o comportamento da sua crew sem alterar o código subjacente.
## Passo 3: Configure seus Agentes
Agora vem a parte divertida – definir seus agentes de IA! Na CrewAI, agentes são entidades especializadas com papéis, objetivos e históricos específicos que moldam seu comportamento. Pense neles como personagens em uma peça, cada um com sua personalidade e propósito próprios.
Para nossa crew de pesquisa, vamos criar dois agentes:
1. Um **pesquisador** que é especialista em encontrar e organizar informações
2. Um **analista** que pode interpretar os resultados da pesquisa e criar relatórios perspicazes
Vamos modificar o arquivo `agents.yaml` para definir esses agentes especializados. Certifique-se de
definir `llm` para o provedor que você está utilizando.
```yaml
# src/research_crew/config/agents.yaml
researcher:
role: >
Especialista Sênior em Pesquisa para {topic}
goal: >
Encontrar informações abrangentes e precisas sobre {topic}
com foco em desenvolvimentos recentes e insights chave
backstory: >
Você é um especialista em pesquisa experiente com talento para
encontrar informações relevantes de diversas fontes. Você se destaca em
organizar informações de forma clara e estruturada, tornando temas complexos acessíveis para outros.
llm: provider/model-id # ex: openai/gpt-4o, google/gemini-2.0-flash, anthropic/claude...
analyst:
role: >
Analista de Dados e Redator de Relatórios para {topic}
goal: >
Analisar os resultados da pesquisa e criar um relatório abrangente e bem estruturado
que apresente os insights de forma clara e envolvente
backstory: >
Você é um analista habilidoso com experiência em interpretação de dados
e redação técnica. Tem talento para identificar padrões
e extrair insights relevantes dos dados de pesquisa, comunicando esses insights de forma eficaz por meio de relatórios bem elaborados.
llm: provider/model-id # ex: openai/gpt-4o, google/gemini-2.0-flash, anthropic/claude...
```
Perceba como cada agente tem um papel, objetivo e histórico distintos. Esses elementos não são apenas descritivos – eles efetivamente moldam como o agente aborda suas tarefas. Ao criar cuidadosamente esses detalhes, você pode ter agentes com habilidades e perspectivas que se complementam.
## Passo 4: Defina suas Tarefas
Com nossos agentes definidos, agora precisamos atribuir tarefas específicas para eles realizarem. Tarefas na CrewAI representam o trabalho concreto que os agentes irão executar, com instruções detalhadas e saídas esperadas.
Para nossa crew de pesquisa, vamos definir duas tarefas principais:
1. Uma **tarefa de pesquisa** para coletar informações abrangentes
2. Uma **tarefa de análise** para criar um relatório com insights
Vamos modificar o arquivo `tasks.yaml`:
```yaml
# src/research_crew/config/tasks.yaml
research_task:
description: >
Realize uma pesquisa aprofundada sobre {topic}. Foque em:
1. Conceitos e definições chave
2. Desenvolvimento histórico e tendências recentes
3. Principais desafios e oportunidades
4. Aplicações relevantes ou estudos de caso
5. Perspectivas futuras e novos desenvolvimentos
Certifique-se de organizar seus achados em um formato estruturado, com seções claras.
expected_output: >
Um documento de pesquisa abrangente com seções bem organizadas cobrindo
todos os aspectos solicitados de {topic}. Inclua fatos, números
e exemplos específicos sempre que possível.
agent: researcher
analysis_task:
description: >
Analise os resultados da pesquisa e crie um relatório abrangente sobre {topic}.
Seu relatório deve:
1. Iniciar com um resumo executivo
2. Incluir todas as informações relevantes da pesquisa
3. Oferecer uma análise perspicaz de tendências e padrões
4. Apresentar recomendações ou considerações futuras
5. Estar formatado de forma profissional, clara e com títulos bem definidos
expected_output: >
Um relatório profissional, polido e estruturado sobre {topic} com apresentação dos resultados da pesquisa,
acrescentando análise e insights. O relatório deve ser bem estruturado,
incluindo resumo executivo, sessões principais e conclusão.
agent: analyst
context:
- research_task
output_file: output/report.md
```
Note o campo `context` na tarefa de análise – esse é um recurso poderoso que permite ao analista acessar a saída da tarefa de pesquisa. Isso cria um fluxo de trabalho em que a informação circula naturalmente entre os agentes, como aconteceria em uma equipe humana.
## Passo 5: Configure sua Crew
Agora é hora de juntar tudo configurando nossa crew. A crew é o container que orquestra como os agentes trabalham juntos para completar as tarefas.
Vamos modificar o arquivo `crew.py`:
```python
# src/research_crew/crew.py
from crewai import Agent, Crew, Process, Task
from crewai.project import CrewBase, agent, crew, task
from crewai_tools import SerperDevTool
from crewai.agents.agent_builder.base_agent import BaseAgent
from typing import List
@CrewBase
class ResearchCrew():
"""Research crew for comprehensive topic analysis and reporting"""
agents: List[BaseAgent]
tasks: List[Task]
@agent
def researcher(self) -> Agent:
return Agent(
config=self.agents_config['researcher'], # type: ignore[index]
verbose=True,
tools=[SerperDevTool()]
)
@agent
def analyst(self) -> Agent:
return Agent(
config=self.agents_config['analyst'], # type: ignore[index]
verbose=True
)
@task
def research_task(self) -> Task:
return Task(
config=self.tasks_config['research_task'] # type: ignore[index]
)
@task
def analysis_task(self) -> Task:
return Task(
config=self.tasks_config['analysis_task'], # type: ignore[index]
output_file='output/report.md'
)
@crew
def crew(self) -> Crew:
"""Creates the research crew"""
return Crew(
agents=self.agents,
tasks=self.tasks,
process=Process.sequential,
verbose=True,
)
```
Neste código, estamos:
1. Criando o agente pesquisador e equipando-o com o SerperDevTool para buscas web
2. Criando o agente analista
3. Definindo as tarefas de pesquisa e análise
4. Configurando a crew para executar as tarefas sequencialmente (o analista espera o pesquisador terminar)
É aqui que a mágica acontece – com poucas linhas de código, definimos um sistema colaborativo de IA onde agentes especializados trabalham juntos em um processo coordenado.
## Passo 6: Prepare seu Script Principal
Agora, vamos preparar o script principal que irá rodar nossa crew. É aqui que informamos o tema específico que queremos pesquisar.
```python
#!/usr/bin/env python
# src/research_crew/main.py
import os
from research_crew.crew import ResearchCrew
# Crie o diretório de saída se não existir
os.makedirs('output', exist_ok=True)
def run():
"""
Rodar a crew de pesquisa.
"""
inputs = {
'topic': 'Inteligência Artificial na Saúde'
}
# Criar e rodar a crew
result = ResearchCrew().crew().kickoff(inputs=inputs)
# Imprimir o resultado
print("\n\n=== RELATÓRIO FINAL ===\n\n")
print(result.raw)
print("\n\nRelatório salvo em output/report.md")
if __name__ == "__main__":
run()
```
Este script prepara o ambiente, define o tema de pesquisa e inicia o trabalho da crew. O poder da CrewAI fica evidente em como esse código é simples – toda a complexidade do gerenciamento de múltiplos agentes de IA é tratada pelo framework.
## Passo 7: Defina suas Variáveis de Ambiente
Crie um arquivo `.env` na raiz do seu projeto com suas chaves de API:
```sh
SERPER_API_KEY=sua_serper_api_key
# Adicione a chave de API do seu provedor também.
```
Confira o [guia de configuração do LLM](/pt-BR/concepts/llms#setting-up-your-llm) para detalhes sobre como configurar o provedor de sua escolha. Você pode obter a chave da Serper em [Serper.dev](https://serper.dev/).
## Passo 8: Instale as Dependências
Instale as dependências necessárias usando a CLI da CrewAI:
```bash
crewai install
```
Este comando irá:
1. Ler as dependências da configuração do seu projeto
2. Criar um ambiente virtual se necessário
3. Instalar todos os pacotes necessários
## Passo 9: Execute sua Crew
Agora chega o momento empolgante – é hora de rodar sua crew e assistir à colaboração de IA em ação!
```bash
crewai run
```
Ao rodar esse comando, você verá sua crew ganhando vida. O pesquisador irá coletar informações sobre o tema especificado, e o analista irá criar um relatório abrangente baseado nessa pesquisa. Você poderá acompanhar em tempo real o raciocínio, as ações e os resultados dos agentes à medida que colaboram para concluir as tarefas.
## Passo 10: Revise o Resultado
Após a conclusão do trabalho da crew, você encontrará o relatório final em `output/report.md`. O relatório incluirá:
1. Um resumo executivo
2. Informações detalhadas sobre o tema
3. Análises e insights
4. Recomendações ou considerações futuras
Tire um momento para valorizar o que você realizou – você criou um sistema no qual múltiplos agentes de IA colaboraram em uma tarefa complexa, cada um contribuindo com suas habilidades especializadas para gerar um resultado maior do que qualquer agente conseguiria sozinho.
## Explorando Outros Comandos da CLI
A CrewAI oferece vários outros comandos úteis de CLI para trabalhar com crews:
```bash
# Ver todos os comandos disponíveis
crewai --help
# Rodar a crew
crewai run
# Testar a crew
crewai test
# Resetar as memórias da crew
crewai reset-memories
# Repetir a partir de uma tarefa específica
crewai replay -t
## Passo 2: Entendendo a Estrutura do Projeto
O projeto gerado possui a seguinte estrutura. Reserve um momento para conhecê-la, pois isso ajudará você a criar flows mais complexos no futuro.
```
guide_creator_flow/
├── .gitignore
├── pyproject.toml
├── README.md
├── .env
├── main.py
├── crews/
│ └── poem_crew/
│ ├── config/
│ │ ├── agents.yaml
│ │ └── tasks.yaml
│ └── poem_crew.py
└── tools/
└── custom_tool.py
```
Esta estrutura oferece uma separação clara entre os diferentes componentes do seu flow:
* A lógica principal do flow no arquivo `main.py`
* Crews especializados no diretório `crews`
* Ferramentas customizadas no diretório `tools`
Vamos modificar esta estrutura para criar nosso flow de criação de guias, que irá orquestrar o processo de geração de guias de aprendizagem abrangentes.
## Passo 3: Adicione um Crew de Redator de Conteúdo
Nosso flow precisará de um crew especializado para lidar com o processo de criação de conteúdo. Vamos usar a CLI do CrewAI para adicionar um crew de redatores de conteúdo:
```bash
crewai flow add-crew content-crew
```
Este comando cria automaticamente os diretórios e arquivos de template necessários para seu crew. O crew de redatores será responsável por escrever e revisar seções do nosso guia, trabalhando dentro do flow orquestrado pela aplicação principal.
## Passo 4: Configure o Crew de Redator de Conteúdo
Agora, vamos modificar os arquivos gerados para o crew de redatores. Vamos configurar dois agentes especializados – um escritor e um revisor – que irão colaborar para criar um conteúdo de alta qualidade para o nosso guia.
1. Primeiro, atualize o arquivo de configuração de agents para definir a equipe de criação de conteúdo:
Lembre-se de configurar o `llm` com o provedor que está utilizando.
```yaml
# src/guide_creator_flow/crews/content_crew/config/agents.yaml
content_writer:
role: >
Redator de Conteúdo Educacional
goal: >
Criar conteúdo envolvente e informativo que explique completamente o tema proposto
e forneça insights valiosos ao leitor
backstory: >
Você é um talentoso escritor educacional com experiência em criar conteúdo claro
e atraente. Você tem facilidade para explicar conceitos complexos em linguagem acessível
e organizar as informações de forma a ajudar o leitor a construir seu entendimento.
llm: provider/model-id # e.g. openai/gpt-4o, google/gemini-2.0-flash, anthropic/claude...
content_reviewer:
role: >
Revisor(a) e Editor(a) de Conteúdo Educacional
goal: >
Garantir que o conteúdo seja preciso, abrangente, bem estruturado e mantenha
consistência com as seções previamente escritas
backstory: >
Você é um editor(a) meticuloso(a) com anos de experiência revisando conteúdo educacional.
Tem atenção aos detalhes, clareza e coesão. Você se destaca em aprimorar conteúdo
mantendo o estilo do autor original e garantindo qualidade consistente em várias seções.
llm: provider/model-id # e.g. openai/gpt-4o, google/gemini-2.0-flash, anthropic/claude...
```
Essas definições de agents estabelecem papéis e perspectivas especializadas que irão moldar como nossos agentes de IA abordam a criação de conteúdo. Note como cada agent possui um propósito e expertise distintos.
2. Em seguida, atualize o arquivo de configuração de tarefas para definir as tarefas específicas de escrita e revisão:
```yaml
# src/guide_creator_flow/crews/content_crew/config/tasks.yaml
write_section_task:
description: >
Escreva uma seção abrangente sobre o tema: "{section_title}"
Descrição da seção: {section_description}
Público-alvo: {audience_level} aprendizes
Seu conteúdo deve:
1. Começar com uma breve introdução ao tema da seção
2. Explicar claramente todos os conceitos principais com exemplos
3. Incluir aplicações práticas ou exercícios onde apropriado
4. Terminar com um resumo dos pontos principais
5. Ter aproximadamente 500-800 palavras
Formate seu conteúdo em Markdown com títulos, listas e ênfase apropriados.
Seções previamente escritas:
{previous_sections}
Certifique-se de que seu conteúdo mantenha consistência com as seções já escritas
e amplie os conceitos que já foram explicados.
expected_output: >
Uma seção bem estruturada e abrangente em formato Markdown que explique
totalmente o tema e é apropriada para o público-alvo.
agent: content_writer
review_section_task:
description: >
Revise e melhore a seguinte seção sobre "{section_title}":
{draft_content}
Público-alvo: {audience_level} aprendizes
Seções previamente escritas:
{previous_sections}
Sua revisão deve:
1. Corrigir qualquer erro gramatical ou de ortografia
2. Melhorar clareza e legibilidade
3. Garantir que o conteúdo seja abrangente e preciso
4. Verificar a consistência com as seções já escritas
5. Aprimorar a estrutura e o fluxo
6. Adicionar qualquer informação-chave ausente
Forneça a versão aprimorada da seção em formato Markdown.
expected_output: >
Uma versão melhorada e refinada da seção, mantendo a estrutura original,
mas aprimorando clareza, precisão e consistência.
agent: content_reviewer
context:
- write_section_task
```
Essas definições de tarefas fornecem instruções detalhadas para nossos agents, garantindo que eles produzam conteúdo que atenda aos padrões de qualidade. Observe como o parâmetro `context` na tarefa de revisão cria um fluxo onde o revisor tem acesso à produção do redator.
3. Agora, atualize o arquivo de implementação do crew para definir como nossos agents e tasks trabalham juntos:
```python
# src/guide_creator_flow/crews/content_crew/content_crew.py
from crewai import Agent, Crew, Process, Task
from crewai.project import CrewBase, agent, crew, task
from crewai.agents.agent_builder.base_agent import BaseAgent
from typing import List
@CrewBase
class ContentCrew():
"""Crew de redação de conteúdo"""
agents: List[BaseAgent]
tasks: List[Task]
@agent
def content_writer(self) -> Agent:
return Agent(
config=self.agents_config['content_writer'], # type: ignore[index]
verbose=True
)
@agent
def content_reviewer(self) -> Agent:
return Agent(
config=self.agents_config['content_reviewer'], # type: ignore[index]
verbose=True
)
@task
def write_section_task(self) -> Task:
return Task(
config=self.tasks_config['write_section_task'] # type: ignore[index]
)
@task
def review_section_task(self) -> Task:
return Task(
config=self.tasks_config['review_section_task'], # type: ignore[index]
context=[self.write_section_task()]
)
@crew
def crew(self) -> Crew:
"""Cria o crew de redação de conteúdo"""
return Crew(
agents=self.agents,
tasks=self.tasks,
process=Process.sequential,
verbose=True,
)
```
Essa definição de crew estabelece o relacionamento entre nossos agents e tasks, definindo um processo sequencial onde o redator cria o rascunho e o revisor o aprimora. Embora este crew possa funcionar de forma independente, em nosso flow ele será orquestrado como parte de um sistema maior.
## Passo 5: Crie o Flow
Agora vem a parte emocionante – criar o flow que irá orquestrar todo o processo de criação do guia. Aqui iremos combinar código Python regular, chamadas diretas a LLM e nosso crew de criação de conteúdo em um sistema coeso.
Nosso flow irá:
1. Obter a entrada do usuário sobre o tema e nível do público
2. Fazer uma chamada direta à LLM para criar um roteiro estruturado do guia
3. Processar cada seção sequencialmente usando o crew de redatores
4. Combinar tudo em um documento final abrangente
Vamos criar nosso flow no arquivo `main.py`:
```python
# [CÓDIGO NÃO TRADUZIDO, MANTER COMO ESTÁ]
```
Vamos analisar o que está acontecendo neste flow:
1. Definimos modelos Pydantic para dados estruturados, garantindo segurança de tipos e representação clara dos dados.
2. Criamos uma classe de estado para manter dados entre os diferentes passos do flow.
3. Implementamos três etapas principais para o flow:
* Obtenção da entrada do usuário com o decorator `@start()`
* Criação do roteiro do guia com uma chamada direta à LLM
* Processamento das seções com nosso crew de conteúdo
4. Usamos o decorator `@listen()` para estabelecer relações orientadas a eventos entre as etapas
Este é o poder dos flows – combinar diferentes tipos de processamento (interação com usuário, chamadas diretas a IA, tarefas colaborativas com crews) em um sistema orientado a eventos e coeso.
## Passo 6: Configure suas Variáveis de Ambiente
Crie um arquivo `.env` na raiz do projeto com suas chaves de API. Veja o [guia de configuração do LLM](/pt-BR/concepts/llms#setting-up-your-llm) para detalhes sobre como configurar o provedor.
```sh .env
OPENAI_API_KEY=sua_chave_openai
# ou
GEMINI_API_KEY=sua_chave_gemini
# ou
ANTHROPIC_API_KEY=sua_chave_anthropic
```
## Passo 7: Instale as Dependências
Instale as dependências necessárias:
```bash
crewai install
```
## Passo 8: Execute Seu Flow
Agora é hora de ver seu flow em ação! Execute-o usando a CLI do CrewAI:
```bash
crewai flow kickoff
```
Quando você rodar esse comando, verá seu flow ganhando vida:
1. Ele solicitará um tema e o nível do público para você
2. Criará um roteiro estruturado para o seu guia
3. Processará cada seção, com o redator e o revisor colaborando em cada uma
4. Por fim, irá compilar tudo em um guia abrangente
Isso demonstra o poder dos flows para orquestrar processos complexos envolvendo múltiplos componentes, tanto de IA quanto não-IA.
## Passo 9: Visualize Seu Flow
Uma das funcionalidades mais poderosas dos flows é a possibilidade de visualizar sua estrutura:
```bash
crewai flow plot
```
Isso irá criar um arquivo HTML que mostra a estrutura do seu flow, incluindo os relacionamentos entre etapas e o fluxo de dados. Essa visualização pode ser inestimável para entender e depurar flows complexos.
## Passo 10: Revise o Resultado
Depois que o flow finalizar, você encontrará dois arquivos no diretório `output`:
1. `guide_outline.json`: Contém o roteiro estruturado do guia
2. `complete_guide.md`: O guia abrangente com todas as seções
Reserve um momento para revisar esses arquivos e apreciar o que você construiu – um sistema que combina entrada do usuário, interações diretas com IA e trabalho colaborativo de agents para produzir um output complexo e de alta qualidade.
## A Arte do Possível: Além do Seu Primeiro Flow
O que você aprendeu neste guia é uma base para criar sistemas de IA muito mais sofisticados. Veja algumas formas de expandir este flow básico:
### Aprimorando a Interação com o Usuário
Você pode criar flows mais interativos com:
* Interfaces web para entrada e saída de dados
* Atualizações em tempo real de progresso
* Loops de feedback e refinamento interativos
* Interações multi-stage com o usuário
### Adicionando Mais Etapas de Processamento
Você pode expandir seu flow com etapas adicionais para:
* Pesquisa antes da criação do roteiro
* Geração de imagens para ilustrações
* Geração de snippets de código para guias técnicos
* Garantia de qualidade e checagem final de fatos
### Criando Flows Mais Complexos
Você pode implementar padrões de flow mais sofisticados:
* Ramificações condicionais com base na preferência do usuário ou tipo de conteúdo
* Processamento paralelo de seções independentes
* Loops de refinamento iterativo com feedback
* Integração a APIs e serviços externos
### Aplicando a Diferentes Domínios
Os mesmos padrões podem ser usados para criar flows de:
* **Narrativas interativas**: criação de histórias personalizadas com base na entrada do usuário
* **Inteligência de negócios**: processamento de dados, geração de insights e criação de relatórios
* **Desenvolvimento de produtos**: facilitação de ideação, design e planejamento
* **Sistemas educacionais**: criação de experiências de aprendizagem personalizadas
## Principais Funcionalidades Demonstradas
Este flow de criação de guia demonstra diversos recursos poderosos do CrewAI:
1. **Interação com o usuário**: O flow coleta input diretamente do usuário
2. **Chamadas diretas à LLM**: Usa a classe LLM para interações eficientes e direcionadas com IA
3. **Dados estruturados com Pydantic**: Usa Pydantic para garantir segurança de tipos
4. **Processamento sequencial com contexto**: Escreve seções em ordem, fornecendo as anteriores como contexto
5. **Crews multiagentes**: Utiliza agents especializados (redator e revisor) para criação de conteúdo
6. **Gerenciamento de estado**: Mantém estado entre diferentes etapas do processo
7. **Arquitetura orientada a eventos**: Usa o decorator `@listen` para responder a eventos
## Entendendo a Estrutura do Flow
Vamos decompor os principais componentes dos flows para ajudá-lo a entender como construir o seu:
### 1. Chamadas Diretas à LLM
Flows permitem que você faça chamadas diretas a modelos de linguagem quando precisa de respostas simples e estruturadas:
```python
llm = LLM(
model="model-id-here", # gpt-4o, gemini-2.0-flash, anthropic/claude...
response_format=GuideOutline
)
response = llm.call(messages=messages)
```
Isso é mais eficiente do que usar um crew quando você precisa de um output específico e estruturado.
### 2. Arquitetura Orientada a Eventos
Flows usam decorators para estabelecer relações entre componentes:
```python
@start()
def get_user_input(self):
# Primeira etapa no flow
# ...
@listen(get_user_input)
def create_guide_outline(self, state):
# Esta roda quando get_user_input é concluída
# ...
```
Isso cria uma estrutura clara e declarativa para sua aplicação.
### 3. Gerenciamento de Estado
Flows mantêm o estado entre as etapas, facilitando o compartilhamento de dados:
```python
class GuideCreatorState(BaseModel):
topic: str = ""
audience_level: str = ""
guide_outline: GuideOutline = None
sections_content: Dict[str, str] = {}
```
Isso fornece uma maneira segura e tipada de rastrear e transformar dados ao longo do flow.
### 4. Integração com Crews
Flows podem integrar crews para tarefas colaborativas complexas:
```python
result = ContentCrew().crew().kickoff(inputs={
"section_title": section.title,
# ...
})
```
Assim, você usa a ferramenta certa para cada parte da aplicação – chamadas diretas para tarefas simples e crews para colaboração avançada.
## Próximos Passos
Agora que você construiu seu primeiro flow, pode:
1. Experimentar estruturas e padrões mais complexos de flow
2. Testar o uso do `@router()` para criar ramificações condicionais em seus flows
3. Explorar as funções `and_` e `or_` para execuções paralelas e mais complexas
4. Conectar seu flow a APIs externas, bancos de dados ou interfaces de usuário
5. Combinar múltiplos crews especializados em um único flow
| Componente | Descrição | Principais Funcionalidades |
| :---------------- | :------------------------------------: | :-------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Crew** | Organização de mais alto nível | • Gerencia equipes de agentes de IA
| Componente | Descrição | Principais Funcionalidades |
| :--------------- | :-------------------------------------------: | :---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Flow** | Orquestração de fluxo de trabalho estruturada | • Gerencia caminhos de execução
## Boas Práticas
1. **Seja específico nos prompts de geração de imagem** para obter melhores resultados.
2. **Considere o tempo de geração** - A geração de imagens pode levar algum tempo, então inclua isso no seu planejamento de tarefas.
3. **Siga as políticas de uso** - Sempre cumpra as políticas de uso da OpenAI ao gerar imagens.
## Solução de Problemas
1. **Verifique o acesso à API** - Certifique-se de que sua chave de API OpenAI possui acesso ao DALL-E.
2. **Compatibilidade de versões** - Verifique se você está utilizando a versão mais recente do crewAI e crewai-tools.
3. **Configuração da ferramenta** - Confirme que a ferramenta DALL-E foi corretamente adicionada à lista de ferramentas do agente.
# Forçar a Saída da Ferramenta como Resultado
Source: https://docs.crewai.com/pt-BR/learn/force-tool-output-as-result
Aprenda como forçar a saída de uma ferramenta como resultado em uma tarefa de Agent no CrewAI.
## Introdução
No CrewAI, você pode forçar a saída de uma ferramenta como o resultado de uma tarefa de um agent.\
Esse recurso é útil quando você deseja garantir que a saída da ferramenta seja capturada e retornada como resultado da tarefa, evitando quaisquer modificações pelo agent durante a execução da tarefa.
## Forçando a Saída da Ferramenta como Resultado
Para forçar a saída da ferramenta como resultado da tarefa de um agent, você precisa definir o parâmetro `result_as_answer` como `True` ao adicionar uma ferramenta ao agent.\
Esse parâmetro garante que a saída da ferramenta seja capturada e retornada como resultado da tarefa, sem qualquer modificação pelo agent.
Veja um exemplo de como forçar a saída da ferramenta como resultado da tarefa de um agent:
```python Code
from crewai.agent import Agent
from my_tool import MyCustomTool
# Create a coding agent with the custom tool
coding_agent = Agent(
role="Data Scientist",
goal="Produce amazing reports on AI",
backstory="You work with data and AI",
tools=[MyCustomTool(result_as_answer=True)],
)
# Assuming the tool's execution and result population occurs within the system
task_result = coding_agent.execute_task(task)
```
## Fluxo de Trabalho em Ação
**Funcionalidades Avançadas de Teste:**
* **Comparação Multi-Modelo**: Teste diversos LLMs simultaneamente nas mesmas tarefas e entradas. Compare desempenho entre GPT-4o, Claude, Llama, Groq, Cerebras, e outros líderes em paralelo para identificar a melhor opção para você.
* **Rigor Estatístico**: Configure múltiplas iterações com inputs consistentes para medir confiabilidade e variação no desempenho. Assim, identifica modelos que performam bem e de modo consistente.
* **Validação no Mundo Real**: Use os inputs e cenários reais da sua crew, e não apenas benchmarks sintéticos. A plataforma permite testar no contexto da sua indústria, empresa e casos de uso.
* **Analytics Completo**: Acesse métricas detalhadas de desempenho, tempos de execução e análise de custos para todos os modelos testados. Decisões baseadas em dados reais, não apenas reputação.
* **Colaboração em Equipe**: Compartilhe resultados e análises com seu time, favorecendo decisões coletivas e estratégias alinhadas.
Acesse [app.crewai.com](https://app.crewai.com) para começar!
**Confira:** [Ver o exemplo de trace ao vivo](https://app.langdb.ai/sharing/threads/3becbfed-a1be-ae84-ea3c-4942867a3e22)
## Recursos
### Capacidades do AI Gateway
* **Acesso a mais de 350 LLMs**: Conecte-se a todos os principais modelos de linguagem através de uma única integração
* **Modelos Virtuais**: Crie configurações de modelo personalizadas com parâmetros específicos e regras de roteamento
* **MCP Virtual**: Habilite compatibilidade e integração com sistemas MCP (Model Context Protocol) para comunicação aprimorada de agentes
* **Guardrails**: Implemente medidas de segurança e controles de conformidade para comportamento de agentes
### Observabilidade e Rastreamento
* **Rastreamento Automático**: Uma única chamada `init()` captura todas as interações CrewAI
* **Visibilidade Ponta a Ponta**: Monitore fluxos de trabalho de agentes do início ao fim
* **Rastreamento de Uso de Ferramentas**: Rastreie quais ferramentas os agentes usam e seus resultados
* **Monitoramento de Chamadas de Modelo**: Insights detalhados sobre interações LLM
* **Análise de Performance**: Monitore latência, uso de tokens e custos
* **Suporte a Depuração**: Execução passo a passo para solução de problemas
* **Monitoramento em Tempo Real**: Dashboard de traces e métricas ao vivo
## Instruções de Configuração
### O Que Você Verá
* **Interações de Agentes**: Fluxo completo de conversas de agentes e transferências de tarefas
* **Uso de Ferramentas**: Quais ferramentas foram chamadas, suas entradas e saídas
* **Chamadas de Modelo**: Interações LLM detalhadas com prompts e respostas
* **Métricas de Performance**: Rastreamento de latência, uso de tokens e custos
* **Linha do Tempo de Execução**: Visualização passo a passo de todo o fluxo de trabalho
## Solução de Problemas
### Problemas Comuns
* **Nenhum trace aparecendo**: Certifique-se de que `init()` seja chamado antes de qualquer importação CrewAI
* **Erros de autenticação**: Verifique sua chave API LangDB e ID do projeto
## Recursos
## Instruções de Configuração
### Funcionalidades
* **Painel de Tracing**: Monitore as atividades dos seus agentes crewAI com painéis detalhados que incluem entradas, saídas e metadados dos spans.
* **Tracing Automatizado**: Uma integração totalmente automatizada com crewAI, que pode ser habilitada executando `mlflow.crewai.autolog()`.
* **Instrumentação Manual de Tracing com pouco esforço**: Personalize a instrumentação dos traces usando as APIs de alto nível do MLflow, como decorators, wrappers de funções e context managers.
* **Compatibilidade com OpenTelemetry**: O MLflow Tracing suporta a exportação de traces para um OpenTelemetry Collector, que pode então ser usado para exportar traces para diversos backends como Jaeger, Zipkin e AWS X-Ray.
* **Empacote e Faça Deploy dos Agents**: Empacote e faça deploy de seus agents crewAI em um servidor de inferência com diversas opções de destino.
* **Hospede LLMs com Segurança**: Hospede múltiplos LLMs de vários provedores em um endpoint unificado através do gateway do MFflow.
* **Avaliação**: Avalie seus agents crewAI com uma ampla variedade de métricas utilizando a API conveniente `mlflow.evaluate()`.
## Instruções de Configuração
### Funcionalidades
* **Painel Analítico**: Monitore a saúde e desempenho dos seus Agentes com dashboards detalhados que acompanham métricas, custos e interações dos usuários.
* **SDK de Observabilidade Nativo OpenTelemetry**: SDKs neutros de fornecedor para enviar rastreamentos e métricas para suas ferramentas de observabilidade existentes como Grafana, DataDog e outros.
* **Rastreamento de Custos para Modelos Customizados e Ajustados**: Adapte estimativas de custo para modelos específicos usando arquivos de precificação customizados para orçamentos precisos.
* **Painel de Monitoramento de Exceções**: Identifique e solucione rapidamente problemas ao rastrear exceções comuns e erros por meio de um painel de monitoramento.
* **Conformidade e Segurança**: Detecte ameaças potenciais como profanidade e vazamento de dados sensíveis (PII).
* **Detecção de Prompt Injection**: Identifique possíveis injeções de código e vazamentos de segredos.
* **Gerenciamento de Chaves de API e Segredos**: Gerencie suas chaves de API e segredos do LLM de forma centralizada e segura, evitando práticas inseguras.
* **Gerenciamento de Prompt**: Gerencie e versiona prompts de Agente usando o PromptHub para acesso consistente e fácil entre os agentes.
* **Model Playground** Teste e compare diferentes modelos para seus agentes CrewAI antes da implantação.
## Instruções de Configuração
O Opik oferece suporte abrangente para cada etapa do desenvolvimento da sua aplicação CrewAI:
* **Registrar Traces e Spans**: Acompanhe automaticamente chamadas LLM e lógica da aplicação para depurar e analisar sistemas em desenvolvimento e em produção. Anote manualmente ou programaticamente, visualize e compare respostas entre projetos.
* **Avalie a Performance da sua Aplicação LLM**: Avalie contra um conjunto de testes personalizado e execute métricas de avaliação nativas ou defina suas próprias métricas via SDK ou UI.
* **Teste no Pipeline CI/CD**: Estabeleça bases de performance confiáveis com os testes unitários LLM do Opik, baseados em PyTest. Execute avaliações online para monitoramento contínuo em produção.
* **Monitore & Analise Dados de Produção**: Entenda a performance dos seus modelos em dados inéditos em produção e gere conjuntos de dados para novas iterações de desenvolvimento.
## Configuração
A Comet oferece uma versão hospedada da plataforma Opik, ou você pode rodar a plataforma localmente.
Para usar a versão hospedada, basta [criar uma conta gratuita na Comet](https://www.comet.com/signup?utm_medium=github\&utm_source=crewai_docs) e obter sua chave de API.
Para rodar a plataforma Opik localmente, veja nosso [guia de instalação](https://www.comet.com/docs/opik/self-host/overview/) para mais informações.
Neste guia, utilizaremos o exemplo de início rápido da CrewAI.
## Introdução
Portkey aprimora o CrewAI com recursos prontos para produção, transformando seus crews de agentes experimentais em sistemas robustos ao fornecer:
* **Observabilidade completa** de cada etapa do agente, uso de ferramentas e interações
* **Confiabilidade incorporada** com fallbacks, tentativas automáticas e balanceamento de carga
* **Rastreamento e otimização de custos** para gerenciar seus gastos com IA
* **Acesso a mais de 200 LLMs** por meio de uma única integração
* **Guardrails** para manter o comportamento dos agentes seguro e em conformidade
* **Prompts versionados** para desempenho consistente dos agentes
### Instalação & Configuração
Os traces fornecem uma visão hierárquica da execução do seu crew, mostrando a sequência de chamadas LLM, ativações de ferramentas e transições de estado.
```python
# Adicione trace_id para habilitar o tracing hierárquico no Portkey
portkey_llm = LLM(
model="gpt-4o",
base_url=PORTKEY_GATEWAY_URL,
api_key="dummy",
extra_headers=createHeaders(
api_key="YOUR_PORTKEY_API_KEY",
virtual_key="YOUR_OPENAI_VIRTUAL_KEY",
trace_id="unique-session-id" # Adicione um trace ID único
)
)
```
Portkey registra cada interação com LLMs, incluindo:
* Payloads completos das requisições e respostas
* Métricas de latência e uso de tokens
* Cálculos de custo
* Chamadas de ferramentas e execuções de funções
Todos os logs podem ser filtrados por metadados, trace IDs, modelos e mais, tornando mais fácil depurar execuções específicas do crew.
Portkey oferece dashboards integrados que ajudam você a:
* Rastrear custos e uso de tokens em todas as execuções do crew
* Analisar métricas de desempenho, como latência e taxas de sucesso
* Identificar gargalos nos fluxos de trabalho dos agentes
* Comparar diferentes configurações de crew e LLMs
Você pode filtrar e segmentar todas as métricas por metadados personalizados para analisar tipos de crew, grupos de usuários ou casos de uso específicos.
Adicione metadados personalizados à configuração LLM do seu CrewAI para permitir filtragem e segmentação poderosas:
```python
portkey_llm = LLM(
model="gpt-4o",
base_url=PORTKEY_GATEWAY_URL,
api_key="dummy",
extra_headers=createHeaders(
api_key="YOUR_PORTKEY_API_KEY",
virtual_key="YOUR_OPENAI_VIRTUAL_KEY",
metadata={
"crew_type": "research_crew",
"environment": "production",
"_user": "user_123", # Campo especial _user para analytics de usuários
"request_source": "mobile_app"
}
)
)
```
Esses metadados podem ser usados para filtrar logs, traces e métricas no painel do Portkey, permitindo analisar execuções específicas do crew, usuários ou ambientes.
Isso permite:
* Rastreamento de custos e orçamento por usuário
* Analytics personalizados por usuário
* Métricas por equipe ou organização
* Monitoramento específico por ambiente (homologação x produção)
Documentação oficial do CrewAI
Receba orientação personalizada sobre como implementar essa integração
```python
from crewai import LLM
# Criar uma instância de LLM com o AI Gateway da TrueFoundry
truefoundry_llm = LLM(
model="openai-main/gpt-4o", # Da mesma forma, você pode chamar qualquer modelo de qualquer provedor
base_url="your_truefoundry_gateway_base_url",
api_key="your_truefoundry_api_key"
)
# Usar nos seus agentes do CrewAI
from crewai import Agent
@agent
def researcher(self) -> Agent:
return Agent(
config=self.agents_config['researcher'],
llm=truefoundry_llm,
verbose=True
)
```
Com o AI Gateway da TrueFoundry, você pode monitorar e analisar:
* **Métricas de desempenho**: Acompanhe métricas-chave de latência como Latência da Requisição, Tempo até o Primeiro Token (TTFS) e Latência entre Tokens (ITL), com percentis P99, P90 e P50
* **Custos e uso de tokens**: Tenha visibilidade dos custos da sua aplicação com detalhamento de tokens de entrada/saída e das despesas associadas a cada modelo
* **Padrões de uso**: Entenda como sua aplicação está sendo utilizada com análises detalhadas sobre atividade de usuários, distribuição de modelos e uso por equipe
* **Limite de taxa e balanceamento de carga**: Você pode configurar rate limiting, balanceamento de carga e fallback para seus modelos
## Rastreamento
Para uma compreensão mais detalhada sobre rastreamento, consulte [getting-started-tracing](https://docs.truefoundry.com/docs/tracing/tracing-getting-started). Para rastreamento, você pode adicionar o SDK do Traceloop:
```bash
pip install traceloop-sdk
```
```python
from traceloop.sdk import Traceloop
# Inicializar rastreamento avançado
Traceloop.init(
api_endpoint="https://your-truefoundry-endpoint/api/tracing",
headers={
"Authorization": f"Bearer {your_truefoundry_pat_token}",
"TFY-Tracing-Project": "your_project_name",
},
)
```
Isso oferece correlação adicional de rastreamentos em todo o seu fluxo de trabalho com o CrewAI.
# Integração com Weave
Source: https://docs.crewai.com/pt-BR/observability/weave
Saiba como usar o Weights & Biases (W&B) Weave para rastrear, experimentar, avaliar e melhorar suas aplicações CrewAI.
# Visão Geral do Weave
[Weights & Biases (W\&B) Weave](https://weave-docs.wandb.ai/) é um framework para rastreamento, experimentação, avaliação, implementação e aprimoramento de aplicações baseadas em LLM.
O Weave oferece suporte completo para todas as etapas do desenvolvimento da sua aplicação CrewAI:
* **Rastreamento e Monitoramento**: Acompanhe automaticamente chamadas LLM e a lógica da aplicação para depuração e análise de sistemas em produção
* **Iteração Sistemática**: Aperfeiçoe e itere em prompts, conjuntos de dados e modelos
* **Avaliação**: Utilize avaliadores personalizados ou pré-construídos para avaliar e aprimorar sistematicamente o desempenho dos agentes
* **Guardrails**: Proteja seus agentes com salvaguardas pré e pós-execução para moderação de conteúdo e segurança de prompts
O Weave captura automaticamente rastreamentos (traces) de suas aplicações CrewAI, permitindo monitorar e analisar o desempenho, as interações e o fluxo de execução dos seus agentes. Isso te ajuda a construir melhores conjuntos de dados para avaliação e a otimizar os fluxos de trabalho dos agentes.
## Instruções de Configuração