andre/crewAI
1
0
Fork 0
mirror of https://github.com/crewAIInc/crewAI.git synced 2026-01-10 08:38:30 +00:00
Code Issues Actions 4 Packages Projects Releases Wiki Activity

Add pt-BR docs translation (#3039)

Browse Source 
* docs: add pt-br translations

Powered by a CrewAI Flow https://github.com/danielfsbarreto/docs_translator

* Update mcp/overview.mdx brazilian docs

Its en-US counterpart was updated after I did a pass,
so now it includes the new section about @CrewBase
This commit is contained in:
Daniel Barreto
2025-06-25 12:52:33 -03:00
committed by GitHub
parent f6dfec61d6
commit a50fae3a4b
339 changed files with 33822 additions and 517 deletions
Download Patch File Download Diff File Expand all files Collapse all files

60
docs/pt-BR/learn/before-and-after-kickoff-hooks.mdx Normal file
View File

@@ -0,0 +1,60 @@
---
title: Hooks Antes e Depois do Kickoff
description: Aprenda a usar hooks antes e depois do kickoff em CrewAI
---
O CrewAI fornece hooks que permitem executar código antes e depois do kickoff de uma crew. Esses hooks são úteis para pré-processar entradas ou pós-processar resultados.
## Hook Antes do Kickoff
O hook antes do kickoff é executado antes da crew iniciar suas tarefas. Ele recebe o dicionário de entradas e pode modificá-lo antes de passá-lo para a crew. Você pode usar esse hook para configurar seu ambiente, carregar dados necessários ou pré-processar suas entradas. Isso é útil em cenários onde os dados de entrada podem precisar de enriquecimento ou validação antes de serem processados pela crew.
Aqui está um exemplo de como definir uma função antes do kickoff em seu `crew.py`:
```python
from crewai import CrewBase
from crewai.project import before_kickoff
@CrewBase
class MyCrew:
@before_kickoff
def prepare_data(self, inputs):
# Preprocess or modify inputs
inputs['processed'] = True
return inputs
#...
```
Neste exemplo, a função prepare_data modifica as entradas adicionando um novo par chave-valor indicando que as entradas foram processadas.
## Hook Depois do Kickoff
O hook depois do kickoff é executado após a crew completar suas tarefas. Ele recebe o objeto de resultado, que contém as saídas da execução da crew. Este hook é ideal para pós-processar resultados, como log, transformação de dados ou análise adicional.
Veja como você pode definir uma função depois do kickoff em seu `crew.py`:
```python
from crewai import CrewBase
from crewai.project import after_kickoff
@CrewBase
class MyCrew:
@after_kickoff
def log_results(self, result):
# Log or modify the results
print("Crew execution completed with result:", result)
return result
# ...
```
Na função `log_results`, os resultados da execução da crew são simplesmente impressos. Você pode estender isso para realizar operações mais complexas, como enviar notificações ou integrar com outros serviços.
## Utilizando Ambos os Hooks
Ambos os hooks podem ser usados juntos para oferecer um processo completo de preparação e finalização na execução da sua crew. Eles são particularmente úteis para manter uma arquitetura de código limpa, separando responsabilidades e melhorando a modularidade das suas implementações com CrewAI.
## Conclusão
Os hooks antes e depois do kickoff em CrewAI oferecem formas poderosas de interagir com o ciclo de vida da execução de uma crew. Ao entender e utilizar esses hooks, você pode aumentar significativamente a robustez e flexibilidade dos seus agentes de IA.

441
docs/pt-BR/learn/bring-your-own-agent.mdx Normal file
View File

@@ -0,0 +1,441 @@
---
title: Traga seu próprio agente
description: Aprenda como trazer seus próprios agentes que funcionam dentro de uma Crew.
icon: robots
---
Interoperabilidade é um conceito fundamental no CrewAI. Este guia mostrará como trazer seus próprios agentes para funcionar dentro de uma Crew.
## Guia de Adaptação para trazer seus próprios agentes (Agentes Langgraph, Agentes OpenAI, etc...)
Requeremos 3 adaptadores para tornar qualquer agente de diferentes frameworks compatível com uma crew.
1. BaseAgentAdapter
2. BaseToolAdapter
3. BaseConverter
## BaseAgentAdapter
Esta classe abstrata define a interface comum e a funcionalidade que todos
os adaptadores de agente devem implementar. Ela estende BaseAgent para manter compatibilidade
com o framework CrewAI, ao mesmo tempo em que adiciona requisitos específicos do adaptador.
Métodos obrigatórios:
1. `def configure_tools`
2. `def configure_structured_output`
## Criando seu próprio Adaptador
Para integrar um agente de um framework diferente (por exemplo, LangGraph, Autogen, OpenAI Assistants) ao CrewAI, você precisa criar um adaptador customizado herdando de `BaseAgentAdapter`. Esse adaptador atua como uma camada de compatibilidade, traduzindo entre as interfaces do CrewAI e os requisitos específicos do seu agente externo.
Veja como implementar seu adaptador customizado:
1. **Herdar de `BaseAgentAdapter`**:
```python
from crewai.agents.agent_adapters.base_agent_adapter import BaseAgentAdapter
from crewai.tools import BaseTool
from typing import List, Optional, Any, Dict
class MyCustomAgentAdapter(BaseAgentAdapter):
# ... detalhes da implementação ...
```
2. **Implementar `__init__`**:
O construtor deve chamar o construtor da classe pai `super().__init__(**kwargs)` e executar qualquer inicialização específica do seu agente externo. Você pode usar o dicionário opcional `agent_config` passado durante a inicialização do `Agent` do CrewAI para configurar seu adaptador e o agente subjacente.
```python
def __init__(self, agent_config: Optional[Dict[str, Any]] = None, **kwargs: Any):
super().__init__(agent_config=agent_config, **kwargs)
# Inicialize seu agente externo aqui, possivelmente usando agent_config
# Exemplo: self.external_agent = initialize_my_agent(agent_config)
print(f"Inicializando MyCustomAgentAdapter com config: {agent_config}")
```
3. **Implementar `configure_tools`**:
Este método abstrato é crucial. Ele recebe uma lista de instâncias de `BaseTool` do CrewAI. Sua implementação deve converter ou adaptar essas ferramentas para o formato esperado pelo seu framework de agente externo. Isso pode envolver encapsulamento, extração de atributos específicos ou registro delas na instância do agente externo.
```python
def configure_tools(self, tools: Optional[List[BaseTool]] = None) -> None:
if tools:
adapted_tools = []
for tool in tools:
# Adapte o CrewAI BaseTool para o formato que seu agente espera
# Exemplo: adapted_tool = adapt_to_my_framework(tool)
# adapted_tools.append(adapted_tool)
pass # Substitua pela sua lógica real de adaptação
# Configure o agente externo com as ferramentas adaptadas
# Exemplo: self.external_agent.set_tools(adapted_tools)
print(f"Configurando ferramentas para MyCustomAgentAdapter: {adapted_tools}") # Placeholder
else:
# Caso nenhum ferramenta seja fornecida
# Exemplo: self.external_agent.set_tools([])
print("Nenhuma ferramenta fornecida para MyCustomAgentAdapter.")
```
4. **Implementar `configure_structured_output`**:
Esse método é chamado quando o `Agent` do CrewAI é configurado com requisitos de saída estruturada (por exemplo, `output_json` ou `output_pydantic`). Seu adaptador precisa garantir que o agente externo esteja configurado para cumprir esses requisitos. Isso pode envolver definir parâmetros específicos no agente externo ou garantir que seu modelo subjacente suporte o formato solicitado. Se o agente externo não suportar saída estruturada de forma compatível com as expectativas do CrewAI, talvez seja necessário lidar com a conversão ou lançar um erro apropriado.
```python
def configure_structured_output(self, structured_output: Any) -> None:
# Configure seu agente externo para produzir saída no formato especificado
# Exemplo: self.external_agent.set_output_format(structured_output)
self.adapted_structured_output = True # Sinaliza que a saída estruturada foi tratada
print(f"Configurando saída estruturada para MyCustomAgentAdapter: {structured_output}")
```
Implementando esses métodos, seu `MyCustomAgentAdapter` permitirá que sua implementação personalizada de agente funcione corretamente dentro de uma crew do CrewAI, interagindo com tarefas e ferramentas de forma transparente. Lembre-se de substituir os comentários e prints de exemplo pela sua lógica real de adaptação específica do framework externo que está integrando.
## Implementação de BaseToolAdapter
A classe `BaseToolAdapter` é responsável por converter os objetos nativos `BaseTool` do CrewAI em um formato que o seu framework de agente externo possa entender e utilizar. Diferentes frameworks de agentes (como LangGraph, OpenAI Assistants, etc.) possuem suas próprias formas de definir e tratar ferramentas, e o `BaseToolAdapter` age como tradutor.
Veja como implementar seu adaptador de ferramentas personalizado:
1. **Herdar de `BaseToolAdapter`**:
```python
from crewai.agents.agent_adapters.base_tool_adapter import BaseToolAdapter
from crewai.tools import BaseTool
from typing import List, Any
class MyCustomToolAdapter(BaseToolAdapter):
# ... detalhes da implementação ...
```
2. **Implementar `configure_tools`**:
Este é o método abstrato principal que você deve implementar. Ele recebe uma lista de instâncias de `BaseTool` fornecidas ao agente. Sua tarefa é iterar por essa lista, adaptar cada `BaseTool` para o formato esperado pelo seu framework externo e armazenar as ferramentas convertidas na lista `self.converted_tools` (inicializada no construtor da classe base).
```python
def configure_tools(self, tools: List[BaseTool]) -> None:
"""Configura e converte ferramentas do CrewAI para a implementação específica."""
self.converted_tools = [] # Reseta caso seja chamado múltiplas vezes
for tool in tools:
# Sanitizar o nome da ferramenta se necessário pelo framework alvo
sanitized_name = self.sanitize_tool_name(tool.name)
# --- Sua lógica de conversão aqui ---
# Exemplo: Converter BaseTool para formato de dicionário para LangGraph
# converted_tool = {
# "name": sanitized_name,
# "description": tool.description,
# "parameters": tool.args_schema.schema() if tool.args_schema else {},
# # Adicione outros campos específicos do framework
# }
# Exemplo: Converter BaseTool para definição de função OpenAI
# converted_tool = {
# "type": "function",
# "function": {
# "name": sanitized_name,
# "description": tool.description,
# "parameters": tool.args_schema.schema() if tool.args_schema else {"type": "object", "properties": {}},
# }
# }
# --- Substitua os exemplos acima pela sua adaptação real ---
converted_tool = self.adapt_tool_to_my_framework(tool, sanitized_name) # Placeholder
self.converted_tools.append(converted_tool)
print(f"Ferramenta '{tool.name}' adaptada para '{sanitized_name}' em MyCustomToolAdapter") # Placeholder
print(f"MyCustomToolAdapter terminou de configurar ferramentas: {len(self.converted_tools)} adaptadas.") # Placeholder
# --- Método auxiliar para adaptação (Exemplo) ---
def adapt_tool_to_my_framework(self, tool: BaseTool, sanitized_name: str) -> Any:
# Substitua pela lógica real para converter um CrewAI BaseTool
# para o formato necessário do framework de agente externo específico.
# Isso pode variar bastante de acordo com o framework.
adapted_representation = {
"framework_specific_name": sanitized_name,
"framework_specific_description": tool.description,
"inputs": tool.args_schema.schema() if tool.args_schema else None,
"implementation_reference": tool.run # Ou conforme o framework precisa chamar
}
# Certifique-se também que a ferramenta funcione tanto síncrona quanto assincronamente
async def async_tool_wrapper(*args, **kwargs):
output = tool.run(*args, **kwargs)
if inspect.isawaitable(output):
return await output
else:
return output
adapted_tool = MyFrameworkTool(
name=sanitized_name,
description=tool.description,
inputs=tool.args_schema.schema() if tool.args_schema else None,
implementation_reference=async_tool_wrapper
)
return adapted_representation
```
3. **Utilizando o Adaptador**:
Normalmente, você instanciaria seu `MyCustomToolAdapter` dentro do método `configure_tools` do seu `MyCustomAgentAdapter` e o usaria para processar as ferramentas antes de configurar o agente externo.
```python
# Dentro de MyCustomAgentAdapter.configure_tools
def configure_tools(self, tools: Optional[List[BaseTool]] = None) -> None:
if tools:
tool_adapter = MyCustomToolAdapter() # Instancia seu adaptador de ferramenta
tool_adapter.configure_tools(tools) # Converte as ferramentas
adapted_tools = tool_adapter.tools() # Obtém as ferramentas convertidas
# Agora configure seu agente externo com as ferramentas adaptadas
# Exemplo: self.external_agent.set_tools(adapted_tools)
print(f"Configurando agente externo com ferramentas adaptadas: {adapted_tools}") # Placeholder
else:
# Caso sem ferramentas
print("Nenhuma ferramenta fornecida para MyCustomAgentAdapter.")
```
Ao criar um `BaseToolAdapter`, você desacopla a lógica de conversão de ferramenta da adaptação de agente, tornando a integração mais limpa e modular. Lembre-se de substituir os exemplos de placeholder pela lógica de conversão real exigida pelo seu framework externo específico.
## BaseConverter
O `BaseConverterAdapter` desempenha um papel crucial quando uma `Task` do CrewAI exige que um agente retorne sua saída final em um formato estruturado específico, como JSON ou um modelo Pydantic. Ele faz a ponte entre os requisitos de saída estruturada do CrewAI e as capacidades do seu agente externo.
Suas responsabilidades principais são:
1. **Configurar o Agente para Saída Estruturada:** Com base nos requisitos da `Task` (`output_json` ou `output_pydantic`), ele instrui o `BaseAgentAdapter` associado (e indiretamente, o agente externo) sobre qual formato é esperado.
2. **Apriorar o Prompt do Sistema:** Ele modifica o prompt do sistema do agente para incluir instruções claras sobre *como* gerar a saída na estrutura exigida.
3. **Pós-processamento do Resultado:** Pega a saída bruta do agente e tenta fazer parsing, validar e formatar conforme a estrutura requerida, retornando por fim uma representação em string (por exemplo, uma string JSON).
Veja como implementar seu adaptador de conversão customizado:
1. **Herdar de `BaseConverterAdapter`**:
```python
from crewai.agents.agent_adapters.base_converter_adapter import BaseConverterAdapter
# Supondo que o seu MyCustomAgentAdapter foi definido
# from .my_custom_agent_adapter import MyCustomAgentAdapter
from crewai.task import Task
from typing import Any
class MyCustomConverterAdapter(BaseConverterAdapter):
# Armazena o tipo de saída esperado (ex: 'json', 'pydantic', 'text')
_output_type: str = 'text'
_output_schema: Any = None # Armazena o schema JSON ou modelo Pydantic
# ... detalhes da implementação ...
```
2. **Implementar `__init__`**:
O construtor deve aceitar a instância correspondente de `agent_adapter` com a qual irá trabalhar.
```python
def __init__(self, agent_adapter: Any): # Use um type hint específico para seu AgentAdapter
self.agent_adapter = agent_adapter
print(f"Inicializando MyCustomConverterAdapter para o adaptador de agente: {type(agent_adapter).__name__}")
```
3. **Implementar `configure_structured_output`**:
Esse método recebe o objeto `Task` do CrewAI. Você precisa checar os atributos `output_json` e `output_pydantic` da task para determinar a estrutura de saída exigida. Armazene essa informação (por exemplo, em `_output_type` e `_output_schema`) e, potencialmente, chame métodos de configuração no seu `self.agent_adapter` se o agente externo necessitar de um ajuste específico para saída estruturada (algo que pode já ter sido parcialmente feito no `configure_structured_output` do adaptador de agente).
```python
def configure_structured_output(self, task: Task) -> None:
"""Configura a saída estruturada esperada baseada na task."""
if task.output_pydantic:
self._output_type = 'pydantic'
self._output_schema = task.output_pydantic
print(f"Converter: Configurado para saída Pydantic: {self._output_schema.__name__}")
elif task.output_json:
self._output_type = 'json'
self._output_schema = task.output_json
print(f"Converter: Configurado para saída JSON com schema: {self._output_schema}")
else:
self._output_type = 'text'
self._output_schema = None
print("Converter: Configurado para saída de texto padrão.")
# Opcionalmente, informe o agent_adapter se necessário
# self.agent_adapter.set_output_mode(self._output_type, self._output_schema)
```
4. **Implementar `enhance_system_prompt`**:
Este método recebe o prompt base do sistema do agente e deve anexar instruções adaptadas para o `_output_type` e `_output_schema` atualmente configurados. O objetivo é guiar o LLM que alimenta o agente a produzir saída no formato correto.
```python
def enhance_system_prompt(self, base_prompt: str) -> str:
"""Aprimore o prompt do sistema com instruções de saída estruturada."""
if self._output_type == 'text':
return base_prompt # Nenhum aprimoramento necessário para texto puro
instructions = "\n\nSua resposta final DEVE estar formatada como "
if self._output_type == 'json':
schema_str = json.dumps(self._output_schema, indent=2)
instructions += f"um objeto JSON conforme o seguinte schema:\n```json\n{schema_str}\n```"
elif self._output_type == 'pydantic':
schema_str = json.dumps(self._output_schema.model_json_schema(), indent=2)
instructions += f"um objeto JSON conforme o modelo Pydantic '{self._output_schema.__name__}' com o seguinte schema:\n```json\n{schema_str}\n```"
instructions += "\nGaranta que toda a sua resposta seja APENAS o objeto JSON válido, sem nenhum texto introdutório, explicações ou considerações finais."
print(f"Converter: Aprimorando prompt para saída {self._output_type}.")
return base_prompt + instructions
```
*Nota: O prompt pode precisar de ajustes conforme o agente/LLM usado.*
5. **Implementar `post_process_result`**:
Esse método recebe a saída em string bruta do agente. Se uma saída estruturada foi solicitada (`json` ou `pydantic`), você deve tentar convertê-la para o formato esperado. Trate erros de parsing caso ocorram (por exemplo, registre-os, tente corrigir, ou lance uma exceção). O método **deve sempre retornar uma string**, mesmo se o formato intermediário seja um dicionário ou objeto Pydantic (por exemplo, serializando novamente para JSON).
```python
import json
from pydantic import ValidationError
def post_process_result(self, result: str) -> str:
"""Pós-processa o resultado do agente para garantir que corresponde ao formato esperado."""
print(f"Converter: Pós-processando resultado para saída {self._output_type}.")
if self._output_type == 'json':
try:
# Tenta fazer parsing e re-serializar para garantir validade e formato consistente
parsed_json = json.loads(result)
# Opcional: Validar contra o schema se for um dicionário JSON schema
# from jsonschema import validate
# validate(instance=parsed_json, schema=self._output_schema)
return json.dumps(parsed_json)
except json.JSONDecodeError as e:
print(f"Erro: Falha ao fazer parsing da saída JSON: {e}\nSaída bruta:\n{result}")
# Trate o erro: retorne bruto, lance exceção, ou tente corrigir
return result # Exemplo: retorna a saída bruta caso falhe
# except Exception as e: # Captura erros de validação se usar jsonschema
# print(f"Erro: saída JSON falhou na validação do schema: {e}\nSaída bruta:\n{result}")
# return result
elif self._output_type == 'pydantic':
try:
# Tenta fazer parsing para o modelo Pydantic
model_instance = self._output_schema.model_validate_json(result)
# Retorna o modelo serializado de volta para JSON
return model_instance.model_dump_json()
except ValidationError as e:
print(f"Erro: Falha ao validar saída Pydantic: {e}\nSaída bruta:\n{result}")
# Trate o erro
return result # Exemplo: retorna a saída bruta caso falhe
except json.JSONDecodeError as e:
print(f"Erro: Falha ao fazer parsing do JSON para o modelo Pydantic: {e}\nSaída bruta:\n{result}")
return result
else: # 'text'
return result # Sem processamento para texto puro
```
Implementando esses métodos, seu `MyCustomConverterAdapter` assegurará que as solicitações de saída estruturada das tarefas do CrewAI sejam corretamente tratadas pelo seu agente externo integrado, aumentando a confiabilidade e a usabilidade do seu agente customizado dentro do framework CrewAI.
## Adapters prontos para uso
Fornecemos adapters prontos para uso para os seguintes frameworks:
1. LangGraph
2. Agentes OpenAI
## Iniciando uma crew com agentes adaptados:
```python
import json
import os
from typing import List
from crewai_tools import SerperDevTool
from src.crewai import Agent, Crew, Task
from langchain_openai import ChatOpenAI
from pydantic import BaseModel
from crewai.agents.agent_adapters.langgraph.langgraph_adapter import (
LangGraphAgentAdapter,
)
from crewai.agents.agent_adapters.openai_agents.openai_adapter import OpenAIAgentAdapter
# Agente CrewAI
code_helper_agent = Agent(
role="Code Helper",
goal="Help users solve coding problems effectively and provide clear explanations.",
backstory="You are an experienced programmer with deep knowledge across multiple programming languages and frameworks. You specialize in solving complex coding challenges and explaining solutions clearly.",
allow_delegation=False,
verbose=True,
)
# OpenAI Agent Adapter
link_finder_agent = OpenAIAgentAdapter(
role="Link Finder",
goal="Find the most relevant and high-quality resources for coding tasks.",
backstory="You are a research specialist with a talent for finding the most helpful resources. You're skilled at using search tools to discover documentation, tutorials, and examples that directly address the user's coding needs.",
tools=[SerperDevTool()],
allow_delegation=False,
verbose=True,
)
# LangGraph Agent Adapter
reporter_agent = LangGraphAgentAdapter(
role="Reporter",
goal="Report the results of the tasks.",
backstory="You are a reporter who reports the results of the other tasks",
llm=ChatOpenAI(model="gpt-4o"),
allow_delegation=True,
verbose=True,
)
class Code(BaseModel):
code: str
task = Task(
description="Give an answer to the coding question: {task}",
expected_output="A thorough answer to the coding question: {task}",
agent=code_helper_agent,
output_json=Code,
)
task2 = Task(
description="Find links to resources that can help with coding tasks. Use the serper tool to find resources that can help.",
expected_output="A list of links to resources that can help with coding tasks",
agent=link_finder_agent,
)
class Report(BaseModel):
code: str
links: List[str]
task3 = Task(
description="Report the results of the tasks.",
expected_output="A report of the results of the tasks. this is the code produced and then the links to the resources that can help with the coding task.",
agent=reporter_agent,
output_json=Report,
)
# Usando no CrewAI
crew = Crew(
agents=[code_helper_agent, link_finder_agent, reporter_agent],
tasks=[task, task2, task3],
verbose=True,
)
result = crew.kickoff(
inputs={"task": "How do you implement an abstract class in python?"}
)
# Imprima o resultado bruto primeiro
print("Raw result:", result)
# Lide com o resultado de acordo com seu tipo
if hasattr(result, "json_dict") and result.json_dict:
json_result = result.json_dict
print("\nStructured JSON result:")
print(f"{json.dumps(json_result, indent=2)}")
# Acesse os campos de forma segura
if isinstance(json_result, dict):
if "code" in json_result:
print("\nCode:")
print(
json_result["code"][:200] + "..."
if len(json_result["code"]) > 200
else json_result["code"]
)
if "links" in json_result:
print("\nLinks:")
for link in json_result["links"][:5]: # Print first 5 links
print(f"- {link}")
if len(json_result["links"]) > 5:
print(f"...and {len(json_result['links']) - 5} more links")
elif hasattr(result, "pydantic") and result.pydantic:
print("\nPydantic model result:")
print(result.pydantic.model_dump_json(indent=2))
else:
# Fallback para saída bruta
print("\nNo structured result available, using raw output:")
print(result.raw[:500] + "..." if len(result.raw) > 500 else result.raw)
```

95
docs/pt-BR/learn/coding-agents.mdx Normal file
View File

@@ -0,0 +1,95 @@
---
title: Agentes de Codificação
description: Aprenda como habilitar seus Agentes CrewAI para escrever e executar código, e explore funcionalidades avançadas para maior potencial.
icon: rectangle-code
---
## Introdução
Os Agentes CrewAI agora têm a poderosa capacidade de escrever e executar código, aumentando significativamente suas habilidades de resolução de problemas. Esse recurso é particularmente útil para tarefas que exigem soluções computacionais ou programáticas.
## Habilitando a Execução de Código
Para habilitar a execução de código para um agente, defina o parâmetro `allow_code_execution` como `True` ao criar o agente.
Veja um exemplo:
```python Code
from crewai import Agent
coding_agent = Agent(
role="Senior Python Developer",
goal="Craft well-designed and thought-out code",
backstory="You are a senior Python developer with extensive experience in software architecture and best practices.",
allow_code_execution=True
)
```
<Note>
Observe que o parâmetro `allow_code_execution` é `False` por padrão.
</Note>
## Considerações Importantes
1. **Seleção de Modelo**: É fortemente recomendado utilizar modelos mais avançados como Claude 3.5 Sonnet e GPT-4 ao habilitar a execução de código.
Esses modelos têm melhor compreensão de conceitos de programação e tendem a gerar códigos mais corretos e eficientes.
2. **Tratamento de Erros**: O recurso de execução de código inclui tratamento de erros. Se o código executado gerar uma exceção, o agente receberá a mensagem de erro e poderá tentar corrigir o código ou
fornecer soluções alternativas. O parâmetro `max_retry_limit`, que por padrão é 2, controla o número máximo de tentativas para uma tarefa.
3. **Dependências**: Para usar o recurso de execução de código, é necessário instalar o pacote `crewai_tools`. Caso não esteja instalado, o agente registrará uma mensagem informativa:
"Ferramentas de codificação não disponíveis. Instale crewai_tools."
## Processo de Execução de Código
Quando um agente com execução de código habilitada encontra uma tarefa que requer programação:
<Steps>
<Step title="Análise da Tarefa">
O agente analisa a tarefa e determina que a execução de código é necessária.
</Step>
<Step title="Formulação do Código">
Ele formula o código Python necessário para resolver o problema.
</Step>
<Step title="Execução do Código">
O código é enviado para a ferramenta interna de execução de código (`CodeInterpreterTool`).
</Step>
<Step title="Interpretação dos Resultados">
O agente interpreta o resultado e o incorpora na sua resposta ou o utiliza para aprofundar a solução do problema.
</Step>
</Steps>
## Exemplo de Uso
Veja um exemplo detalhado de como criar um agente com capacidade de execução de código e utilizá-lo em uma tarefa:
```python Code
from crewai import Agent, Task, Crew
# Create an agent with code execution enabled
coding_agent = Agent(
role="Python Data Analyst",
goal="Analyze data and provide insights using Python",
backstory="You are an experienced data analyst with strong Python skills.",
allow_code_execution=True
)
# Create a task that requires code execution
data_analysis_task = Task(
description="Analyze the given dataset and calculate the average age of participants.",
agent=coding_agent
)
# Create a crew and add the task
analysis_crew = Crew(
agents=[coding_agent],
tasks=[data_analysis_task]
)
# Execute the crew
result = analysis_crew.kickoff()
print(result)
```
Neste exemplo, o `coding_agent` pode escrever e executar código Python para realizar tarefas de análise de dados.

89
docs/pt-BR/learn/conditional-tasks.mdx Normal file
View File

@@ -0,0 +1,89 @@
---
title: Tarefas Condicionais
description: Saiba como usar tarefas condicionais em um kickoff do crewAI
icon: diagram-subtask
---
## Introdução
As Tarefas Condicionais no crewAI permitem a adaptação dinâmica do fluxo de trabalho com base nos resultados de tarefas anteriores.
Esse recurso poderoso possibilita que crews tomem decisões e executem tarefas seletivamente, aumentando a flexibilidade e a eficiência dos seus processos orientados por IA.
## Exemplo de Uso
```python Code
from typing import List
from pydantic import BaseModel
from crewai import Agent, Crew
from crewai.tasks.conditional_task import ConditionalTask
from crewai.tasks.task_output import TaskOutput
from crewai.task import Task
from crewai_tools import SerperDevTool
# Define a condition function for the conditional task
# If false, the task will be skipped, if true, then execute the task.
def is_data_missing(output: TaskOutput) -> bool:
return len(output.pydantic.events) < 10 # this will skip this task
# Define the agents
data_fetcher_agent = Agent(
role="Data Fetcher",
goal="Fetch data online using Serper tool",
backstory="Backstory 1",
verbose=True,
tools=[SerperDevTool()]
)
data_processor_agent = Agent(
role="Data Processor",
goal="Process fetched data",
backstory="Backstory 2",
verbose=True
)
summary_generator_agent = Agent(
role="Summary Generator",
goal="Generate summary from fetched data",
backstory="Backstory 3",
verbose=True
)
class EventOutput(BaseModel):
events: List[str]
task1 = Task(
description="Fetch data about events in San Francisco using Serper tool",
expected_output="List of 10 things to do in SF this week",
agent=data_fetcher_agent,
output_pydantic=EventOutput,
)
conditional_task = ConditionalTask(
description="""
Check if data is missing. If we have less than 10 events,
fetch more events using Serper tool so that
we have a total of 10 events in SF this week..
""",
expected_output="List of 10 Things to do in SF this week",
condition=is_data_missing,
agent=data_processor_agent,
)
task3 = Task(
description="Generate summary of events in San Francisco from fetched data",
expected_output="A complete report on the customer and their customers and competitors, including their demographics, preferences, market positioning and audience engagement.",
agent=summary_generator_agent,
)
# Create a crew with the tasks
crew = Crew(
agents=[data_fetcher_agent, data_processor_agent, summary_generator_agent],
tasks=[task1, conditional_task, task3],
verbose=True,
planning=True
)
# Run the crew
result = crew.kickoff()
print("results", result)
```

69
docs/pt-BR/learn/create-custom-tools.mdx Normal file
View File

@@ -0,0 +1,69 @@
---
title: Criar Ferramentas Personalizadas
description: Guia abrangente sobre como criar, utilizar e gerenciar ferramentas personalizadas dentro do framework CrewAI, incluindo novas funcionalidades e tratamento de erros.
icon: hammer
---
## Criando e Utilizando Ferramentas no CrewAI
Este guia traz instruções detalhadas sobre como criar ferramentas personalizadas para o framework CrewAI e como gerenciar e utilizar essas ferramentas de forma eficiente,
incorporando funcionalidades recentes, como delegação de ferramentas, tratamento de erros e chamada dinâmica de ferramentas. Destaca também a importância de ferramentas de colaboração,
permitindo que agentes executem uma ampla gama de ações.
### Subclassificando `BaseTool`
Para criar uma ferramenta personalizada, herde de `BaseTool` e defina os atributos necessários, incluindo o `args_schema` para validação de entrada e o método `_run`.
```python Code
from typing import Type
from crewai.tools import BaseTool
from pydantic import BaseModel, Field
class MyToolInput(BaseModel):
"""Input schema for MyCustomTool."""
argument: str = Field(..., description="Description of the argument.")
class MyCustomTool(BaseTool):
name: str = "Name of my tool"
description: str = "What this tool does. It's vital for effective utilization."
args_schema: Type[BaseModel] = MyToolInput
def _run(self, argument: str) -> str:
# Your tool's logic here
return "Tool's result"
```
### Usando o Decorador `tool`
Como alternativa, você pode utilizar o decorador de ferramenta `@tool`. Esta abordagem permite definir os atributos e as funcionalidades da ferramenta diretamente em uma função,
oferecendo uma maneira concisa e eficiente de criar ferramentas especializadas de acordo com suas necessidades.
```python Code
from crewai.tools import tool
@tool("Tool Name")
def my_simple_tool(question: str) -> str:
"""Tool description for clarity."""
# Tool logic here
return "Tool output"
```
### Definindo uma Função de Cache para a Ferramenta
Para otimizar o desempenho da ferramenta com cache, defina estratégias de cache personalizadas utilizando o atributo `cache_function`.
```python Code
@tool("Tool with Caching")
def cached_tool(argument: str) -> str:
"""Tool functionality description."""
return "Cacheable result"
def my_cache_strategy(arguments: dict, result: str) -> bool:
# Define custom caching logic
return True if some_condition else False
cached_tool.cache_function = my_cache_strategy
```
Seguindo essas orientações e incorporando novas funcionalidades e ferramentas de colaboração nos seus processos de criação e gerenciamento de ferramentas,
você pode aproveitar ao máximo as capacidades do framework CrewAI, aprimorando tanto a experiência de desenvolvimento quanto a eficiência dos seus agentes de IA.

122
docs/pt-BR/learn/custom-llm.mdx Normal file
View File

@@ -0,0 +1,122 @@
---
title: Implementação de LLM Personalizada
description: Aprenda a criar implementações personalizadas de LLM no CrewAI.
icon: code
---
## Visão Geral
O CrewAI oferece suporte a implementações personalizadas de LLM por meio da classe abstrata `BaseLLM`. Isso permite integrar qualquer provedor de LLM que não tenha suporte nativo no LiteLLM ou implementar mecanismos de autenticação personalizados.
## Início Rápido
Aqui está uma implementação mínima de LLM personalizada:
```python
# (não traduzir blocos de código)
```
## Usando Seu LLM Personalizado
```python
# (não traduzir blocos de código)
```
## Métodos Necessários
### Construtor: `__init__()`
**Crítico**: Você deve chamar `super().__init__(model, temperature)` com os parâmetros necessários:
```python
# (não traduzir blocos de código)
```
### Método Abstrato: `call()`
O método `call()` é o núcleo da sua implementação de LLM. Ele deve:
- Aceitar mensagens (string ou lista de dicionários com 'role' e 'content')
- Retornar uma resposta como string
- Lidar com ferramentas e chamada de funções, se suportado
- Lançar exceções apropriadas para erros
### Métodos Opcionais
```python
# (não traduzir blocos de código)
```
## Padrões Comuns
### Tratamento de Erros
```python
# (não traduzir blocos de código)
```
### Autenticação Personalizada
```python
# (não traduzir blocos de código)
```
### Suporte a Stop Words
O CrewAI adiciona automaticamente `"\nObservation:"` como stop word para controlar o comportamento do agente. Se o seu LLM suporta stop words:
```python
# (não traduzir blocos de código)
```
Se o seu LLM não suporta stop words nativamente:
```python
# (não traduzir blocos de código)
```
## Chamada de Funções
Se o seu LLM suporta chamada de funções, implemente o fluxo completo:
```python
# (não traduzir blocos de código)
```
## Solução de Problemas
### Problemas Comuns
**Erros no Construtor**
```python
# ❌ Errado - parâmetros obrigatórios ausentes
def __init__(self, api_key: str):
super().__init__()
# ✅ Correto
def __init__(self, model: str, api_key: str, temperature: Optional[float] = None):
super().__init__(model=model, temperature=temperature)
```
**Chamada de Funções Não Funciona**
- Certifique-se de que `supports_function_calling()` retorna `True`
- Verifique se você lida com `tool_calls` na resposta
- Assegure-se de que o parâmetro `available_functions` está sendo corretamente utilizado
**Falhas de Autenticação**
- Verifique o formato e as permissões da chave de API
- Confira o formato do header de autenticação
- Certifique-se de que as URLs dos endpoints estão corretas
**Erros de Parsing de Resposta**
- Valide a estrutura da resposta antes de acessar campos aninhados
- Trate casos em que o content pode ser None
- Adicione tratamento de erros para respostas malformadas
## Testando Seu LLM Personalizado
```python
# (não traduzir blocos de código)
```
Este guia cobre o essencial para implementar LLMs personalizados no CrewAI.

90
docs/pt-BR/learn/custom-manager-agent.mdx Normal file
View File

@@ -0,0 +1,90 @@
---
title: Agente Gerente Personalizado
description: Saiba como definir um agente personalizado como gerente no CrewAI, proporcionando mais controle sobre o gerenciamento e a coordenação das tarefas.
icon: user-shield
---
# Definindo um Agente Específico como Gerente no CrewAI
O CrewAI permite que usuários definam um agente específico como gerente da crew, oferecendo mais controle sobre o gerenciamento e a coordenação das tarefas.
Esse recurso possibilita a personalização do papel gerencial para se adequar melhor às necessidades do seu projeto.
## Utilizando o Atributo `manager_agent`
### Agente Gerente Personalizado
O atributo `manager_agent` permite que você defina um agente personalizado para gerenciar a crew. Este agente supervisionará todo o processo, garantindo que as tarefas sejam concluídas de forma eficiente e com o mais alto padrão de qualidade.
### Exemplo
```python Code
import os
from crewai import Agent, Task, Crew, Process
# Define your agents
researcher = Agent(
role="Researcher",
goal="Conduct thorough research and analysis on AI and AI agents",
backstory="You're an expert researcher, specialized in technology, software engineering, AI, and startups. You work as a freelancer and are currently researching for a new client.",
allow_delegation=False,
)
writer = Agent(
role="Senior Writer",
goal="Create compelling content about AI and AI agents",
backstory="You're a senior writer, specialized in technology, software engineering, AI, and startups. You work as a freelancer and are currently writing content for a new client.",
allow_delegation=False,
)
# Define your task
task = Task(
description="Generate a list of 5 interesting ideas for an article, then write one captivating paragraph for each idea that showcases the potential of a full article on this topic. Return the list of ideas with their paragraphs and your notes.",
expected_output="5 bullet points, each with a paragraph and accompanying notes.",
)
# Define the manager agent
manager = Agent(
role="Project Manager",
goal="Efficiently manage the crew and ensure high-quality task completion",
backstory="You're an experienced project manager, skilled in overseeing complex projects and guiding teams to success. Your role is to coordinate the efforts of the crew members, ensuring that each task is completed on time and to the highest standard.",
allow_delegation=True,
)
# Instantiate your crew with a custom manager
crew = Crew(
agents=[researcher, writer],
tasks=[task],
manager_agent=manager,
process=Process.hierarchical,
)
# Start the crew's work
result = crew.kickoff()
```
## Benefícios de um Agente Gerente Personalizado
- **Controle aprimorado**: Adapte a abordagem de gerenciamento para atender às necessidades específicas do seu projeto.
- **Coordenação melhorada**: Assegure uma coordenação e gestão eficiente das tarefas por um agente experiente.
- **Gestão personalizável**: Defina funções e responsabilidades gerenciais que estejam alinhadas aos objetivos do seu projeto.
## Definindo um Manager LLM
Se você estiver utilizando o processo hierarchical e não quiser definir um agente gerente personalizado, é possível especificar o modelo de linguagem para o gerente:
```python Code
from crewai import LLM
manager_llm = LLM(model="gpt-4o")
crew = Crew(
agents=[researcher, writer],
tasks=[task],
process=Process.hierarchical,
manager_llm=manager_llm
)
```
<Note>
É necessário definir `manager_agent` ou `manager_llm` ao utilizar o processo hierarchical.
</Note>

111
docs/pt-BR/learn/customizing-agents.mdx Normal file
View File

@@ -0,0 +1,111 @@
---
title: Personalize Agentes
description: Um guia abrangente para adaptar agentes a funções específicas, tarefas e customizações avançadas dentro do framework CrewAI.
icon: user-pen
---
## Atributos Personalizáveis
A construção de uma equipe CrewAI eficiente depende da capacidade de adaptar dinamicamente seus agentes de IA para atender aos requisitos únicos de qualquer projeto. Esta seção aborda os atributos fundamentais que você pode personalizar.
### Principais Atributos para Personalização
| Atributo | Descrição |
|:------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **Role** | Especifica a função do agente dentro da equipe, como 'Analista' ou 'Representante de Atendimento ao Cliente'. |
| **Goal** | Define os objetivos do agente, alinhados à sua função e à missão geral da equipe. |
| **Backstory** | Fornece profundidade à persona do agente, aprimorando motivações e engajamento dentro da equipe. |
| **Tools** *(Opcional)* | Representa as capacidades ou métodos que o agente utiliza para tarefas, desde funções simples até integrações complexas. |
| **Cache** *(Opcional)* | Determina se o agente deve usar cache para o uso de ferramentas. |
| **Max RPM** | Define o número máximo de requisições por minuto (`max_rpm`). Pode ser definido como `None` para requisições ilimitadas a serviços externos. |
| **Verbose** *(Opcional)* | Ativa registros detalhados para depuração e otimização, fornecendo insights sobre os processos de execução. |
| **Allow Delegation** *(Opcional)* | Controla a delegação de tarefas para outros agentes, padrão é `False`. |
| **Max Iter** *(Opcional)* | Limita o número máximo de iterações (`max_iter`) para uma tarefa, prevenindo loops infinitos, com valor padrão de 25. |
| **Max Execution Time** *(Opcional)* | Define o tempo máximo permitido para que o agente complete uma tarefa. |
| **System Template** *(Opcional)* | Define o formato do sistema para o agente. |
| **Prompt Template** *(Opcional)* | Define o formato do prompt para o agente. |
| **Response Template** *(Opcional)* | Define o formato da resposta para o agente. |
| **Use System Prompt** *(Opcional)* | Controla se o agente irá usar um prompt de sistema durante a execução de tarefas. |
| **Respect Context Window** | Ativa uma janela deslizante de contexto por padrão, mantendo o tamanho do contexto. |
| **Max Retry Limit** | Define o número máximo de tentativas (`max_retry_limit`) para um agente em caso de erros. |
## Opções Avançadas de Personalização
Além dos atributos básicos, o CrewAI permite customizações mais profundas para aprimorar significativamente o comportamento e as capacidades de um agente.
### Personalização de Modelo de Linguagem
Agentes podem ser personalizados com modelos de linguagem específicos (`llm`) e modelos de linguagem com chamada de função (`function_calling_llm`), oferecendo controle avançado sobre o processamento e a tomada de decisão.
É importante notar que definir o `function_calling_llm` permite sobrescrever o modelo padrão de chamada de função da equipe, proporcionando maior grau de personalização.
## Ajustes de Performance e Depuração
Ajustar a performance do agente e monitorar suas operações é fundamental para a execução eficiente de tarefas.
### Modo Verbose e Limite de RPM
- **Modo Verbose**: Ativa o registro detalhado das ações do agente, útil para depuração e otimização. Especificamente, fornece insights sobre os processos de execução do agente, auxiliando na otimização de performance.
- **Limite de RPM**: Define o número máximo de requisições por minuto (`max_rpm`). Este atributo é opcional e pode ser definido como `None` para não haver limite, permitindo consultas ilimitadas a serviços externos, se necessário.
### Máximo de Iterações por Execução de Tarefa
O atributo `max_iter` permite ao usuário definir o número máximo de iterações que um agente pode executar para uma única tarefa, prevenindo loops infinitos ou execuções excessivamente longas.
O valor padrão é 25, fornecendo um equilíbrio entre profundidade e eficiência. Quando o agente chega próximo a esse número, ele tentará entregar a melhor resposta possível.
## Personalizando Agentes e Ferramentas
Agentes são personalizados definindo seus atributos e ferramentas durante a inicialização. As ferramentas são críticas para a funcionalidade do agente, permitindo que realizem tarefas especializadas.
O atributo `tools` deve ser um array de ferramentas que o agente pode utilizar, e, por padrão, é inicializado como uma lista vazia. As ferramentas podem ser adicionadas ou modificadas após a criação do agente para se adaptar a novos requisitos.
```shell
pip install 'crewai[tools]'
```
### Exemplo: Atribuindo Ferramentas a um Agente
```python Code
import os
from crewai import Agent
from crewai_tools import SerperDevTool
# Defina as chaves de API para inicialização da ferramenta
os.environ["OPENAI_API_KEY"] = "Sua Chave"
os.environ["SERPER_API_KEY"] = "Sua Chave"
# Inicialize uma ferramenta de busca
search_tool = SerperDevTool()
# Inicialize o agente com opções avançadas
agent = Agent(
role='Research Analyst',
goal='Provide up-to-date market analysis',
backstory='An expert analyst with a keen eye for market trends.',
tools=[search_tool],
memory=True, # Ativa memória
verbose=True,
max_rpm=None, # Sem limite de requisições por minuto
max_iter=25, # Valor padrão de máximo de iterações
)
```
## Delegação e Autonomia
Controlar a capacidade de um agente delegar tarefas ou fazer perguntas é fundamental para ajustar sua autonomia e a dinâmica de colaboração dentro do framework CrewAI. Por padrão,
o atributo `allow_delegation` agora é definido como `False`, desabilitando para que agentes busquem assistência ou deleguem tarefas conforme necessário. Esse comportamento padrão pode ser alterado para promover resolução colaborativa de problemas e
eficiência dentro do ecossistema CrewAI. Se necessário, a delegação pode ser ativada para atender requisitos operacionais específicos.
### Exemplo: Desabilitando Delegação para um Agente
```python Code
agent = Agent(
role='Content Writer',
goal='Write engaging content on market trends',
backstory='A seasoned writer with expertise in market analysis.',
allow_delegation=True # Habilitando delegação
)
```
## Conclusão
Personalizar agentes no CrewAI definindo seus papéis, objetivos, histórias e ferramentas, juntamente com opções avançadas como personalização de modelo de linguagem, memória, ajustes de performance e preferências de delegação,
proporciona uma equipe de IA sofisticada e preparada para enfrentar desafios complexos.

73
docs/pt-BR/learn/dalle-image-generation.mdx Normal file
View File

@@ -0,0 +1,73 @@
---
title: "Geração de Imagens com DALL-E"
description: "Aprenda a usar o DALL-E para geração de imagens com IA em seus projetos CrewAI"
icon: "image"
---
O CrewAI oferece integração com o DALL-E da OpenAI, permitindo que seus agentes de IA gerem imagens como parte de suas tarefas. Este guia irá orientá-lo sobre como configurar e utilizar a ferramenta DALL-E em seus projetos CrewAI.
## Pré-requisitos
- crewAI instalado (última versão)
- Chave de API OpenAI com acesso ao DALL-E
## Configurando a Ferramenta DALL-E
<Steps>
<Step title="Importe a ferramenta DALL-E">
```python
from crewai_tools import DallETool
```
</Step>
<Step title="Adicione a ferramenta DALL-E na configuração do seu agente">
```python
@agent
def researcher(self) -> Agent:
return Agent(
config=self.agents_config['researcher'],
tools=[SerperDevTool(), DallETool()], # Add DallETool to the list of tools
allow_delegation=False,
verbose=True
)
```
</Step>
</Steps>
## Utilizando a Ferramenta DALL-E
Depois de adicionar a ferramenta DALL-E ao seu agente, ele poderá gerar imagens baseadas em prompts de texto. A ferramenta retornará uma URL para a imagem gerada, que pode ser utilizada na resposta do agente ou repassada para outros agentes para processamento adicional.
### Exemplo de Configuração de Agente
```yaml
role: >
Pesquisador Sênior de Dados para Perfis do LinkedIn
goal: >
Encontrar perfis detalhados do LinkedIn com base no nome fornecido {name} e domínio {domain}
Gerar uma imagem com o Dall-e baseada no domínio {domain}
backstory: >
Você é um pesquisador experiente com habilidade para encontrar os perfis do LinkedIn mais relevantes.
Conhecido por sua eficiência em navegar no LinkedIn, você se destaca em reunir e apresentar
informações profissionais de forma clara e concisa.
```
### Resultado Esperado
O agente com a ferramenta DALL-E conseguirá gerar a imagem e fornecer uma URL em sua resposta. Você poderá então baixar a imagem.
<Frame>
<img src="/images/enterprise/dall-e-image.png" alt="Imagem DALL-E" />
</Frame>
## 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.

50
docs/pt-BR/learn/force-tool-output-as-result.mdx Normal file
View File

@@ -0,0 +1,50 @@
---
title: Forçar a Saída da Ferramenta como Resultado
description: Aprenda como forçar a saída de uma ferramenta como resultado em uma tarefa de Agent no CrewAI.
icon: wrench-simple
---
## 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
<Steps>
<Step title="Execução da Tarefa">
O agent executa a tarefa utilizando a ferramenta fornecida.
</Step>
<Step title="Saída da Ferramenta">
A ferramenta gera a saída, que é capturada como resultado da tarefa.
</Step>
<Step title="Interação do Agent">
O agent pode refletir e aprender com a ferramenta, mas a saída não é modificada.
</Step>
<Step title="Retorno do Resultado">
A saída da ferramenta é retornada como resultado da tarefa sem quaisquer modificações.
</Step>
</Steps>

111
docs/pt-BR/learn/hierarchical-process.mdx Normal file
View File

@@ -0,0 +1,111 @@
---
title: Processo Hierárquico
description: Um guia abrangente para compreender e aplicar o processo hierárquico em seus projetos CrewAI, atualizado para refletir as práticas de codificação e funcionalidades mais recentes.
icon: sitemap
---
## Introdução
O processo hierárquico no CrewAI introduz uma abordagem estruturada para a gestão de tarefas, simulando hierarquias organizacionais tradicionais para uma delegação e execução eficiente de tarefas.
Esse fluxo de trabalho sistemático melhora os resultados do projeto ao garantir que as tarefas sejam tratadas com máxima eficiência e precisão.
<Tip>
O processo hierárquico foi projetado para alavancar modelos avançados como o GPT-4, otimizando o uso de tokens enquanto lida com tarefas complexas de forma mais eficiente.
</Tip>
## Visão Geral do Processo Hierárquico
Por padrão, as tarefas no CrewAI são gerenciadas por meio de um processo sequencial. No entanto, adotar uma abordagem hierárquica permite uma hierarquia clara na gestão de tarefas,
onde um agente 'gerente' coordena o fluxo de trabalho, delega tarefas e valida os resultados para uma execução eficaz e simplificada. Esse agente gerente pode agora ser
criado automaticamente pelo CrewAI ou explicitamente definido pelo usuário.
### Principais Características
- **Delegação de Tarefas**: Um agente gerente distribui tarefas entre os membros da crew com base em seus papéis e capacidades.
- **Validação de Resultados**: O gerente avalia os resultados para garantir que atendam aos padrões exigidos.
- **Fluxo de Trabalho Eficiente**: Emula estruturas corporativas, oferecendo uma abordagem organizada para a gestão de tarefas.
- **Manipulação de System Prompt**: Opcionalmente, especifique se o sistema deve usar prompts predefinidos.
- **Controle de Stop Words**: Opcionalmente, especifique se stop words devem ser usadas, oferecendo suporte a diversos modelos, incluindo os modelos o1.
- **Respeito à Context Window**: Priorização de contexto relevante ativando o respeito à context window, que agora é o comportamento padrão.
- **Controle de Delegação**: A delegação agora está desativada por padrão para dar controle explícito ao usuário.
- **Máximo de Requisições por Minuto**: Opção configurável para definir o número máximo de requisições por minuto.
- **Máximo de Iterações**: Limitação do número máximo de iterações até a obtenção de uma resposta final.
## Implementando o Processo Hierárquico
Para utilizar o processo hierárquico, é essencial definir explicitamente o atributo de processo como `Process.hierarchical`, já que o comportamento padrão é `Process.sequential`.
Defina uma crew com um gerente designado e estabeleça uma cadeia de comando clara.
<Tip>
Atribua ferramentas no nível do agente para facilitar a delegação e execução de tarefas pelos agentes designados sob a orientação do gerente.
Ferramentas também podem ser especificadas no nível da tarefa, para um controle preciso sobre a disponibilidade de ferramentas durante a execução das tarefas.
</Tip>
<Tip>
Configurar o parâmetro `manager_llm` é fundamental para o processo hierárquico.
O sistema exige a configuração de um LLM do gerente para funcionar corretamente, garantindo tomadas de decisão personalizadas.
</Tip>
```python Code
from crewai import Crew, Process, Agent
# Agents are defined with attributes for backstory, cache, and verbose mode
researcher = Agent(
role='Researcher',
goal='Conduct in-depth analysis',
backstory='Experienced data analyst with a knack for uncovering hidden trends.',
)
writer = Agent(
role='Writer',
goal='Create engaging content',
backstory='Creative writer passionate about storytelling in technical domains.',
)
# Establishing the crew with a hierarchical process and additional configurations
project_crew = Crew(
tasks=[...], # Tasks to be delegated and executed under the manager's supervision
agents=[researcher, writer],
manager_llm="gpt-4o", # Specify which LLM the manager should use
process=Process.hierarchical,
planning=True,
)
```
### Usando um Agente Gerente Personalizado
Alternativamente, você pode criar um agente gerente personalizado com atributos específicos adaptados às necessidades de gestão do seu projeto. Isso oferece maior controle sobre o comportamento e as capacidades do gerente.
```python
# Define a custom manager agent
manager = Agent(
role="Project Manager",
goal="Efficiently manage the crew and ensure high-quality task completion",
backstory="You're an experienced project manager, skilled in overseeing complex projects and guiding teams to success.",
allow_delegation=True,
)
# Use the custom manager in your crew
project_crew = Crew(
tasks=[...],
agents=[researcher, writer],
manager_agent=manager, # Use your custom manager agent
process=Process.hierarchical,
planning=True,
)
```
<Tip>
Para mais detalhes sobre a criação e personalização de um agente gerente, confira a [documentação do Custom Manager Agent](https://docs.crewai.com/how-to/custom-manager-agent#custom-manager-agent).
</Tip>
### Fluxo de Trabalho na Prática
1. **Atribuição de Tarefas**: O gerente atribui as tarefas estrategicamente, considerando as capacidades de cada agente e as ferramentas disponíveis.
2. **Execução e Revisão**: Os agentes concluem suas tarefas com a opção de execução assíncrona e funções de callback para fluxos de trabalho otimizados.
3. **Progresso Sequencial das Tarefas**: Apesar de ser um processo hierárquico, as tarefas seguem uma ordem lógica para um progresso fluido, facilitado pela supervisão do gerente.
## Conclusão
Adotar o processo hierárquico no CrewAI, com as configurações corretas e o entendimento das capacidades do sistema, facilita uma abordagem organizada e eficiente para o gerenciamento de projetos.
Aproveite os recursos avançados e as personalizações para ajustar o fluxo de trabalho conforme suas necessidades, garantindo a execução ideal das tarefas e o sucesso do projeto.

78
docs/pt-BR/learn/human-in-the-loop.mdx Normal file
View File

@@ -0,0 +1,78 @@
---
title: "Workflows Human-in-the-Loop (HITL)"
description: "Aprenda como implementar workflows Human-in-the-Loop na CrewAI para aprimorar a tomada de decisões"
icon: "user-check"
---
Human-in-the-Loop (HITL) é uma abordagem poderosa que combina a inteligência artificial com a experiência humana para aprimorar a tomada de decisões e melhorar os resultados das tarefas. Este guia mostra como implementar HITL dentro da CrewAI.
## Configurando Workflows HITL
<Steps>
<Step title="Configure sua Tarefa">
Configure sua tarefa com a entrada humana habilitada:
<Frame>
<img src="/images/enterprise/crew-human-input.png" alt="Entrada Humana Crew" />
</Frame>
</Step>
<Step title="Forneça a URL do Webhook">
Ao iniciar seu crew, inclua uma URL de webhook para entrada humana:
<Frame>
<img src="/images/enterprise/crew-webhook-url.png" alt="URL do Webhook Crew" />
</Frame>
</Step>
<Step title="Receba Notificação do Webhook">
Assim que o crew concluir a tarefa que requer entrada humana, você receberá uma notificação de webhook contendo:
- Execution ID
- Task ID
- Task output
</Step>
<Step title="Revise o Resultado da Tarefa">
O sistema irá pausar no estado `Pending Human Input`. Revise cuidadosamente o resultado da tarefa.
</Step>
<Step title="Envie o Feedback Humano">
Chame o endpoint de retomada do seu crew com as seguintes informações:
<Frame>
<img src="/images/enterprise/crew-resume-endpoint.png" alt="Endpoint de Retomada Crew" />
</Frame>
<Warning>
**Impacto do Feedback na Execução da Tarefa**:
É fundamental ter cuidado ao fornecer feedback, pois todo o conteúdo do feedback será incorporado como contexto adicional para execuções futuras da tarefa.
</Warning>
Isso significa:
- Todas as informações do seu feedback passam a fazer parte do contexto da tarefa.
- Detalhes irrelevantes podem influenciar negativamente.
- Feedback conciso e relevante ajuda a manter o foco e a eficiência da tarefa.
- Sempre revise seu feedback cuidadosamente antes de enviar para garantir que contenha apenas informações pertinentes que irão guiar positivamente a execução da tarefa.
</Step>
<Step title="Lidar com Feedback Negativo">
Se você fornecer um feedback negativo:
- O crew irá tentar novamente a tarefa com o contexto adicionado do seu feedback.
- Você receberá outra notificação de webhook para nova revisão.
- Repita os passos 4-6 até ficar satisfeito.
</Step>
<Step title="Continuação da Execução">
Quando você enviar um feedback positivo, a execução prosseguirá para as próximas etapas.
</Step>
</Steps>
## Melhores Práticas
- **Seja Específico**: Forneça feedback claro e acionável que trate diretamente da tarefa em questão
- **Mantenha-se Relevante**: Inclua apenas informações que ajudem a melhorar a execução da tarefa
- **Seja Ágil**: Responda rapidamente às solicitações HITL para evitar atrasos no fluxo
- **Reveja Cuidadosamente**: Verifique seu feedback antes de enviar para garantir a precisão
## Casos de Uso Comuns
Workflows HITL são particularmente valiosos para:
- Garantia de qualidade e validação
- Cenários de tomada de decisão complexa
- Operações sensíveis ou de alto risco
- Tarefas criativas que requerem julgamento humano
- Revisões de conformidade e regulamentação

98
docs/pt-BR/learn/human-input-on-execution.mdx Normal file
View File

@@ -0,0 +1,98 @@
---
title: Input Humano na Execução
description: Integrando o CrewAI com input humano durante a execução em processos complexos de tomada de decisão e aproveitando ao máximo todos os atributos e ferramentas do agente.
icon: user-check
---
## Input humano na execução dos agentes
O input humano é fundamental em vários cenários de execução de agentes, permitindo que os agentes solicitem informações adicionais ou esclarecimentos quando necessário.
Esse recurso é especialmente útil em processos complexos de tomada de decisão ou quando os agentes precisam de mais detalhes para concluir uma tarefa de forma eficaz.
## Usando input humano com CrewAI
Para integrar input humano durante a execução do agente, defina o parâmetro `human_input` na definição da tarefa. Quando ativado, o agente solicitará informações ao usuário antes de fornecer sua resposta final.
Esse input pode oferecer contexto extra, esclarecer ambiguidades ou validar a saída produzida pelo agente.
### Exemplo:
```shell
pip install crewai
```
```python Code
import os
from crewai import Agent, Task, Crew
from crewai_tools import SerperDevTool
os.environ["SERPER_API_KEY"] = "Your Key" # serper.dev API key
os.environ["OPENAI_API_KEY"] = "Your Key"
# Loading Tools
search_tool = SerperDevTool()
# Define your agents with roles, goals, tools, and additional attributes
researcher = Agent(
role='Senior Research Analyst',
goal='Uncover cutting-edge developments in AI and data science',
backstory=(
"You are a Senior Research Analyst at a leading tech think tank. "
"Your expertise lies in identifying emerging trends and technologies in AI and data science. "
"You have a knack for dissecting complex data and presenting actionable insights."
),
verbose=True,
allow_delegation=False,
tools=[search_tool]
)
writer = Agent(
role='Tech Content Strategist',
goal='Craft compelling content on tech advancements',
backstory=(
"You are a renowned Tech Content Strategist, known for your insightful and engaging articles on technology and innovation. "
"With a deep understanding of the tech industry, you transform complex concepts into compelling narratives."
),
verbose=True,
allow_delegation=True,
tools=[search_tool],
cache=False, # Disable cache for this agent
)
# Create tasks for your agents
task1 = Task(
description=(
"Conduct a comprehensive analysis of the latest advancements in AI in 2025. "
"Identify key trends, breakthrough technologies, and potential industry impacts. "
"Compile your findings in a detailed report. "
"Make sure to check with a human if the draft is good before finalizing your answer."
),
expected_output='A comprehensive full report on the latest AI advancements in 2025, leave nothing out',
agent=researcher,
human_input=True
)
task2 = Task(
description=(
"Using the insights from the researcher\'s report, develop an engaging blog post that highlights the most significant AI advancements. "
"Your post should be informative yet accessible, catering to a tech-savvy audience. "
"Aim for a narrative that captures the essence of these breakthroughs and their implications for the future."
),
expected_output='A compelling 3 paragraphs blog post formatted as markdown about the latest AI advancements in 2025',
agent=writer,
human_input=True
)
# Instantiate your crew with a sequential process
crew = Crew(
agents=[researcher, writer],
tasks=[task1, task2],
verbose=True,
memory=True,
planning=True # Enable planning feature for the crew
)
# Get your crew to work!
result = crew.kickoff()
print("######################")
print(result)
```

123
docs/pt-BR/learn/kickoff-async.mdx Normal file
View File

@@ -0,0 +1,123 @@
---
title: Inicie uma Crew de Forma Assíncrona
description: Inicie uma Crew de Forma Assíncrona
icon: rocket-launch
---
## Introdução
A CrewAI oferece a capacidade de iniciar uma crew de forma assíncrona, permitindo que você comece a execução da crew de maneira não bloqueante.
Esse recurso é especialmente útil quando você deseja executar múltiplas crews simultaneamente ou quando precisa realizar outras tarefas enquanto a crew está em execução.
## Execução Assíncrona de Crew
Para iniciar uma crew de forma assíncrona, utilize o método `kickoff_async()`. Este método inicia a execução da crew em uma thread separada, permitindo que a thread principal continue executando outras tarefas.
### Assinatura do Método
```python Code
def kickoff_async(self, inputs: dict) -> CrewOutput:
```
### Parâmetros
- `inputs` (dict): Um dicionário contendo os dados de entrada necessários para as tarefas.
### Retorno
- `CrewOutput`: Um objeto que representa o resultado da execução da crew.
## Possíveis Casos de Uso
- **Geração Paralela de Conteúdo**: Inicie múltiplas crews independentes de forma assíncrona, cada uma responsável por gerar conteúdo sobre temas diferentes. Por exemplo, uma crew pode pesquisar e redigir um artigo sobre tendências em IA, enquanto outra gera posts para redes sociais sobre o lançamento de um novo produto. Cada crew atua de forma independente, permitindo a escala eficiente da produção de conteúdo.
- **Tarefas Conjuntas de Pesquisa de Mercado**: Lance múltiplas crews de forma assíncrona para realizar pesquisas de mercado em paralelo. Uma crew pode analisar tendências do setor, outra examinar estratégias de concorrentes e ainda outra avaliar o sentimento do consumidor. Cada crew conclui sua tarefa de forma independente, proporcionando insights mais rápidos e abrangentes.
- **Módulos Independentes de Planejamento de Viagem**: Execute crews separadas para planejar diferentes aspectos de uma viagem de forma independente. Uma crew pode cuidar das opções de voo, outra das acomodações e uma terceira do planejamento das atividades. Cada crew trabalha de maneira assíncrona, permitindo que os vários componentes da viagem sejam planejados ao mesmo tempo e de maneira independente, para resultados mais rápidos.
## Exemplo: Execução Assíncrona de uma Única Crew
Veja um exemplo de como iniciar uma crew de forma assíncrona utilizando asyncio e aguardando o resultado:
```python Code
import asyncio
from crewai import Crew, Agent, Task
# Create an agent with code execution enabled
coding_agent = Agent(
role="Python Data Analyst",
goal="Analyze data and provide insights using Python",
backstory="You are an experienced data analyst with strong Python skills.",
allow_code_execution=True
)
# Create a task that requires code execution
data_analysis_task = Task(
description="Analyze the given dataset and calculate the average age of participants. Ages: {ages}",
agent=coding_agent,
expected_output="The average age of the participants."
)
# Create a crew and add the task
analysis_crew = Crew(
agents=[coding_agent],
tasks=[data_analysis_task]
)
# Async function to kickoff the crew asynchronously
async def async_crew_execution():
result = await analysis_crew.kickoff_async(inputs={"ages": [25, 30, 35, 40, 45]})
print("Crew Result:", result)
# Run the async function
asyncio.run(async_crew_execution())
```
## Exemplo: Execução Assíncrona de Múltiplas Crews
Neste exemplo, mostraremos como iniciar múltiplas crews de forma assíncrona e aguardar todas serem concluídas usando `asyncio.gather()`:
```python Code
import asyncio
from crewai import Crew, Agent, Task
# Create an agent with code execution enabled
coding_agent = Agent(
role="Python Data Analyst",
goal="Analyze data and provide insights using Python",
backstory="You are an experienced data analyst with strong Python skills.",
allow_code_execution=True
)
# Create tasks that require code execution
task_1 = Task(
description="Analyze the first dataset and calculate the average age of participants. Ages: {ages}",
agent=coding_agent,
expected_output="The average age of the participants."
)
task_2 = Task(
description="Analyze the second dataset and calculate the average age of participants. Ages: {ages}",
agent=coding_agent,
expected_output="The average age of the participants."
)
# Create two crews and add tasks
crew_1 = Crew(agents=[coding_agent], tasks=[task_1])
crew_2 = Crew(agents=[coding_agent], tasks=[task_2])
# Async function to kickoff multiple crews asynchronously and wait for all to finish
async def async_multiple_crews():
# Create coroutines for concurrent execution
result_1 = crew_1.kickoff_async(inputs={"ages": [25, 30, 35, 40, 45]})
result_2 = crew_2.kickoff_async(inputs={"ages": [20, 22, 24, 28, 30]})
# Wait for both crews to finish
results = await asyncio.gather(result_1, result_2)
for i, result in enumerate(results, 1):
print(f"Crew {i} Result:", result)
# Run the async function
asyncio.run(async_multiple_crews())
```

53
docs/pt-BR/learn/kickoff-for-each.mdx Normal file
View File

@@ -0,0 +1,53 @@
---
title: Kickoff Crew para Cada
description: Kickoff Crew para Cada Item em uma Lista
icon: at
---
## Introdução
A CrewAI oferece a capacidade de iniciar um crew para cada item em uma lista, permitindo que você execute o crew para cada item da lista.
Esse recurso é particularmente útil quando é necessário realizar o mesmo conjunto de tarefas para vários itens.
## Iniciando um Crew para Cada Item
Para iniciar um crew para cada item em uma lista, utilize o método `kickoff_for_each()`.
Esse método executa o crew para cada item da lista, permitindo o processamento eficiente de múltiplos itens.
Veja um exemplo de como iniciar um crew para cada item em uma lista:
```python Code
from crewai import Crew, Agent, Task
# Create an agent with code execution enabled
coding_agent = Agent(
role="Python Data Analyst",
goal="Analyze data and provide insights using Python",
backstory="You are an experienced data analyst with strong Python skills.",
allow_code_execution=True
)
# Create a task that requires code execution
data_analysis_task = Task(
description="Analyze the given dataset and calculate the average age of participants. Ages: {ages}",
agent=coding_agent,
expected_output="The average age calculated from the dataset"
)
# Create a crew and add the task
analysis_crew = Crew(
agents=[coding_agent],
tasks=[data_analysis_task],
verbose=True,
memory=False
)
datasets = [
{ "ages": [25, 30, 35, 40, 45] },
{ "ages": [20, 25, 30, 35, 40] },
{ "ages": [30, 35, 40, 45, 50] }
]
# Execute the crew
result = analysis_crew.kickoff_for_each(inputs=datasets)
```

204
docs/pt-BR/learn/llm-connections.mdx Normal file
View File

@@ -0,0 +1,204 @@
---
title: Conecte-se a qualquer LLM
description: Guia abrangente sobre como integrar o CrewAI a diversos Large Language Models (LLMs) usando o LiteLLM, incluindo provedores compatíveis e opções de configuração.
icon: brain-circuit
---
## Conecte o CrewAI a LLMs
O CrewAI utiliza o LiteLLM para conectar-se a uma grande variedade de Modelos de Linguagem (LLMs). Essa integração proporciona grande versatilidade, permitindo que você utilize modelos de inúmeros provedores por meio de uma interface simples e unificada.
<Note>
Por padrão, o CrewAI usa o modelo `gpt-4o-mini`. Isso é determinado pela variável de ambiente `OPENAI_MODEL_NAME`, que tem como padrão "gpt-4o-mini" se não for definida.
Você pode facilmente configurar seus agentes para usar um modelo ou provedor diferente, conforme descrito neste guia.
</Note>
## Provedores Compatíveis
O LiteLLM oferece suporte a uma ampla gama de provedores, incluindo, mas não se limitando a:
- OpenAI
- Anthropic
- Google (Vertex AI, Gemini)
- Azure OpenAI
- AWS (Bedrock, SageMaker)
- Cohere
- VoyageAI
- Hugging Face
- Ollama
- Mistral AI
- Replicate
- Together AI
- AI21
- Cloudflare Workers AI
- DeepInfra
- Groq
- SambaNova
- [NVIDIA NIMs](https://docs.api.nvidia.com/nim/reference/models-1)
- E muitos outros!
Para uma lista completa e sempre atualizada dos provedores suportados, consulte a [documentação de Provedores do LiteLLM](https://docs.litellm.ai/docs/providers).
## Alterando a LLM
Para utilizar uma LLM diferente com seus agentes CrewAI, você tem várias opções:
<Tabs>
<Tab title="Usando um Identificador de String">
Passe o nome do modelo como uma string ao inicializar o agente:
<CodeGroup>
```python Code
from crewai import Agent
# Usando o GPT-4 da OpenAI
openai_agent = Agent(
role='OpenAI Expert',
goal='Provide insights using GPT-4',
backstory="An AI assistant powered by OpenAI's latest model.",
llm='gpt-4'
)
# Usando o Claude da Anthropic
claude_agent = Agent(
role='Anthropic Expert',
goal='Analyze data using Claude',
backstory="An AI assistant leveraging Anthropic's language model.",
llm='claude-2'
)
```
</CodeGroup>
</Tab>
<Tab title="Usando a Classe LLM">
Para uma configuração mais detalhada, utilize a classe LLM:
<CodeGroup>
```python Code
from crewai import Agent, LLM
llm = LLM(
model="gpt-4",
temperature=0.7,
base_url="https://api.openai.com/v1",
api_key="your-api-key-here"
)
agent = Agent(
role='Customized LLM Expert',
goal='Provide tailored responses',
backstory="An AI assistant with custom LLM settings.",
llm=llm
)
```
</CodeGroup>
</Tab>
</Tabs>
## Opções de Configuração
Ao configurar uma LLM para o seu agente, você tem acesso a uma variedade de parâmetros:
| Parâmetro | Tipo | Descrição |
|:----------|:-----:|:-------------|
| **model** | `str` | O nome do modelo a ser utilizado (ex.: "gpt-4", "claude-2") |
| **temperature** | `float` | Controla o grau de aleatoriedade nas respostas (0.0 a 1.0) |
| **max_tokens** | `int` | Número máximo de tokens a serem gerados |
| **top_p** | `float` | Controla a diversidade das respostas (0.0 a 1.0) |
| **frequency_penalty** | `float` | Penaliza novos tokens com base na frequência em que já apareceram no texto |
| **presence_penalty** | `float` | Penaliza novos tokens com base na presença deles no texto até o momento |
| **stop** | `str`, `List[str]` | Sequência(s) que interrompem a geração do texto |
| **base_url** | `str` | URL base do endpoint da API |
| **api_key** | `str` | Sua chave de API para autenticação |
Para uma lista completa de parâmetros e suas respectivas descrições, consulte a documentação da classe LLM.
## Conectando-se a LLMs Compatíveis com OpenAI
Você pode se conectar a LLMs compatíveis com a OpenAI usando variáveis de ambiente ou definindo atributos específicos na classe LLM:
<Tabs>
<Tab title="Usando Variáveis de Ambiente">
<CodeGroup>
```python Generic
import os
os.environ["OPENAI_API_KEY"] = "your-api-key"
os.environ["OPENAI_API_BASE"] = "https://api.your-provider.com/v1"
os.environ["OPENAI_MODEL_NAME"] = "your-model-name"
```
```python Google
import os
# Exemplo usando a API compatível com OpenAI do Gemini.
os.environ["OPENAI_API_KEY"] = "your-gemini-key" # Deve começar com AIza...
os.environ["OPENAI_API_BASE"] = "https://generativelanguage.googleapis.com/v1beta/openai/"
os.environ["OPENAI_MODEL_NAME"] = "openai/gemini-2.0-flash" # Adicione aqui seu modelo do Gemini, sob openai/
```
</CodeGroup>
</Tab>
<Tab title="Usando Atributos da Classe LLM">
<CodeGroup>
```python Generic
llm = LLM(
model="custom-model-name",
api_key="your-api-key",
base_url="https://api.your-provider.com/v1"
)
agent = Agent(llm=llm, ...)
```
```python Google
# Exemplo usando a API compatível com OpenAI do Gemini
llm = LLM(
model="openai/gemini-2.0-flash",
base_url="https://generativelanguage.googleapis.com/v1beta/openai/",
api_key="your-gemini-key", # Deve começar com AIza...
)
agent = Agent(llm=llm, ...)
```
</CodeGroup>
</Tab>
</Tabs>
## Utilizando Modelos Locais com Ollama
Para modelos locais como os oferecidos pelo Ollama:
<Steps>
<Step title="Baixe e instale o Ollama">
[Clique aqui para baixar e instalar o Ollama](https://ollama.com/download)
</Step>
<Step title="Puxe o modelo desejado">
Por exemplo, execute `ollama pull llama3.2` para baixar o modelo.
</Step>
<Step title="Configure seu agente">
<CodeGroup>
```python Code
agent = Agent(
role='Local AI Expert',
goal='Process information using a local model',
backstory="An AI assistant running on local hardware.",
llm=LLM(model="ollama/llama3.2", base_url="http://localhost:11434")
)
```
</CodeGroup>
</Step>
</Steps>
## Alterando a URL Base da API
Você pode alterar a URL base da API para qualquer provedor de LLM definindo o parâmetro `base_url`:
```python Code
llm = LLM(
model="custom-model-name",
base_url="https://api.your-provider.com/v1",
api_key="your-api-key"
)
agent = Agent(llm=llm, ...)
```
Isso é particularmente útil ao trabalhar com APIs compatíveis com a OpenAI ou quando você precisa especificar um endpoint diferente para o provedor escolhido.
## Conclusão
Ao utilizar o LiteLLM, o CrewAI oferece integração transparente com uma vasta gama de LLMs. Essa flexibilidade permite que você escolha o modelo mais adequado para sua necessidade específica, seja priorizando desempenho, custo-benefício ou implantação local. Lembre-se de consultar a [documentação do LiteLLM](https://docs.litellm.ai/docs/) para obter as informações mais atualizadas sobre modelos suportados e opções de configuração.

727
docs/pt-BR/learn/llm-selection-guide.mdx Normal file
View File

@@ -0,0 +1,727 @@
---
title: 'Guia Estratégico de Seleção de LLMs'
description: 'Framework estratégico para escolher o LLM certo para seus agentes CrewAI e escrever definições eficazes de tarefas e agentes'
icon: 'brain-circuit'
---
## A Abordagem CrewAI para Seleção de LLMs
Em vez de recomendações prescritivas de modelos, defendemos um **framework de pensamento** que ajude você a tomar decisões informadas com base no seu caso de uso, restrições e requisitos específicos. O cenário de LLMs evolui rapidamente, com novos modelos surgindo regularmente e os existentes sendo atualizados frequentemente. O que mais importa é desenvolver uma abordagem sistemática de avaliação que permaneça relevante independentemente dos modelos disponíveis no momento.
<Note>
Este guia foca em pensamento estratégico em vez de recomendações de modelos específicos, já que o cenário dos LLMs evolui rapidamente.
</Note>
## Framework de Decisão Rápida
<Steps>
<Step title="Analise Suas Tarefas">
Comece entendendo profundamente o que suas tarefas realmente exigem. Considere a complexidade cognitiva envolvida, a profundidade de raciocínio necessária, o formato dos resultados esperados e a quantidade de contexto que o modelo precisará processar. Essa análise fundamental guiará todas as decisões seguintes.
</Step>
<Step title="Mapeie as Capacidades dos Modelos">
Assim que você compreende seus requisitos, mapeie-os para as forças dos modelos. Diferentes famílias de modelos se destacam em diferentes tipos de trabalho; alguns são otimizados para raciocínio e análise, outros para criatividade e geração de conteúdo, e outros para velocidade e eficiência.
</Step>
<Step title="Considere Restrições">
Leve em conta suas reais restrições operacionais, incluindo limitações orçamentárias, requisitos de latência, necessidades de privacidade de dados e capacidades de infraestrutura. O melhor modelo teoricamente pode não ser a melhor escolha prática para sua situação.
</Step>
<Step title="Teste e Itere">
Comece com modelos confiáveis e bem conhecidos e otimize com base no desempenho real no seu caso de uso. Os resultados práticos frequentemente diferem dos benchmarks teóricos, então testes empíricos são cruciais.
</Step>
</Steps>
## Framework Central de Seleção
### a. Pensamento Orientado à Tarefa
O passo mais crítico na seleção de LLMs é entender o que sua tarefa realmente exige. Frequentemente, equipes escolhem modelos com base em reputação geral ou pontuações de benchmark, sem analisar cuidadosamente suas necessidades específicas. Essa abordagem leva tanto ao superdimensionamento de tarefas simples usando modelos caros e complexos quanto à subutilização em tarefas sofisticadas com modelos sem as capacidades necessárias.
<Tabs>
<Tab title="Complexidade de Raciocínio">
- **Tarefas Simples** representam a maioria do trabalho diário de IA e incluem seguir instruções básicas, processar dados simples e formatação elementar. Estas tarefas geralmente têm entradas e saídas claras, com mínima ambiguidade. A carga cognitiva é baixa e o modelo precisa apenas seguir instruções explícitas, não realizar raciocínio complexo.
- **Tarefas Complexas** exigem raciocínio de múltiplas etapas, pensamento estratégico e a capacidade de lidar com informações ambíguas ou incompletas. Podem envolver análise de múltiplas fontes de dados, desenvolvimento de estratégias abrangentes ou resolução de problemas que precisam ser decompostos em componentes menores. O modelo deve manter o contexto ao longo de várias etapas de raciocínio e frequentemente precisa inferir informações não explicitamente declaradas.
- **Tarefas Criativas** exigem um tipo diferente de capacidade cognitiva, focada em gerar conteúdo novo, envolvente e adequado ao contexto. Isso inclui storytelling, criação de textos de marketing e solução criativa de problemas. O modelo deve compreender nuances, tom e público, produzindo conteúdo autêntico e envolvente, não apenas fórmulas.
</Tab>
<Tab title="Requisitos de Saída">
- **Dados Estruturados** exigem precisão e consistência na adesão ao formato. Ao trabalhar com JSON, XML ou formatos de banco de dados, o modelo deve produzir saídas sintaticamente corretas, que possam ser processadas programaticamente. Essas tarefas possuem requisitos rígidos de validação e pouca tolerância a erros de formato, tornando a confiabilidade mais importante que a criatividade.
- **Conteúdo Criativo** requer equilíbrio entre competência técnica e criatividade. O modelo precisa compreender o público, tom e voz da marca, ao mesmo tempo em que produz conteúdo que engaja leitores e atinge objetivos comunicativos específicos. A qualidade aqui é mais subjetiva e exige modelos capazes de adaptar o estilo de escrita a diferentes contextos e propósitos.
- **Conteúdo Técnico** situa-se entre dados estruturados e conteúdo criativo, demandando precisão e clareza. Documentação, geração de código e análises técnicas precisam ser exatas e completas, mas ainda assim acessíveis ao público-alvo. O modelo deve entender conceitos técnicos complexos e comunicá-los de forma eficaz.
</Tab>
<Tab title="Necessidades de Contexto">
- **Contexto Curto** envolve tarefas imediatas e focalizadas, onde o modelo processa informações limitadas rapidamente. São interações transacionais em que velocidade e eficiência importam mais do que compreensão profunda. O modelo não precisa manter histórico extenso ou processar grandes documentos.
- **Contexto Longo** é necessário ao lidar com documentos substanciais, conversas extensas ou tarefas complexas de múltiplas partes. O modelo precisa manter coerência ao longo de milhares de tokens, referenciando informações anteriores com precisão. Essencial para análise de documentos, pesquisa abrangente e sistemas de diálogo sofisticados.
- **Contexto Muito Longo** ultrapassa os limites do possível hoje, com processamento de documentos massivos, síntese de pesquisas extensas ou interações multi-sessão. São casos que exigem modelos projetados especificamente para lidar com contexto estendido e envolvem trade-offs entre extensão e velocidade.
</Tab>
</Tabs>
### b. Mapeamento de Capacidades do Modelo
Entender as capacidades dos modelos exige ir além do marketing e dos benchmarks, analisando forças e limitações fundamentais das arquiteturas e métodos de treinamento.
<AccordionGroup>
<Accordion title="Modelos de Raciocínio" icon="brain">
Modelos de raciocínio formam uma categoria especializada, projetada para tarefas de pensamento complexo e de múltiplas etapas. Eles se destacam na resolução de problemas que requerem análise cuidadosa, planejamento estratégico ou decomposição sistemática. Normalmente aplicam técnicas como chain-of-thought ou tree-of-thought para conduzir o raciocínio passo a passo.
O ponto forte é manter consistência lógica em cadeias longas de raciocínio e decompor problemas complexos em partes gerenciáveis. São especialmente valiosos para planejamento estratégico, análise complexa e situações onde a qualidade do raciocínio importa mais que a velocidade.
Entretanto, há trade-offs em termos de custo e velocidade. Podem ser menos adequados para tarefas criativas ou operações simples, onde suas capacidades avançadas não são necessárias. Considere-os quando as tarefas realmente se beneficiarem dessa análise detalhada.
</Accordion>
<Accordion title="Modelos de Uso Geral" icon="microchip">
Modelos de uso geral oferecem uma abordagem equilibrada, com desempenho sólido em uma ampla gama de tarefas, sem especialização extrema. São treinados em conjuntos de dados diversificados e otimizados para versatilidade.
A principal vantagem é a confiabilidade previsível em diversos trabalhos: pesquisa, análise, criação de conteúdo, processamento de dados. São ótimas opções iniciais para equipes que buscam consistência ao lidar com fluxos variados.
Embora não atinjam picos de desempenho como modelos especializados, oferecem simplicidade operacional e baixa complexidade na gestão. São o melhor ponto de partida para novos projetos, permitindo descobertas de necessidades antes de avançar para otimizações.
</Accordion>
<Accordion title="Modelos Rápidos & Eficientes" icon="bolt">
Modelos rápidos e eficientes priorizam velocidade, custo e eficiência de recursos, em vez de raciocínio sofisticado. São otimizados para cenários de alto volume onde respostas rápidas e baixos custos são mais importantes que compreensão ou criatividade profunda.
Brilham em operações rotineiras, processamento simples de dados, chamadas de funções e tarefas de alto volume. Aplicações que processam muitos pedidos rapidamente ou operam sob restrições orçamentárias se beneficiam desses modelos.
O ponto crucial é garantir que suas capacidades atendam às exigências da tarefa. Podem não atender tarefas que exijam entendimento profundo, raciocínio complexo ou geração de conteúdo sofisticado. São ideais para tarefas rotineiras bem definidas.
</Accordion>
<Accordion title="Modelos Criativos" icon="pen">
Modelos criativos são otimizados para geração de conteúdo, qualidade de escrita e pensamento inovador. Excelentes na compreensão de nuances, tom e estilo, produzindo conteúdo envolvente e natural.
O ponto forte está em adaptar o estilo para diferentes públicos, manter voz e tom consistentes e engajar leitores. Performam melhor em storytelling, textos publicitários, comunicações de marca e outras tarefas com criatividade como foco.
Ao selecionar esses modelos, considere não apenas a habilidade de gerar texto, mas a compreensão de público, contexto e objetivo. Os melhores modelos criativos adaptam a saída à voz da marca, diferentes segmentos e mantêm consistência em peças longas.
</Accordion>
<Accordion title="Modelos Open Source" icon="code">
Modelos open source oferecem vantagens em controle de custos, potencial de customização, privacidade de dados e flexibilidade de deployment. Podem ser rodados localmente ou em infraestrutura própria, dando controle total sobre dados e comportamento.
Os principais benefícios incluem eliminação de custos por token, possibilidade de fine-tuning, privacidade total e independência de fornecedores externos. Perfeitos para organizações com necessidade de privacidade, orçamento limitado ou desejo de customização.
Contudo, requerem maior expertise técnica para implantar e manter. Considere custos de infraestrutura, complexidade de gestão e esforços contínuos de atualização e otimização ao avaliar modelos open source. O custo total pode ser maior que o de alternativas em nuvem devido a esse overhead.
</Accordion>
</AccordionGroup>
## Padrões Estratégicos de Configuração
### a. Abordagem Multi-Modelo
<Tip>
Use diferentes modelos para diferentes propósitos dentro da mesma crew para otimizar desempenho e custos.
</Tip>
As implementações CrewAI mais sofisticadas empregam múltiplos modelos estrategicamente, designando-os conforme as funções e necessidades dos agentes. Assim, é possível otimizar desempenho e custos usando o modelo mais adequado para cada tipo de tarefa.
Agentes de planejamento se beneficiam de modelos de raciocínio para pensamento estratégico e análise multi-etapas. Esses agentes funcionam como o "cérebro" da operação. Agentes de conteúdo têm melhor desempenho com modelos criativos focados em qualidade de escrita e engajamento. Agentes de processamento, responsáveis por operações rotineiras, podem usar modelos eficientes priorizando velocidade.
**Exemplo: Crew de Pesquisa e Análise**
```python
from crewai import Agent, Task, Crew, LLM
# Modelo de raciocínio para planejamento estratégico
manager_llm = LLM(model="gemini-2.5-flash-preview-05-20", temperature=0.1)
# Modelo criativo para gerar conteúdo
content_llm = LLM(model="claude-3-5-sonnet-20241022", temperature=0.7)
# Modelo eficiente para processamento de dados
processing_llm = LLM(model="gpt-4o-mini", temperature=0)
research_manager = Agent(
role="Research Strategy Manager",
goal="Develop comprehensive research strategies and coordinate team efforts",
backstory="Expert research strategist with deep analytical capabilities",
llm=manager_llm, # Modelo de alto nível para raciocínio complexo
verbose=True
)
content_writer = Agent(
role="Research Content Writer",
goal="Transform research findings into compelling, well-structured reports",
backstory="Skilled writer who excels at making complex topics accessible",
llm=content_llm, # Modelo criativo para conteúdo envolvente
verbose=True
)
data_processor = Agent(
role="Data Analysis Specialist",
goal="Extract and organize key data points from research sources",
backstory="Detail-oriented analyst focused on accuracy and efficiency",
llm=processing_llm, # Modelo rápido para tarefas rotineiras
verbose=True
)
crew = Crew(
agents=[research_manager, content_writer, data_processor],
tasks=[...], # Suas tarefas específicas
manager_llm=manager_llm, # Manager usa o modelo de raciocínio
verbose=True
)
```
O segredo do sucesso na implementação multi-modelo está em entender como os agentes interagem e garantir que as capacidades dos modelos estejam alinhadas às responsabilidades. Isso exige planejamento estratégico, mas traz ganhos significativos em qualidade dos resultados e eficiência operacional.
### b. Seleção Específica por Componente
<Tabs>
<Tab title="Manager LLM">
O manager LLM desempenha papel central em fluxos hierárquicos CrewAI, coordenando agentes e tarefas. Este modelo precisa se destacar em delegação, priorização de tarefas e manutenção de contexto em várias operações simultâneas.
LLMs de manager eficazes exigem forte raciocínio para delegar bem, desempenho consistente para coordenar previsivelmente e excelente gestão de contexto para acompanhar o estado dos agentes. O modelo deve entender capacidades e limitações dos agentes enquanto otimiza a alocação de tarefas.
O custo é especialmente relevante, já que este LLM participa de todas as operações. O modelo precisa entregar capacidades suficientes, sem o preço premium de opções sofisticadas demais, buscando sempre o equilíbrio entre performance e valor.
</Tab>
<Tab title="Function Calling LLM">
LLMs de function calling gerenciam o uso de ferramentas por todos os agentes, sendo críticos em crews que dependem fortemente de APIs externas e ferramentas. Devem ser precisos na extração de parâmetros e no processamento das respostas.
As características mais importantes são precisão e confiabilidade, não criatividade ou raciocínio avançado. O modelo deve extrair parâmetros corretos de comandos em linguagem natural consistentemente e processar respostas de ferramentas adequadamente. Velocidade também importa, pois o uso de ferramentas pode envolver múltiplas idas e vindas de informação.
Muitas equipes descobrem que modelos especializados em function calling ou de uso geral com forte suporte a ferramentas funcionam melhor do que modelos criativos ou de raciocínio nesse papel. O fundamental é assegurar que o modelo consiga converter instruções em chamadas estruturadas sem falhas.
</Tab>
<Tab title="Sobrescritas Específicas de Agente">
Agentes individuais podem sobrescrever o LLM do nível da crew quando suas necessidades diferem significativamente das do restante. Isso permite otimização pontual, mantendo a simplicidade operacional para os demais agentes.
Considere sobrescritas quando a função do agente exige capacidades distintas. Por exemplo, um agente de redação criativa pode se beneficiar de um LLM otimizado para geração de conteúdo, enquanto um analista de dados pode preferir um modelo voltado ao raciocínio.
O desafio é balancear otimização com complexidade operacional. Cada modelo adicional aumenta a complexidade de deployment, monitoramento e custos. Foque em sobrescritas apenas quando a melhoria justificar essa complexidade.
</Tab>
</Tabs>
## Framework de Definição de Tarefas
### a. Foque em Clareza, Não em Complexidade
Definir bem as tarefas é frequentemente mais importante do que a seleção do modelo no resultado gerado pelos agentes CrewAI. Tarefas bem formuladas orientam claramente mesmo modelos simples a terem bom desempenho. Já tarefas mal definidas prejudicam até os modelos mais avançados.
<AccordionGroup>
<Accordion title="Descrições de Tarefas Eficazes" icon="list-check">
As melhores descrições de tarefas equilibram detalhamento e clareza. Devem definir o objetivo de forma clara e sem ambiguidade, além de explicar o método a ser usado com detalhes que permitam ao agente agir corretamente.
Descrições eficazes incluem contexto relevante e restrições, ajudando o agente a entender o propósito maior e quaisquer limitações. Divida trabalhos complexos em etapas gerenciáveis em vez de objetivos genéricos e sobrecarregados.
Erros comuns incluem objetivos vagos, falta de contexto, critérios de sucesso mal definidos ou mistura de tarefas totalmente distintas em um mesmo texto. O objetivo é passar informação suficiente para o sucesso, mas mantendo foco no resultado claro.
</Accordion>
<Accordion title="Diretrizes para a Saída Esperada" icon="bullseye">
As diretrizes da saída esperada funcionam como contrato entre definição de tarefa e agente, especificando claramente o que deve ser entregue e como será avaliado. Elas abrangem formato, estrutura e elementos essenciais.
As melhores diretrizes incluem exemplos concretos de indicadores de qualidade e critérios claros de conclusão, de modo que agente e revisores humanos possam avaliar o resultado facilmente. Isso reduz ambiguidades e garante resultados consistentes.
Evite descrições genéricas que serviriam para qualquer tarefa, ausência de especificações de formato, padrões vagos ou falta de exemplos/modelos que ajudem o agente a entender as expectativas.
</Accordion>
</AccordionGroup>
### b. Estratégia de Sequenciamento de Tarefas
<Tabs>
<Tab title="Dependências Sequenciais">
Dependências são essenciais quando as tarefas se baseiam em resultados prévios, informações fluem de uma tarefa para outra, ou a qualidade depende da conclusão de fases anteriores. Assim, cada tarefa recebe o contexto correto para o sucesso.
Para implementar bem, use o parâmetro de contexto para encadear tarefas, desenvolvendo gradualmente a complexidade. Cada tarefa deve gerar saídas que alimentam as próximas. O objetivo é manter um fluxo lógico entre as tarefas dependentes, evitando gargalos desnecessários.
Funciona melhor quando há progressão lógica evidente e quando a saída de uma tarefa realmente agrega valor nas etapas seguintes. Cuidado com os gargalos; foque nas dependências essenciais.
</Tab>
<Tab title="Execução Paralela">
A execução paralela é valiosa quando as tarefas são independentes, o tempo é crítico ou há expertise distintas que não exigem coordenação. Pode reduzir drasticamente o tempo total, permitindo que agentes especializados atuem simultaneamente.
Para isso, identifique tarefas realmente independentes, agrupe fluxos de trabalho distintos e planeje a integração dos resultados posteriormente. O ponto-chave é garantir que tarefas paralelas não gerem conflitos ou redundâncias.
Considere o paralelo em múltiplos fluxos independentes, diferentes tipos de análise autônoma, ou criação de conteúdo que pode ser feita ao mesmo tempo. Mas atente-se à alocação de recursos, evitando sobrecarga de modelos ou estouro no orçamento.
</Tab>
</Tabs>
## Otimizando a Configuração dos Agentes para Desempenho de LLMs
### a. Seleção de LLM Guiada pelo Papel
<Warning>
Funções genéricas de agentes tornam impossível escolher o LLM certo. Funções específicas permitem otimização do modelo conforme a função.
</Warning>
A especificidade das funções dos agentes determina quais capacidades de LLM mais importam para alto desempenho, criando oportunidade estratégica de alinhar forças do modelo ao papel do agente.
**Impacto de Funções Genéricas vs. Específicas:**
Ao definir funções, pense no conhecimento do domínio, estilo de trabalho e frameworks decisórios mais valiosos para o tipo de tarefa do agente. Quanto mais específica e contextualizada a função, melhor o modelo incorporará esse papel.
```python
# ✅ Função específica - requisitos claros de LLM
specific_agent = Agent(
role="SaaS Revenue Operations Analyst", # Expertise de domínio clara
goal="Analyze recurring revenue metrics and identify growth opportunities",
backstory="Specialist in SaaS business models with deep understanding of ARR, churn, and expansion revenue",
llm=LLM(model="gpt-4o") # Raciocínio justificado para análise complexa
)
```
**Estratégia de Mapeamento de Função para Modelo:**
- **"Research Analyst"** → Modelo de raciocínio (GPT-4o, Claude Sonnet) para análise complexa
- **"Content Editor"** → Modelo criativo (Claude, GPT-4o) para qualidade de escrita
- **"Data Processor"** → Modelo eficiente (GPT-4o-mini, Gemini Flash) para tarefas estruturadas
- **"API Coordinator"** → Modelo otimizado para function calling (GPT-4o, Claude) para uso de ferramentas
### b. Backstory como Amplificador de Contexto do Modelo
<Info>
Backstories estratégicos maximizam a eficácia do LLM ao contextualizar as respostas de forma que prompts genéricos não conseguem.
</Info>
Um bom backstory transforma a escolha do LLM de genérica a especializada. Isso é crucial para otimizar custos: um modelo eficiente com contexto certo pode superar um premium sem contexto.
**Exemplo de Performance Guiada por Contexto:**
```python
# Contexto amplifica a efetividade do modelo
domain_expert = Agent(
role="B2B SaaS Marketing Strategist",
goal="Develop comprehensive go-to-market strategies for enterprise software",
backstory="""
You have 10+ years of experience scaling B2B SaaS companies from Series A to IPO.
You understand the nuances of enterprise sales cycles, the importance of product-market
fit in different verticals, and how to balance growth metrics with unit economics.
You've worked with companies like Salesforce, HubSpot, and emerging unicorns, giving
you perspective on both established and disruptive go-to-market strategies.
""",
llm=LLM(model="claude-3-5-sonnet", temperature=0.3) # Criatividade balanceada com conhecimento de domínio
)
# Esse contexto faz o Claude agir como especialista do setor
# Sem isso, mesmo ele entregaria respostas genéricas
```
**Elementos de Backstory que Potencializam a Performance de LLMs:**
- **Experiência de Domínio**: "10+ anos em vendas enterprise SaaS"
- **Expertise Específica**: "Especialista em due diligence técnica para Série B+"
- **Estilo de Trabalho**: "Decisões orientadas a dados, documentação clara"
- **Padrões de Qualidade**: "Sempre cita fontes e mostra análise detalhada"
### c. Otimização Holística de Agente + LLM
As configurações mais eficazes criam sinergia entre função específica, profundidade do backstory e escolha do LLM. Cada elemento reforça o outro para maximizar rendimento.
**Framework de Otimização:**
```python
# Exemplo: Agente de Documentação Técnica
tech_writer = Agent(
role="API Documentation Specialist",
goal="Create comprehensive, developer-friendly API documentation",
backstory="""
You're a technical writer with 8+ years documenting REST APIs, GraphQL endpoints,
and SDK integration guides. You've worked with developer tools companies and
understand what developers need: clear examples, comprehensive error handling,
and practical use cases. You prioritize accuracy and usability over marketing fluff.
""",
llm=LLM(
model="claude-3-5-sonnet",
temperature=0.1
),
tools=[code_analyzer_tool, api_scanner_tool],
verbose=True
)
```
**Checklist de Alinhamento:**
- ✅ **Função Específica**: Domínio e responsabilidades claras
- ✅ **Correspondência do LLM**: Forças do modelo conectadas à função
- ✅ **Profundidade do Backstory**: Contexto de domínio disponível pro modelo
- ✅ **Integração de Ferramentas**: Ferramentas fortalecem a função do agente
- ✅ **Ajuste de Parâmetros**: Temperatura e configs otimizadas para a função
O segredo é criar agentes onde cada configuração reforça sua estratégia de escolha do LLM, maximizando rendimento e otimizando custos.
## Checklist Prático de Implementação
Em vez de repetir o framework estratégico, segue um checklist tático para implementar as decisões de seleção de LLM em CrewAI:
<Steps>
<Step title="Audite Sua Configuração Atual" icon="clipboard-check">
**O que analisar:**
- Todos os agentes usam o mesmo LLM por padrão?
- Quais agentes lidam com tarefas mais complexas?
- Quais agentes só processam ou formatam dados?
- Algum agente depende fortemente de ferramentas?
**Ação**: Documente funções dos agentes e identifique oportunidades de otimização.
</Step>
<Step title="Implemente Estratégia no Nível da Crew" icon="users-gear">
**Defina sua Base:**
```python
# Comece com um padrão confiável para a crew
default_crew_llm = LLM(model="gpt-4o-mini") # Base econômica
crew = Crew(
agents=[...],
tasks=[...],
memory=True
)
```
**Ação**: Defina o LLM padrão da crew antes de otimizar agentes individuais.
</Step>
<Step title="Otimize Agentes de Maior Impacto" icon="star">
**Identifique e Aprimore Agentes-Chave:**
```python
# Agentes gerenciadores ou de coordenação
manager_agent = Agent(
role="Project Manager",
llm=LLM(model="gemini-2.5-flash-preview-05-20"),
# ... demais configs
)
# Agentes criativos ou customer-facing
content_agent = Agent(
role="Content Creator",
llm=LLM(model="claude-3-5-sonnet"),
# ... demais configs
)
```
**Ação**: Faça upgrade dos 20% dos agentes que tratam 80% da complexidade.
</Step>
<Step title="Valide com Testes Empresariais" icon="test-tube">
**Após colocar os agentes em produção:**
- Use [CrewAI Enterprise platform](https://app.crewai.com) para testar seleções de modelo A/B
- Execute múltiplas iterações com inputs reais para medir consistência e performance
- Compare custo vs performance na configuração otimizada
- Compartilhe resultados com o time para tomada coletiva de decisão
**Ação**: Substitua achismos por validação com dados reais usando a plataforma de testes.
</Step>
</Steps>
### Quando Usar Tipos Diferentes de Modelos
<Tabs>
<Tab title="Modelos de Raciocínio">
Modelos de raciocínio tornam-se essenciais quando tarefas exigem pensamento lógico genuíno em múltiplas etapas, planejamento estratégico ou decisões complexas beneficiadas por análise sistemática. Brilham na decomposição de problemas e análise estruturada, não no simples seguimento de padrões.
Considere-os para desenvolvimento de estratégias de negócios, análise de dados combinados de múltiplas fontes, resolução de problemas dependente de etapas sucessivas e planejamento estratégico envolvendo múltiplas variáveis.
Entretanto, esses modelos são mais caros e lentos, devendo ser reservados para tarefas onde suas capacidades agregam valor real — evite usá-los apenas para operações simples.
</Tab>
<Tab title="Modelos Criativos">
Modelos criativos são valiosos quando a principal entrega é geração de conteúdo e a qualidade, estilo e engajamento desse conteúdo impactam o sucesso. Se destacam quando redação e estilo importam, ideação criativa é necessária, ou voz de marca é fundamental.
Use-os em redação de posts, criação de artigos, textos de marketing com viés persuasivo, storytelling e comunicações da marca. Costumam captar nuances e contexto melhor do que generalistas.
Podem ser menos adequados para tarefas técnicas ou analíticas, onde precisão supera criatividade. Use-os quando aspectos comunicativos são fatores críticos de sucesso.
</Tab>
<Tab title="Modelos Eficientes">
Modelos eficientes são ideais para operações frequentes e rotineiras, onde velocidade e custo são prioridade. Trabalham melhor em tarefas com parâmetros bem definidos, sem necessidade de raciocínio avançado ou criatividade.
Considere-os para processamento e transformação de dados, formatação simples, chamadas de funções (function calling) e operações em alto volume onde custo importa mais.
O ponto crítico é verificar adequação à tarefa. Funcionam para muitos fluxos rotineiros, mas podem falhar se a tarefa exigir compreensão técnica ou raciocínio.
</Tab>
<Tab title="Modelos Open Source">
Modelos open source são atraentes quando há restrição orçamentária, necessidade de privacidade, personalização especial ou exigência de deployment local.
Considere para ferramentas internas de empresas, aplicações sensíveis, projetos onde não é possível usar APIs externas, casos com orçamento apertado ou requisitos de customização.
Mas lembre-se: exigem mais expertise, manutenção e investimentos em infraestrutura. Avalie o custo total da operação ao avaliar esses modelos.
</Tab>
</Tabs>
## Armadilhas Comuns na Seleção de Modelos CrewAI
<AccordionGroup>
<Accordion title="A Armadilha do 'Um Modelo Serve para Tudo'" icon="triangle-exclamation">
**O problema**: Usar o mesmo LLM para todos os agentes, independentemente das funções. Prática padrão, mas raramente ótima.
**Exemplo real**: Usar GPT-4o tanto para planejamento estratégico quanto para extração simples de dados. O manager precisa do raciocínio premium, mas o extrator poderia usar o GPT-4o-mini, muito mais barato.
**Solução CrewAI**: Configure modelos específicos por agente:
```python
# Agente estratégico recebe modelo premium
manager = Agent(role="Strategy Manager", llm=LLM(model="gpt-4o"))
# Agente de processamento recebe modelo eficiente
processor = Agent(role="Data Processor", llm=LLM(model="gpt-4o-mini"))
```
</Accordion>
<Accordion title="Ignorar Hierarquia de LLM entre Crew e Agente" icon="shuffle">
**O problema**: Não entender como funciona a hierarquia LLM da CrewAI — configurações conflitam entre crew, manager e agentes.
**Exemplo real**: Configurar crew com Claude, mas agentes com GPT, gerando comportamento inconsistente e trocas desnecessárias.
**Solução CrewAI**: Planeje a hierarquia estrategicamente:
```python
crew = Crew(
agents=[agent1, agent2],
tasks=[task1, task2],
manager_llm=LLM(model="gpt-4o"),
process=Process.hierarchical
)
# Agentes herdam o LLM da crew, salvo sobrescrita
agent1 = Agent(llm=LLM(model="claude-3-5-sonnet"))
```
</Accordion>
<Accordion title="Incompatibilidade para Function Calling" icon="screwdriver-wrench">
**O problema**: Escolher modelos pela capacidade geral e ignorar o desempenho em function calling em workflows intensivos em ferramentas.
**Exemplo real**: Selecionar modelo criativo para agente que só precisa chamar APIs e processar dados estruturados, resultando em má extração de parâmetros.
**Solução CrewAI**: Priorize desempenho em function calling para agentes que usam ferramentas:
```python
# Para agentes com muitas ferramentas
tool_agent = Agent(
role="API Integration Specialist",
tools=[search_tool, api_tool, data_tool],
llm=LLM(model="gpt-4o"),
# OU
llm=LLM(model="claude-3-5-sonnet")
)
```
</Accordion>
<Accordion title="Otimização Prematura sem Teste" icon="gear">
**O problema**: Decidir configurações complexas de modelo com base em hipóteses não validadas nos fluxos e tarefas reais CrewAI.
**Exemplo real**: Implementar lógica elaborada de troca de modelo por tipo de tarefa sem testar se os ganhos compensam a complexidade.
**Solução CrewAI**: Comece simples e otimize baseado em dados reais:
```python
# Comece assim
crew = Crew(agents=[...], tasks=[...], llm=LLM(model="gpt-4o-mini"))
# Teste a performance e só depois otimize agentes específicos
# Use testes Enterprise para validar melhorias
```
</Accordion>
<Accordion title="Ignorar Limites de Contexto e Memória" icon="brain">
**O problema**: Não considerar como janela de contexto dos modelos interage com memória e compartilhamento de contexto entre agentes CrewAI.
**Exemplo real**: Usar modelo de contexto curto para agentes que precisam manter histórico ao longo de múltiplas iterações ou equipes com comunicação extensiva agent-to-agent.
**Solução CrewAI**: Alinhe capacidades de contexto ao padrão de comunicação da crew.
</Accordion>
</AccordionGroup>
## Estratégia de Teste e Iteração
<Steps>
<Step title="Comece Simples" icon="play">
Comece com modelos de uso geral, confiáveis e amplamente suportados. Isso estabelece base estável para entender necessidades e expectativas de desempenho antes de otimizar para demandas especializadas.
</Step>
<Step title="Meça o que Importa" icon="chart-line">
Desenvolva métricas alinhadas ao seu caso de uso e metas de negócio, não apenas benchmarks gerais. Foque na mensuração de resultados relevantes ao seu sucesso.
</Step>
<Step title="Itere Baseado em Resultados" icon="arrows-rotate">
Faça mudanças baseadas no desempenho observado no seu contexto, não apenas considerações teóricas ou recomendações genéricas. O desempenho prático costuma ser bem diferente dos benchmarks.
</Step>
<Step title="Considere o Custo Total" icon="calculator">
Avalie todo custo de operação, incluindo modelo, tempo de desenvolvimento, manutenção e complexidade. O modelo mais barato por token pode não ser o mais econômico ao considerar todos os fatores.
</Step>
</Steps>
<Tip>
Foque em entender seus requisitos primeiro, e então escolha modelos que melhor correspondam a essas necessidades. O melhor LLM é aquele que consistentemente entrega os resultados esperados dentro das suas restrições.
</Tip>
### Validação de Modelos em Nível Enterprise
Para equipes sérias sobre otimização, a **plataforma CrewAI Enterprise** oferece testes sofisticados que vão além do CLI. Ela permite avaliação completa para decisões orientadas por dados na estratégia de LLM.
<Frame>
![Enterprise Testing Interface](/images/enterprise/enterprise-testing.png)
</Frame>
**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!
<Info>
A plataforma Enterprise transforma a seleção de modelos de um "palpite" para um processo orientado por dados, permitindo validar os princípios deste guia com seus próprios casos de uso.
</Info>
## Resumo dos Princípios-Chave
<CardGroup cols={2}>
<Card title="Seleção Orientada à Tarefa" icon="bullseye">
Escolha os modelos pelo que sua tarefa realmente requer, não por reputação ou capacidades teóricas.
</Card>
<Card title="Combinação de Capacidades" icon="puzzle-piece">
Alinhe forças do modelo a papéis e responsabilidades dos agentes para melhor desempenho.
</Card>
<Card title="Consistência Estratégica" icon="link">
Mantenha uma estratégia coerente de seleção de modelos em fluxos e componentes relacionados.
</Card>
<Card title="Testes Práticos" icon="flask">
Valide escolhas em uso real, não apenas em benchmarks.
</Card>
<Card title="Iteração Contínua" icon="arrow-up">
Comece simples e otimize com base na performance e necessidade práticas.
</Card>
<Card title="Equilíbrio Operacional" icon="scale-balanced">
Equilibre performance requerida, custo e complexidade.
</Card>
</CardGroup>
<Check>
Lembre-se: o melhor LLM é o que entrega consistentemente os resultados de que você precisa dentro de suas restrições. Conheça seu requisito primeiro, depois selecione o modelo mais adequado.
</Check>
## Panorama Atual dos Modelos (Junho/2025)
<Warning>
**Retrato do Momento**: Os rankings a seguir representam o estado da arte em Junho de 2025, compilados do [LMSys Arena](https://arena.lmsys.org/), [Artificial Analysis](https://artificialanalysis.ai/) e outros benchmarks líderes. Performance, disponibilidade e preço mudam rapidamente. Sempre valide com seus dados e casos reais.
</Warning>
### Principais Modelos por Categoria
As tabelas abaixo mostram uma amostra dos modelos de maior destaque em cada categoria, junto de orientação sobre aplicação em agentes CrewAI:
<Note>
Estas tabelas exibem apenas alguns modelos líderes por categoria. Existem muitos outros excelentes. O objetivo é ilustrar exemplos de capacidades buscadas em vez de apresentar um catálogo completo.
</Note>
<Tabs>
<Tab title="Raciocínio & Planejamento">
**Melhores para LLMs Manager e Análises Complexas**
| Modelo | Score de Inteligência | Custo ($/M tokens) | Velocidade | Melhor Uso em CrewAI |
|:------|:---------------------|:-------------------|:-----------|:--------------------|
| **o3** | 70 | $17.50 | Rápido | Manager LLM para coordenação multi-agente |
| **Gemini 2.5 Pro** | 69 | $3.44 | Rápido | Agentes de planejamento estratégico, coordenação de pesquisa |
| **DeepSeek R1** | 68 | $0.96 | Moderada | Raciocínio com bom custo-benefício |
| **Claude 4 Sonnet** | 53 | $6.00 | Rápido | Agentes de análise que precisam de nuance |
| **Qwen3 235B (Reasoning)** | 62 | $2.63 | Moderada | Alternativa open source para raciocínio |
Esses modelos se destacam em raciocínio multi-etapas e são ideais para agentes que desenvolvem estratégias, coordenam outros agentes ou analisam informações complexas.
</Tab>
<Tab title="Codificação & Técnica">
**Melhores para Desenvolvimento e Workflows com Ferramentas**
| Modelo | Performance em Coding | Tool Use Score | Custo ($/M tokens) | Melhor Uso em CrewAI |
|:--------|:---------------------|:--------------|:-------------------|:--------------------|
| **Claude 4 Sonnet** | Excelente | 72.7% | $6.00 | Agente principal de código/documentação técnica |
| **Claude 4 Opus** | Excelente | 72.5% | $30.00 | Arquitetura complexa, code review |
| **DeepSeek V3** | Muito bom | Alto | $0.48 | Coding econômico para desenvolvimentos rotineiros |
| **Qwen2.5 Coder 32B** | Muito bom | Médio | $0.15 | Agente de código econômico |
| **Llama 3.1 405B** | Bom | 81.1% | $3.50 | LLM para function calling em workflows intensivos em ferramentas |
Otimizados para geração de código, debugging e solução técnica, ideais para equipes de desenvolvimento.
</Tab>
<Tab title="Velocidade & Eficiência">
**Melhores para Operações em Massa e Aplicações em Tempo Real**
| Modelo | Velocidade (tokens/s) | Latência (TTFT) | Custo ($/M tokens) | Melhor Uso em CrewAI |
|:-------|:---------------------|:----------------|:-------------------|:---------------------|
| **Llama 4 Scout** | 2.600 | 0.33s | $0.27 | Agentes de processamento de alto volume |
| **Gemini 2.5 Flash** | 376 | 0.30s | $0.26 | Agentes de resposta em tempo real |
| **DeepSeek R1 Distill** | 383 | Variável | $0.04 | Processamento rápido de baixo custo |
| **Llama 3.3 70B** | 2.500 | 0.52s | $0.60 | Equilíbrio entre velocidade e capacidade |
| **Nova Micro** | Alto | 0.30s | $0.04 | Execução rápida de tarefas simples |
Priorizam velocidade e eficiência, perfeitos para agentes em operações de rotina ou resposta ágil. **Dica:** Usar provedores de inference rápidos como Groq potencializa open source como Llama.
</Tab>
<Tab title="Performance Equilibrada">
**Melhores Modelos Coringa para Crews Diversos**
| Modelo | Score Global | Versatilidade | Custo ($/M tokens) | Melhor Uso em CrewAI |
|:------------|:--------------|:-------------|:-------------------|:--------------------|
| **GPT-4.1** | 53 | Excelente | $3.50 | LLM generalista para equipes variadas |
| **Claude 3.7 Sonnet** | 48 | Muito boa | $6.00 | Raciocínio e criatividade balanceados |
| **Gemini 2.0 Flash** | 48 | Boa | $0.17 | Generalista de bom custo benefício |
| **Llama 4 Maverick** | 51 | Boa | $0.37 | Open source para usos gerais |
| **Qwen3 32B** | 44 | Boa | $1.23 | Versatilidade econômica |
Oferecem bom desempenho geral, adequados para crews com demandas amplas.
</Tab>
</Tabs>
### Framework de Seleção para Modelos Atuais
<AccordionGroup>
<Accordion title="Crews de Alta Performance" icon="rocket">
**Priorizando performance**: Use modelos topo de linha como **o3**, **Gemini 2.5 Pro** ou **Claude 4 Sonnet** para managers e agentes críticos. Excelentes em raciocínio e coordenação, porém mais caros.
**Estratégia**: Implemente abordagem multi-modelo, reservando premium para raciocínio estratégico e eficientes para operações rotineiras.
</Accordion>
<Accordion title="Crews de Baixo Custo" icon="dollar-sign">
**Foco no orçamento**: Foque em modelos como **DeepSeek R1**, **Llama 4 Scout** ou **Gemini 2.0 Flash**, que trazem ótimo desempenho com investimento reduzido.
**Estratégia**: Use modelos econômicos para maioria dos agentes, reservando premium apenas para funções críticas.
</Accordion>
<Accordion title="Workflows Especializados" icon="screwdriver-wrench">
**Para expertise específica**: Escolha modelos otimizados para seu principal caso de uso: **Claude 4** em código, **Gemini 2.5 Pro** em pesquisa, **Llama 405B** em function calling.
**Estratégia**: Selecione conforme a principal função da crew, garantindo alinhamento de capacidade e modelo.
</Accordion>
<Accordion title="Empresa & Privacidade" icon="shield">
**Para operações sensíveis**: Avalie modelos open source como **Llama 4** series, **DeepSeek V3** ou **Qwen3** para deployment privado, mantendo performance competitiva.
**Estratégia**: Use open source em infraestrutura própria e aceite possíveis trade-offs por controle dos dados.
</Accordion>
</AccordionGroup>
### Considerações-Chave na Seleção de Modelos
- **Tendências de Performance**: O cenário atual mostra competição forte entre modelos de raciocínio (o3, Gemini 2.5 Pro) e equilibrados (Claude 4, GPT-4.1). Modelos como DeepSeek R1 entregam excelente custo/performance.
- **Trade-off Velocidade x Inteligência**: Modelos como Llama 4 Scout priorizam velocidade (2.600 tokens/s) e inteligência razoável, enquanto outros como o3 maximizam raciocínio em detrimento de velocidade/preço.
- **Viabilidade Open Source**: A distância entre open source e proprietários diminui a cada mês, com Llama 4 Maverick e DeepSeek V3 entregando performance competitiva a preços atrativos. Inferência rápida via Groq maximiza custo-benefício nesses casos.
<Info>
**Testes são essenciais**: Rankings servem de orientação geral, mas seu caso de uso, prompt e critério podem gerar resultados distintos. Sempre teste modelos candidatos com suas tarefas e dados reais antes de decidir.
</Info>
### Estratégia Prática de Implementação
<Steps>
<Step title="Comece por Modelos Validados">
Inicie com opções consagradas como **GPT-4.1**, **Claude 3.7 Sonnet** ou **Gemini 2.0 Flash**, que oferecem bom desempenho e ampla validação.
</Step>
<Step title="Identifique Demandas Especializadas">
Descubra se sua crew possui requisitos específicos (código, raciocínio, velocidade) que justifiquem modelos como **Claude 4 Sonnet** para desenvolvimento ou **o3** para análise. Para aplicações críticas em velocidade, considere Groq aliado à seleção do modelo.
</Step>
<Step title="Implemente Estratégia Multi-Modelo">
Use modelos diferentes para agentes distintos conforme o papel. Modelos de alta capacidade para managers e tarefas complexas, eficientes para rotinas.
</Step>
<Step title="Monitore e Otimize">
Acompanhe métricas relevantes ao seu caso e esteja pronto para ajustar modelos conforme lançamentos ou mudanças de preços.
</Step>
</Steps>

140
docs/pt-BR/learn/multimodal-agents.mdx Normal file
View File

@@ -0,0 +1,140 @@
---
title: Usando Agentes Multimodais
description: Aprenda como habilitar e usar capacidades multimodais em seus agentes para processar imagens e outros conteúdos não textuais dentro do framework CrewAI.
icon: video
---
## Usando Agentes Multimodais
O CrewAI suporta agentes multimodais que podem processar tanto conteúdo textual quanto não textual, como imagens. Este guia mostrará como habilitar e utilizar capacidades multimodais em seus agentes.
### Habilitando Capacidades Multimodais
Para criar um agente multimodal, basta definir o parâmetro `multimodal` como `True` ao inicializar seu agente:
```python
from crewai import Agent
agent = Agent(
role="Image Analyst",
goal="Analyze and extract insights from images",
backstory="An expert in visual content interpretation with years of experience in image analysis",
multimodal=True # This enables multimodal capabilities
)
```
Ao definir `multimodal=True`, o agente é automaticamente configurado com as ferramentas necessárias para lidar com conteúdo não textual, incluindo a `AddImageTool`.
### Trabalhando com Imagens
O agente multimodal vem pré-configurado com a `AddImageTool`, permitindo que ele processe imagens. Não é necessário adicionar esta ferramenta manualmente – ela é automaticamente incluída ao habilitar capacidades multimodais.
Aqui está um exemplo completo mostrando como usar um agente multimodal para analisar uma imagem:
```python
from crewai import Agent, Task, Crew
# Create a multimodal agent
image_analyst = Agent(
role="Product Analyst",
goal="Analyze product images and provide detailed descriptions",
backstory="Expert in visual product analysis with deep knowledge of design and features",
multimodal=True
)
# Create a task for image analysis
task = Task(
description="Analyze the product image at https://example.com/product.jpg and provide a detailed description",
expected_output="A detailed description of the product image",
agent=image_analyst
)
# Create and run the crew
crew = Crew(
agents=[image_analyst],
tasks=[task]
)
result = crew.kickoff()
```
### Uso Avançado com Contexto
Você pode fornecer contexto adicional ou perguntas específicas sobre a imagem ao criar tarefas para agentes multimodais. A descrição da tarefa pode incluir aspectos específicos nos quais você deseja que o agente foque:
```python
from crewai import Agent, Task, Crew
# Create a multimodal agent for detailed analysis
expert_analyst = Agent(
role="Visual Quality Inspector",
goal="Perform detailed quality analysis of product images",
backstory="Senior quality control expert with expertise in visual inspection",
multimodal=True # AddImageTool is automatically included
)
# Create a task with specific analysis requirements
inspection_task = Task(
description="""
Analyze the product image at https://example.com/product.jpg with focus on:
1. Quality of materials
2. Manufacturing defects
3. Compliance with standards
Provide a detailed report highlighting any issues found.
""",
expected_output="A detailed report highlighting any issues found",
agent=expert_analyst
)
# Create and run the crew
crew = Crew(
agents=[expert_analyst],
tasks=[inspection_task]
)
result = crew.kickoff()
```
### Detalhes da Ferramenta
Ao trabalhar com agentes multimodais, a `AddImageTool` é automaticamente configurada com o seguinte esquema:
```python
class AddImageToolSchema:
image_url: str # Required: The URL or path of the image to process
action: Optional[str] = None # Optional: Additional context or specific questions about the image
```
O agente multimodal irá automaticamente realizar o processamento de imagens por meio de suas ferramentas internas, permitindo que ele:
- Acesse imagens via URLs ou caminhos de arquivos locais
- Processe o conteúdo da imagem com contexto opcional ou perguntas específicas
- Forneça análises e insights com base nas informações visuais e requisitos da tarefa
### Boas Práticas
Ao trabalhar com agentes multimodais, tenha em mente as seguintes boas práticas:
1. **Acesso à Imagem**
- Certifique-se de que suas imagens estejam acessíveis via URLs alcançáveis pelo agente
- Para imagens locais, considere hospedá-las temporariamente ou utilize caminhos absolutos
- Verifique se as URLs das imagens são válidas e acessíveis antes de rodar as tarefas
2. **Descrição da Tarefa**
- Seja específico sobre quais aspectos da imagem você deseja que o agente analise
- Inclua perguntas ou requisitos claros na descrição da tarefa
- Considere usar o parâmetro opcional `action` para uma análise focada
3. **Gerenciamento de Recursos**
- O processamento de imagens pode exigir mais recursos computacionais do que tarefas apenas textuais
- Alguns modelos de linguagem podem exigir codificação em base64 para dados de imagem
- Considere o processamento em lote para múltiplas imagens visando otimizar o desempenho
4. **Configuração do Ambiente**
- Verifique se seu ambiente possui as dependências necessárias para processamento de imagens
- Certifique-se de que seu modelo de linguagem suporta capacidades multimodais
- Teste primeiro com imagens pequenas para validar sua configuração
5. **Tratamento de Erros**
- Implemente tratamento apropriado para falhas no carregamento de imagens
- Tenha estratégias de contingência para casos onde o processamento de imagens falhar
- Monitore e registre operações de processamento de imagens para depuração

158
docs/pt-BR/learn/overview.mdx Normal file
View File

@@ -0,0 +1,158 @@
---
title: "Visão Geral"
description: "Aprenda como construir, personalizar e otimizar suas aplicações CrewAI com guias e tutoriais completos"
icon: "face-smile"
---
## Aprenda CrewAI
Esta seção fornece guias e tutoriais completos para ajudar você a dominar o CrewAI, desde conceitos básicos até técnicas avançadas. Seja você iniciante ou esteja buscando otimizar suas implementações existentes, estes recursos o guiarão por todos os aspectos da construção de workflows poderosos de agentes de IA.
## Guias de Introdução
### Conceitos Centrais
<CardGroup cols={2}>
<Card title="Processo Sequencial" icon="list-ol" href="/pt-BR/learn/sequential-process">
Aprenda a executar tarefas em ordem sequencial para workflows estruturados.
</Card>
<Card title="Processo Hierárquico" icon="sitemap" href="/pt-BR/learn/hierarchical-process">
Implemente execução hierárquica de tarefas com agentes gerentes supervisionando workflows.
</Card>
<Card title="Tarefas Condicionais" icon="code-branch" href="/pt-BR/learn/conditional-tasks">
Crie workflows dinâmicos com execução condicional de tarefas baseada em resultados.
</Card>
<Card title="Kickoff Assíncrono" icon="bolt" href="/pt-BR/learn/kickoff-async">
Execute crews de forma assíncrona para melhorar desempenho e concorrência.
</Card>
</CardGroup>
### Desenvolvimento de Agentes
<CardGroup cols={2}>
<Card title="Personalizando Agentes" icon="user-gear" href="/pt-BR/learn/customizing-agents">
Aprenda como personalizar o comportamento, funções e capacidades dos agentes.
</Card>
<Card title="Codificando Agentes" icon="code" href="/pt-BR/learn/coding-agents">
Construa agentes que podem escrever, executar e depurar código automaticamente.
</Card>
<Card title="Agentes Multimodais" icon="images" href="/pt-BR/learn/multimodal-agents">
Crie agentes capazes de processar texto, imagens e outros tipos de mídia.
</Card>
<Card title="Agente Gerente Personalizado" icon="user-tie" href="/pt-BR/learn/custom-manager-agent">
Implemente agentes gerentes personalizados para workflows hierárquicos complexos.
</Card>
</CardGroup>
## Funcionalidades Avançadas
### Controle de Workflow
<CardGroup cols={2}>
<Card title="Humano no Loop" icon="user-check" href="/pt-BR/learn/human-in-the-loop">
Integre supervisão e intervenção humana aos workflows dos agentes.
</Card>
<Card title="Entrada Humana na Execução" icon="hand-paper" href="/pt-BR/learn/human-input-on-execution">
Permita entrada humana durante a execução de tarefas para tomada de decisões dinâmicas.
</Card>
<Card title="Repetir Tarefas" icon="rotate-left" href="/pt-BR/learn/replay-tasks-from-latest-crew-kickoff">
Refaça e retome tarefas a partir de execuções anteriores de crews.
</Card>
<Card title="Kickoff para Cada" icon="repeat" href="/pt-BR/learn/kickoff-for-each">
Execute crews múltiplas vezes com diferentes entradas de maneira eficiente.
</Card>
</CardGroup>
### Personalização & Integração
<CardGroup cols={2}>
<Card title="LLM Personalizado" icon="brain" href="/pt-BR/learn/custom-llm">
Integre modelos de linguagem personalizados e provedores ao CrewAI.
</Card>
<Card title="Conexões LLM" icon="link" href="/pt-BR/learn/llm-connections">
Configure e gerencie conexões com vários provedores de LLM.
</Card>
<Card title="Criar Ferramentas Personalizadas" icon="wrench" href="/pt-BR/learn/create-custom-tools">
Construa ferramentas personalizadas para estender as capacidades dos agentes.
</Card>
<Card title="Usando Anotações" icon="at" href="/pt-BR/learn/using-annotations">
Use anotações Python para um código mais limpo e fácil de manter.
</Card>
</CardGroup>
## Aplicações Especializadas
### Conteúdo & Mídia
<CardGroup cols={2}>
<Card title="Geração de Imagens DALL-E" icon="image" href="/pt-BR/learn/dalle-image-generation">
Gere imagens utilizando a integração DALL-E com seus agentes.
</Card>
<Card title="Traga Seu Próprio Agente" icon="user-plus" href="/pt-BR/learn/bring-your-own-agent">
Integre agentes e modelos já existentes aos workflows do CrewAI.
</Card>
</CardGroup>
### Gerenciamento de Ferramentas
<CardGroup cols={2}>
<Card title="Forçar Saída da Ferramenta como Resultado" icon="hammer" href="/pt-BR/learn/force-tool-output-as-result">
Configure ferramentas para retornarem sua saída diretamente como resultado da tarefa.
</Card>
</CardGroup>
## Recomendações de Rotas de Aprendizagem
### Para Iniciantes
1. Comece pelo **Processo Sequencial** para entender a execução básica de workflows
2. Aprenda **Personalizando Agentes** para criar configurações de agentes eficazes
3. Explore **Criar Ferramentas Personalizadas** para estender funcionalidades
4. Experimente **Humano no Loop** para workflows interativos
### Para Usuários Intermediários
1. Domine **Processo Hierárquico** para sistemas multiagente complexos
2. Implemente **Tarefas Condicionais** para workflows dinâmicos
3. Utilize **Kickoff Assíncrono** para otimizar desempenho
4. Integre **LLM Personalizado** para modelos especializados
### Para Usuários Avançados
1. Construa **Agentes Multimodais** para processamento complexo de mídias
2. Crie **Agentes Gerentes Personalizados** para orquestração sofisticada
3. Implemente **Traga Seu Próprio Agente** para sistemas híbridos
4. Use **Repetir Tarefas** para recuperação de erros robusta
## Melhores Práticas
### Desenvolvimento
- **Comece Simples**: Inicie com workflows sequenciais básicos antes de adicionar complexidade
- **Teste de Forma Incremental**: Teste cada componente antes de integrar em sistemas maiores
- **Use Anotações**: Aproveite as anotações Python para código mais limpo e sustentável
- **Ferramentas Personalizadas**: Crie ferramentas reutilizáveis que possam ser compartilhadas entre diferentes agentes
### Produção
- **Tratamento de Erros**: Implemente mecanismos robustos de tratamento e recuperação de erros
- **Desempenho**: Utilize execução assíncrona e otimize chamadas a LLM para melhor desempenho
- **Monitoramento**: Integre ferramentas de observabilidade para acompanhar o desempenho dos agentes
- **Supervisão Humana**: Inclua checkpoints humanos para decisões críticas
### Otimização
- **Gestão de Recursos**: Monitore e otimize o uso de tokens e custos de API
- **Design de Workflow**: Elabore workflows que minimizem chamadas desnecessárias ao LLM
- **Eficiência das Ferramentas**: Crie ferramentas eficientes que ofereçam máximo valor com o mínimo de overhead
- **Aprimoramento Iterativo**: Use feedback e métricas para melhorar continuamente o desempenho dos agentes
## Obtendo Ajuda
- **Documentação**: Cada guia inclui exemplos detalhados e explicações
- **Comunidade**: Participe do [Fórum CrewAI](https://community.crewai.com) para discussões e suporte
- **Exemplos**: Consulte a seção de Exemplos para implementações completas e funcionais
- **Suporte**: Entre em contato via [support@crewai.com](mailto:support@crewai.com) para assistência técnica
Comece pelos guias que atendem às suas necessidades atuais e, gradualmente, explore tópicos mais avançados conforme você se sentir confortável com os fundamentos.

78
docs/pt-BR/learn/replay-tasks-from-latest-crew-kickoff.mdx Normal file
View File

@@ -0,0 +1,78 @@
---
title: Reexecutar Tarefas a partir do Último Crew Kickoff
description: Reexecute tarefas a partir do último crew.kickoff(...)
icon: arrow-right
---
## Introdução
O CrewAI oferece a capacidade de reexecutar uma tarefa especificada a partir do último crew kickoff. Esse recurso é particularmente útil quando você concluiu um kickoff e deseja tentar novamente determinadas tarefas, ou não precisa buscar dados novamente porque seus agentes já possuem o contexto salvo da execução do kickoff, sendo necessário apenas reexecutar as tarefas desejadas.
<Note>
Você deve executar `crew.kickoff()` antes de poder reexecutar uma tarefa.
Atualmente, apenas o kickoff mais recente é suportado, então se você utilizar `kickoff_for_each`, será possível reexecutar apenas a partir da execução de crew mais recente.
</Note>
Aqui está um exemplo de como reexecutar a partir de uma tarefa:
### Reexecutando a partir de uma Tarefa Específica Usando o CLI
Para utilizar o recurso de reexecução, siga estes passos:
<Steps>
<Step title="Abra seu terminal ou prompt de comando."></Step>
<Step title="Navegue até o diretório onde está localizado seu projeto CrewAI."></Step>
<Step title="Execute os seguintes comandos:">
Para visualizar os task_ids do último kickoff, utilize:
```shell
crewai log-tasks-outputs
```
Após identificar o `task_id` que deseja reexecutar, utilize:
```shell
crewai replay -t <task_id>
```
</Step>
</Steps>
<Note>
Certifique-se de que o `crewai` está instalado e devidamente configurado no seu ambiente de desenvolvimento.
</Note>
### Reexecutando uma Tarefa Programaticamente
Para reexecutar uma tarefa programaticamente, siga os passos abaixo:
<Steps>
<Step title="Especifique o `task_id` e os parâmetros de entrada para o processo de reexecução.">
Especifique o `task_id` e os parâmetros de entrada para o processo de reexecução.
</Step>
<Step title="Execute o comando de reexecução dentro de um bloco try-except para lidar com possíveis erros.">
Execute o comando de reexecução dentro de um bloco try-except para lidar com possíveis erros.
<CodeGroup>
```python Code
def replay():
"""
Replay the crew execution from a specific task.
"""
task_id = '<task_id>'
inputs = {"topic": "CrewAI Training"} # This is optional; you can pass in the inputs you want to replay; otherwise, it uses the previous kickoff's inputs.
try:
YourCrewName_Crew().crew().replay(task_id=task_id, inputs=inputs)
except subprocess.CalledProcessError as e:
raise Exception(f"An error occurred while replaying the crew: {e}")
except Exception as e:
raise Exception(f"An unexpected error occurred: {e}")
```
</CodeGroup>
</Step>
</Steps>
## Conclusão
Com as melhorias acima e funcionalidades detalhadas, a reexecução de tarefas específicas no CrewAI ficou mais eficiente e robusta.
Certifique-se de seguir exatamente os comandos e passos para aproveitar ao máximo esses recursos.

127
docs/pt-BR/learn/sequential-process.mdx Normal file
View File

@@ -0,0 +1,127 @@
---
title: Processos Sequenciais
description: Um guia abrangente para utilizar os processos sequenciais na execução de tarefas em projetos CrewAI.
icon: forward
---
## Introdução
O CrewAI oferece uma estrutura flexível para execução de tarefas de maneira estruturada, suportando tanto processos sequenciais quanto hierárquicos.
Este guia descreve como implementar esses processos de forma eficaz para garantir execução eficiente das tarefas e a conclusão do projeto.
## Visão Geral do Processo Sequencial
O processo sequencial garante que as tarefas sejam executadas uma após a outra, seguindo um progresso linear.
Essa abordagem é ideal para projetos nos quais as tarefas precisam ser concluídas em uma ordem específica.
### Principais Características
- **Fluxo Linear de Tarefas**: Garante o progresso ordenado ao tratar tarefas em uma sequência pré-determinada.
- **Simplicidade**: Melhor opção para projetos com tarefas claras e passo a passo.
- **Fácil Monitoramento**: Facilita o acompanhamento da conclusão das tarefas e do progresso do projeto.
## Implementando o Processo Sequencial
Para utilizar o processo sequencial, monte sua crew e defina as tarefas na ordem em que devem ser executadas.
```python Code
from crewai import Crew, Process, Agent, Task, TaskOutput, CrewOutput
# Define your agents
researcher = Agent(
role='Researcher',
goal='Conduct foundational research',
backstory='An experienced researcher with a passion for uncovering insights'
)
analyst = Agent(
role='Data Analyst',
goal='Analyze research findings',
backstory='A meticulous analyst with a knack for uncovering patterns'
)
writer = Agent(
role='Writer',
goal='Draft the final report',
backstory='A skilled writer with a talent for crafting compelling narratives'
)
# Define your tasks
research_task = Task(
description='Gather relevant data...',
agent=researcher,
expected_output='Raw Data'
)
analysis_task = Task(
description='Analyze the data...',
agent=analyst,
expected_output='Data Insights'
)
writing_task = Task(
description='Compose the report...',
agent=writer,
expected_output='Final Report'
)
# Form the crew with a sequential process
report_crew = Crew(
agents=[researcher, analyst, writer],
tasks=[research_task, analysis_task, writing_task],
process=Process.sequential
)
# Execute the crew
result = report_crew.kickoff()
# Accessing the type-safe output
task_output: TaskOutput = result.tasks[0].output
crew_output: CrewOutput = result.output
```
### Nota:
Cada tarefa em um processo sequencial **deve** ter um agente atribuído. Certifique-se de que todo `Task` inclua um parâmetro `agent`.
### Fluxo de Trabalho em Ação
1. **Tarefa Inicial**: Em um processo sequencial, o primeiro agente conclui sua tarefa e sinaliza a finalização.
2. **Tarefas Subsequentes**: Os agentes assumem suas tarefas conforme o tipo de processo, com os resultados das tarefas anteriores ou diretrizes orientando sua execução.
3. **Finalização**: O processo é concluído assim que a última tarefa é executada, levando à conclusão do projeto.
## Funcionalidades Avançadas
### Delegação de Tarefas
Em processos sequenciais, se um agente possui `allow_delegation` definido como `True`, ele pode delegar tarefas para outros agentes na crew.
Esse recurso é configurado automaticamente quando há múltiplos agentes na crew.
### Execução Assíncrona
As tarefas podem ser executadas de forma assíncrona, permitindo processamento paralelo quando apropriado.
Para criar uma tarefa assíncrona, defina `async_execution=True` ao criar a tarefa.
### Memória e Cache
O CrewAI suporta recursos de memória e cache:
- **Memória**: Habilite definindo `memory=True` ao criar a Crew. Isso permite aos agentes reter informações entre as tarefas.
- **Cache**: Por padrão, o cache está habilitado. Defina `cache=False` para desativá-lo.
### Callbacks
Você pode definir callbacks tanto no nível da tarefa quanto no nível de etapa:
- `task_callback`: Executado após a conclusão de cada tarefa.
- `step_callback`: Executado após cada etapa na execução de um agente.
### Métricas de Uso
O CrewAI rastreia o uso de tokens em todas as tarefas e agentes. Você pode acessar essas métricas após a execução.
## Melhores Práticas para Processos Sequenciais
1. **A Ordem Importa**: Organize as tarefas em uma sequência lógica, onde cada uma aproveite o resultado da anterior.
2. **Descrições Claras de Tarefas**: Forneça descrições detalhadas para cada tarefa, orientando os agentes de forma eficaz.
3. **Seleção Apropriada de Agentes**: Relacione as habilidades e funções dos agentes às necessidades de cada tarefa.
4. **Use o Contexto**: Aproveite o contexto das tarefas anteriores para informar as seguintes.
Esta documentação atualizada garante que os detalhes reflitam com precisão as últimas mudanças no código e descreve claramente como aproveitar novos recursos e configurações.
O conteúdo foi mantido simples e direto para garantir fácil compreensão.

141
docs/pt-BR/learn/using-annotations.mdx Normal file
View File

@@ -0,0 +1,141 @@
---
title: "Usando Anotações no crew.py"
description: "Aprenda como usar anotações para estruturar corretamente agentes, tarefas e componentes no CrewAI"
icon: "at"
---
Este guia explica como utilizar anotações para referenciar corretamente **agentes**, **tarefas** e outros componentes no arquivo `crew.py`.
## Introdução
As anotações no framework CrewAI são utilizadas para decorar classes e métodos, fornecendo metadados e funcionalidades para diversos componentes do seu crew. Essas anotações auxiliam na organização e estruturação do seu código, tornando-o mais legível e fácil de manter.
## Anotações Disponíveis
O framework CrewAI fornece as seguintes anotações:
- `@CrewBase`: Usada para decorar a classe principal do crew.
- `@agent`: Decora métodos que definem e retornam objetos Agent.
- `@task`: Decora métodos que definem e retornam objetos Task.
- `@crew`: Decora o método que cria e retorna o objeto Crew.
- `@llm`: Decora métodos que inicializam e retornam objetos Language Model.
- `@tool`: Decora métodos que inicializam e retornam objetos Tool.
- `@callback`: Utilizada para definir métodos de callback.
- `@output_json`: Utilizada para métodos que retornam dados em JSON.
- `@output_pydantic`: Utilizada para métodos que retornam modelos Pydantic.
- `@cache_handler`: Utilizada para definição de métodos de manipulação de cache.
## Exemplos de Uso
Vamos passar por exemplos de como utilizar essas anotações:
### 1. Classe Base do Crew
```python
@CrewBase
class LinkedinProfileCrew():
"""LinkedinProfile crew"""
agents_config = 'config/agents.yaml'
tasks_config = 'config/tasks.yaml'
```
A anotação `@CrewBase` é usada para decorar a classe principal do crew. Esta classe geralmente contém as configurações e métodos para criação de agentes, tarefas e do próprio crew.
### 2. Definição de Tool
```python
@tool
def myLinkedInProfileTool(self):
return LinkedInProfileTool()
```
A anotação `@tool` é usada para decorar métodos que retornam objetos tool. Essas ferramentas podem ser usadas por agentes para executar tarefas específicas.
### 3. Definição de LLM
```python
@llm
def groq_llm(self):
api_key = os.getenv('api_key')
return ChatGroq(api_key=api_key, temperature=0, model_name="mixtral-8x7b-32768")
```
A anotação `@llm` é usada para decorar métodos que inicializam e retornam objetos Language Model. Esses LLMs são utilizados pelos agentes para tarefas de processamento de linguagem natural.
### 4. Definição de Agente
```python
@agent
def researcher(self) -> Agent:
return Agent(
config=self.agents_config['researcher']
)
```
A anotação `@agent` é usada para decorar métodos que definem e retornam objetos Agent.
### 5. Definição de Tarefa
```python
@task
def research_task(self) -> Task:
return Task(
config=self.tasks_config['research_linkedin_task'],
agent=self.researcher()
)
```
A anotação `@task` é usada para decorar métodos que definem e retornam objetos Task. Esses métodos especificam a configuração da tarefa e o agente responsável por ela.
### 6. Criação do Crew
```python
@crew
def crew(self) -> Crew:
"""Creates the LinkedinProfile crew"""
return Crew(
agents=self.agents,
tasks=self.tasks,
process=Process.sequential,
verbose=True
)
```
A anotação `@crew` é usada para decorar o método que cria e retorna o objeto `Crew`. Este método reúne todos os componentes (agentes e tarefas) em um crew funcional.
## Configuração YAML
As configurações dos agentes geralmente são armazenadas em um arquivo YAML. Veja um exemplo de como o arquivo `agents.yaml` pode ser estruturado para o agente researcher:
```yaml
researcher:
role: >
LinkedIn Profile Senior Data Researcher
goal: >
Uncover detailed LinkedIn profiles based on provided name {name} and domain {domain}
Generate a Dall-E image based on domain {domain}
backstory: >
You're a seasoned researcher with a knack for uncovering the most relevant LinkedIn profiles.
Known for your ability to navigate LinkedIn efficiently, you excel at gathering and presenting
professional information clearly and concisely.
allow_delegation: False
verbose: True
llm: groq_llm
tools:
- myLinkedInProfileTool
- mySerperDevTool
- myDallETool
```
Esta configuração YAML corresponde ao agente researcher definido na classe `LinkedinProfileCrew`. A configuração especifica o papel do agente, objetivo, contexto e outras propriedades, como o LLM e as tools que ele utiliza.
Repare como os campos `llm` e `tools` no arquivo YAML correspondem aos métodos decorados com `@llm` e `@tool` na classe Python.
## Boas Práticas
- **Nomenclatura Consistente**: Utilize nomenclatura clara e consistente para seus métodos. Por exemplo, métodos de agentes podem ser nomeados de acordo com suas funções (ex: researcher, reporting_analyst).
- **Variáveis de Ambiente**: Utilize variáveis de ambiente para informações sensíveis como chaves de API.
- **Flexibilidade**: Estruture seu crew de forma flexível, permitindo fácil adição ou remoção de agentes e tarefas.
- **Correspondência YAML-Código**: Assegure que os nomes e estruturas nos arquivos YAML correspondam corretamente aos métodos decorados em seu código Python.
Seguindo essas orientações e utilizando corretamente as anotações, você conseguirá criar crews bem estruturados e de fácil manutenção utilizando o framework CrewAI.