Guia Rápido

Assista: Construindo Agents e Flows CrewAI com Coding Agent Skills

Instale nossas coding agent skills (Claude Code, Codex, …) para colocar seus agentes de código para funcionar rapidamente com o CrewAI.

Você pode instalar com npx skills add crewaiinc/skills

Neste guia você vai criar um Flow que define um tópico de pesquisa, executa um crew com um agente (um pesquisador com busca na web) e termina com um relatório em Markdown no disco. Flows são a forma recomendada de estruturar apps em produção: eles controlam estado e ordem de execução, enquanto os agentes fazem o trabalho dentro da etapa do crew.

Se ainda não instalou o CrewAI, siga primeiro o guia de instalação.

Pré-requisitos

• Ambiente Python e a CLI do CrewAI (veja instalação)
• Um LLM configurado com as chaves corretas — veja LLMs
• Uma chave de API do Serper.dev (SERPER_API_KEY) para busca na web neste tutorial

Construa seu primeiro Flow

1. Crie um projeto Flow

   No terminal, gere um projeto Flow (o nome da pasta usa sublinhados, ex.: latest_ai_flow):

   Code

   crewai create flow latest-ai-flow
   cd latest_ai_flow

   Isso cria um app Flow em src/latest_ai_flow/, incluindo um crew inicial em crews/content_crew/ que você substituirá por um crew de pesquisa com um único agente nos próximos passos.

2. Configure um agente em JSONC

   Crie src/latest_ai_flow/crews/content_crew/agents/researcher.jsonc (crie o diretório agents/ se necessário). Variáveis como {topic} são preenchidas a partir de crew.kickoff(inputs=...).

   {
     "role": "Pesquisador(a) Sênior de Dados em {topic}",
     "goal": "Descobrir os desenvolvimentos mais recentes em {topic}",
     "backstory": "Você é um pesquisador experiente que encontra as informações mais relevantes e apresenta tudo com clareza.",
     "tools": ["SerperDevTool"],
     "settings": {
       "verbose": true
     }
   }

3. Configure a crew em `crew.jsonc`

   Crie src/latest_ai_flow/crews/content_crew/crew.jsonc:

   {
     "name": "Research Crew",
     "agents": ["researcher"],
     "tasks": [
       {
         "name": "research_task",
         "description": "Faça uma pesquisa aprofundada sobre {topic}. Use busca na web para obter informações recentes e confiáveis.",
         "expected_output": "Um relatório em markdown com seções claras: tendências principais, ferramentas ou empresas relevantes e implicações. Entre 800 e 1200 palavras. Sem cercas de código em volta do documento inteiro.",
         "agent": "researcher",
         "output_file": "output/report.md",
         "markdown": true
       }
     ],
     "process": "sequential",
     "verbose": true
   }

4. Carregue a crew JSON (`content_crew.py`)

   Substitua o content_crew.py gerado por um pequeno loader que transforma crew.jsonc em uma Crew.

   src/latest_ai_flow/crews/content_crew/content_crew.py

   from pathlib import Path
   
   from crewai.project import load_crew
   
   
   def kickoff_content_crew(inputs: dict):
     crew, default_inputs = load_crew(Path(__file__).with_name("crew.jsonc"))
     return crew.kickoff(inputs={**default_inputs, **inputs})

5. Defina o Flow em `main.py`

   Conecte o crew a um Flow: um passo @start() define o tópico no estado e um @listen executa o crew. O output_file da tarefa continua gravando output/report.md.

   src/latest_ai_flow/main.py

   from pydantic import BaseModel
   
   from crewai.flow import Flow, listen, start
   
   from latest_ai_flow.crews.content_crew.content_crew import kickoff_content_crew
   
   
   class ResearchFlowState(BaseModel):
     topic: str = ""
     report: str = ""
   
   
   class LatestAiFlow(Flow[ResearchFlowState]):
     @start()
     def prepare_topic(self, crewai_trigger_payload: dict | None = None):
       if crewai_trigger_payload:
         self.state.topic = crewai_trigger_payload.get("topic", "AI Agents")
       else:
         self.state.topic = "AI Agents"
       print(f"Tópico: {self.state.topic}")
   
     @listen(prepare_topic)
     def run_research(self):
       result = kickoff_content_crew(inputs={"topic": self.state.topic})
       self.state.report = result.raw
       print("Crew de pesquisa concluído.")
   
     @listen(run_research)
     def summarize(self):
       print("Relatório em: output/report.md")
   
   
   def kickoff():
     LatestAiFlow().kickoff()
   
   
   def plot():
     LatestAiFlow().plot()
   
   
   if __name__ == "__main__":
     kickoff()

   Tip

   Se o nome do pacote não for latest_ai_flow, ajuste o import de kickoff_content_crew para o caminho de módulo do seu projeto.

6. Variáveis de ambiente

   Na raiz do projeto, no arquivo .env, defina:

   • SERPER_API_KEY — obtida em Serper.dev
   • As chaves do provedor de modelo conforme necessário — veja configuração de LLM
7. Instalar e executar
   Code

   crewai install
   crewai run

   O crewai run executa o ponto de entrada do Flow definido no projeto (o mesmo comando dos crews; o tipo do projeto é "flow" no pyproject.toml).

8. Confira o resultado

   Você deve ver logs do Flow e do crew. Abra output/report.md para o relatório gerado (trecho):

   Code

   # Agentes de IA: panorama e tendências recentes
   
   ## Resumo executivo
   …
   
   ## Principais tendências
   - **Uso de ferramentas e orquestração** — …
   - **Adoção empresarial** — …
   
   ## Implicações
   …

   O arquivo real será mais longo e refletirá resultados de busca ao vivo.

Como isso se encaixa

1. Flow — LatestAiFlow executa prepare_topic, depois run_research, depois summarize. O estado (topic, report) fica no Flow.
2. Crew — kickoff_content_crew carrega crew.jsonc e executa uma tarefa com um agente: o pesquisador usa Serper na web e escreve o relatório.
3. Artefato — O output_file da tarefa grava o relatório em output/report.md.

Para ir além em Flows (roteamento, persistência, human-in-the-loop), veja Construa seu primeiro Flow e Flows. Para crews sem Flow, veja Crews. Para um único Agent com kickoff() sem tarefas, veja Agents.

Você tem um Flow ponta a ponta com um crew de agente e um relatório salvo — uma base sólida para novas etapas, crews ou ferramentas.

Consistência de nomes

Os nomes em crew.jsonc devem coincidir com os arquivos e referências:

• agents: ["researcher"] carrega agents/researcher.jsonc
• tasks[].agent: "researcher" atribui a tarefa a esse agente

Implantação

Envie seu Flow para o CrewAI AMP quando rodar localmente e o projeto estiver em um repositório GitHub. Na raiz do projeto:

Code

crewai login

crewai deploy create

crewai deploy status
crewai deploy logs

crewai deploy push

crewai deploy list
crewai deploy remove <deployment_id>

Tip

A primeira implantação costuma levar cerca de 1 minuto. Pré-requisitos completos e fluxo na interface web estão em Implantar no AMP.

Guia de implantação

AMP passo a passo (CLI e painel).

Comunidade

Troque ideias, compartilhe projetos e conecte-se com outros desenvolvedores CrewAI.