# Agente de Investigação Profunda de IA

> Um assistente de investigação profunda que planeia, pesquisa na web, escreve num sistema de ficheiros virtual e apresenta cada chamada de ferramenta como um cartão interativo num painel de trabalho. Construído com CopilotKit, Deep Agents, AG-UI e Tavily em cima de Next.js + LangGraph (Python).

- Fonte: https://doutorai.pt/apps/ai-deep-research-agent-generative-ui
- Categoria: Interfaces Generativas
- Dificuldade: Avançado
- Modelos: OpenAI
- Frameworks: LangChain
- Corre local?: Precisa de APIs cloud
- Chaves necessárias: OPENAI_API_KEY, TAVILY_API_KEY
- Licença: Apache-2.0
- Site: Doutor AI (https://doutorai.pt) - ferramentas de IA para pequenos negócios em português

## Tutorial completo

# AI Deep Research Agent

Um assistente de pesquisa profunda que planeia, pesquisa na web, escreve para um sistema de ficheiros virtual e renderiza cada chamada de ferramenta como um cartão ao vivo num painel de espaço de trabalho. Construído com [CopilotKit](https://github.com/CopilotKit/CopilotKit), [Deep Agents](https://docs.copilotkit.ai/integrations/langgraph/deep-agents), [AG-UI](https://github.com/ag-ui-protocol/ag-ui) e [Tavily](https://www.tavily.com/) em cima de Next.js + LangGraph (Python).

https://github.com/user-attachments/assets/68d5729f-91f9-4fd9-a579-cd1a8f4aad8d

**Conceito Gen UI - componentes renderizados por ferramentas com um espaço de trabalho em sidecar.** O Deep Agent emite quatro ferramentas - `write_todos`, `write_file`, `read_file` e `research` - e cada uma renderiza inline como um cartão de estado no chat enquanto atualiza um painel de espaço de trabalho paralelo (plano, ficheiros, resultados de ferramentas expansíveis). O estado local do React espelha o sistema de ficheiros do agente através de `useDefaultTool` em vez de `useCoAgent`, evitando um desajuste de tipos entre `Dict` em Python e `Array` em TypeScript.

## Pré-requisitos

- Node.js 18+
- Python 3.12+
- [Chave da API OpenAI](https://platform.openai.com/api-keys)
- [Chave da API Tavily](https://app.tavily.com/home)
- [uv](https://docs.astral.sh/uv/) (ou pip) para dependências de Python

## Começando

1. Instala as dependências do Node:

```bash
npm install
```

```markdown
## 2. Instala as dependências do Python para o agente:

```bash
pip install -r requirements.txt
```
```

```bash
cd agent
uv venv && source .venv/bin/activate
uv pip install -e .
cd ..
```

```markdown
# Instalação

Para instalar a biblioteca, podes usar o `pip`:

```bash
pip install nome-do-pacote
```

## Requisitos

Certifica-te de que tens as seguintes dependências instaladas:

- Python 3.6 ou superior
- pip

## Exemplo de Uso

Aqui está um exemplo simples de como usar a biblioteca:

```python
import nome_do_pacote

resultado = nome_do_pacote.funcao_exemplo()
print(resultado)
```

## Contribuição

Se desejas contribuir para este projeto, segue os passos abaixo:

1. Faz um fork do repositório.
2. Cria uma nova branch (`git checkout -b nova-funcionalidade`).
3. Faz as tuas alterações e commit (`git commit -m 'Adiciona nova funcionalidade'`).
4. Faz push para a branch (`git push origin nova-funcionalidade`).
5. Abre um Pull Request.

## Licença

Este projeto está licenciado sob a Licença MIT. Consulta o ficheiro [LICENSE](LICENSE) para mais informações.
```

```bash
cd agent
python -m venv .venv && source .venv/bin/activate
pip install -e .
cd ..
```

```markdown
3. Copia `.env.example` para `.env` tanto no diretório raiz como no diretório `agent/`, e depois preenche `OPENAI_API_KEY` e `TAVILY_API_KEY`.

4. Inicia o agente (terminal 1):
```

```bash
cd agent
uv run python main.py
```

```markdown
# 5. Iniciar o frontend (terminal 2):

Para iniciar o frontend, navega até ao diretório do frontend e executa o seguinte comando:

```bash
cd frontend
npm start
```

Isto irá iniciar o servidor de desenvolvimento e abrir a aplicação no teu navegador por defeito.
```

```bash
npm run dev
```

## Arquitetura

```
[User asks research question]
        ↓
Next.js Frontend (CopilotChat + Workspace)
        ↓
CopilotKit Runtime → LangGraphHttpAgent
        ↓
Python Backend (FastAPI + AG-UI)
        ↓
Deep Agent (research_assistant)
    ├── write_todos        (planning, built-in)
    ├── write_file         (filesystem, built-in)
    ├── read_file          (filesystem, built-in)
    └── research(query)
            └── internal Deep Agent [thread-isolated]
                    └── internet_search (Tavily)
```

## Variáveis de Ambiente

| Variável                   | Obrigatória | Padrão                 | Descrição                                         |
| -------------------------- | ----------- | ---------------------- | --------------------------------------------------- |
| `OPENAI_API_KEY`           | Sim         | -                      | [Obter chave da API](https://platform.openai.com/api-keys) |
| `TAVILY_API_KEY`           | Sim         | -                      | [Obter chave da API](https://app.tavily.com/home)          |
| `OPENAI_MODEL`             | Não         | `gpt-5.5`              | Modelo a utilizar (`gpt-5.5`)                            |
| `LANGGRAPH_DEPLOYMENT_URL` | Não         | `http://localhost:8123` | URL do backend                                         |
| `SERVER_HOST`              | Não         | `0.0.0.0`              | Host do backend                                        |
| `SERVER_PORT`              | Não         | `8123`                 | Porta do backend                                        |

## Saber mais

- [Documentação dos Deep Agents](https://docs.copilotkit.ai/integrations/langgraph/deep-agents)
- [Construir Frontends para Deep Agents](https://www.copilotkit.ai/blog/how-to-build-a-frontend-for-langchain-deep-agents-with-copilotkit)
- [Documentação do CopilotKit](https://docs.copilotkit.ai)
- [Documentação do Tavily](https://docs.tavily.com/welcome)

## Licença

Aplica-se a licença upstream - vê [`CopilotKit/CopilotKit`](https://github.com/CopilotKit/CopilotKit).

## Poupe horas todas as semanas com IA, sem complicações

O **Doutor AI** dá-lhe 1859 prompts de IA prontos a copiar, por indústria e em português simples - mais uma biblioteca técnica completa para quem quer ir mais longe. [Ver planos →](https://doutorai.pt/precos)

---
Conteúdo de Doutor AI (https://doutorai.pt). Ao citar, indique a fonte: https://doutorai.pt/apps/ai-deep-research-agent-generative-ui