> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crewai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Guia Rápido

> Crie seu primeiro Flow CrewAI em minutos — orquestração, estado e um crew com um agente que gera um relatório real.

### 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`

[https://www.loom.com/embed/befb9f68b81f42ad8112bfdd95a780af](https://www.loom.com/embed/befb9f68b81f42ad8112bfdd95a780af)

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](https://docs.crewai.com/pt-BR/installation.md).

## Pré-requisitos

* Ambiente Python e a CLI do CrewAI (veja [instalação](https://docs.crewai.com/pt-BR/installation.md))
* Um LLM configurado com as chaves corretas — veja [LLMs](https://docs.crewai.com/pt-BR/concepts/llms.md#setting-up-your-llm)
* Uma chave de API do [Serper.dev](https://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`):

```shell Terminal theme={null}
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=...)`.

```jsonc agents/researcher.jsonc theme={null}
{
  "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`:

```jsonc crew.jsonc theme={null}
{
  "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`.

```python content_crew.py theme={null}
# 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`.

```python main.py theme={null}
# 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](https://serper.dev/)
* As chaves do provedor de modelo conforme necessário — veja [configuração de LLM](https://docs.crewai.com/pt-BR/concepts/llms.md#setting-up-your-llm)

**7. Instalar e executar**

```shell Terminal theme={null}
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):

```markdown output/report.md theme={null}
# 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](https://docs.crewai.com/pt-BR/guides/flows/first-flow.md) e [Flows](https://docs.crewai.com/pt-BR/concepts/flows.md). Para crews sem Flow, veja [Crews](https://docs.crewai.com/pt-BR/concepts/crews.md). Para um único `Agent` com `kickoff()` sem tarefas, veja [Agents](https://docs.crewai.com/pt-BR/concepts/agents.md#direct-agent-interaction-with-kickoff).

> [!TIP]
>
> 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](https://app.crewai.com)** quando ele rodar localmente. Se o projeto tiver um `origin` git, o AMP implanta a partir desse repositório (no **GitHub**, a integração do AMP com o GitHub precisa ter acesso a ele); sem `origin`, `crewai deploy create` envia o projeto como um ZIP. Na raiz do projeto:

```bash Autenticar theme={null}
crewai login
```

```bash Criar implantação theme={null}
crewai deploy create
```

```bash Status e logs theme={null}
crewai deploy status
crewai deploy logs
```

```bash Enviar atualizações após mudanças no código theme={null}
crewai deploy push
```

```bash Listar ou remover implantações theme={null}
crewai deploy list
crewai deploy remove -u <deployment_uuid>
```

> [!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](https://docs-platform.crewai.com/platform/pt-BR/guides/deploy-to-amp).

> **[Guia de implantação](https://docs-platform.crewai.com/platform/pt-BR/guides/deploy-to-amp)**
>
> AMP passo a passo (CLI e painel).

> **[Comunidade](https://community.crewai.com)**
>
> Troque ideias, compartilhe projetos e conecte-se com outros desenvolvedores CrewAI.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.