Agentes do Zero - Guia para Construção de Agentes de IA do Zero

Visão Geral do Projeto

Este repositório é um guia para construir agentes inteligentes (agents) do zero. Ele constrói gradualmente um agente "consciente do ambiente", capaz de gerenciar seus e-mails através da API do Gmail. O projeto foi desenvolvido pela equipe LangChain AI e é um excelente recurso para aprender e praticar o desenvolvimento de agentes de IA.

Estrutura do Projeto

Componentes Principais

O projeto é dividido em 4 partes principais, cada uma contendo um Jupyter notebook e a implementação de código correspondente:

1. Fundamentos do Agente - Construir funcionalidades básicas do agente
2. Avaliação do Agente - Implementar mecanismos de avaliação de desempenho do agente
3. Colaboração Humano-Máquina - Integrar intervenção humana e processos de revisão
4. Sistema de Memória - Adicionar memória de longo prazo e capacidade de aprendizado

Estrutura de Diretórios

• notebooks/ - Contém os Jupyter notebooks para fins de ensino
• src/email_assistant/ - Código de implementação principal do assistente de e-mail
• eval/ - Conjuntos de dados e ferramentas relacionados à avaliação
• tests/ - Suíte de testes automatizados

Requisitos Técnicos

Requisitos de Ambiente

• Versão do Python: 3.11 ou superior (para melhor compatibilidade com LangGraph)
• Dependências Principais: LangGraph, OpenAI API, LangSmith

Configuração de Chaves de API

É necessário configurar as seguintes chaves de API:

• Chave de API da OpenAI (para chamadas de modelo de linguagem)
• Chave de API da LangSmith (para rastreamento e avaliação)

Configuração do Ambiente

# Verificar a versão do Python
python3 --version

# Criar ambiente virtual
python3 -m venv .venv
source .venv/bin/activate

# Atualizar o pip
python3 -m pip install --upgrade pip

# Instalar o projeto (modo editável)
pip install -e .

Configuração de Variáveis de Ambiente

# Copiar o modelo de variáveis de ambiente
cp .env.example .env

No arquivo .env, configure:

LANGSMITH_API_KEY=sua_chave_langsmith_api
LANGSMITH_TRACING=true
LANGSMITH_PROJECT="interrupt-workshop"
OPENAI_API_KEY=sua_chave_openai_api

Módulos de Funcionalidade Detalhados

1. Introdução aos Fundamentos do LangGraph

• Arquivo: notebooks/langgraph_101.ipynb
• Conteúdo: Apresenta os conceitos básicos do LangGraph, incluindo modelos de chat, chamadas de ferramentas, a diferença entre agentes e fluxos de trabalho, nós/arestas/sistema de memória do LangGraph e o uso do LangGraph Studio

2. Construção do Assistente de E-mail

• Notebook: notebooks/agent.ipynb
• Código: src/email_assistant/email_assistant.py
• Funcionalidade:
  • Combina etapas de classificação de e-mail com o processamento de resposta do agente
  • Implementa um fluxo de trabalho completo de processamento de e-mail
  • Fornece funcionalidade de resposta automática de e-mail

3. Sistema de Avaliação do Agente

• Notebook: notebooks/evaluation.ipynb
• Conjunto de Dados: eval/email_dataset.py
• Funcionalidade:
  • Usa Pytest e LangSmith evaluate API para avaliação
  • Implementa LLM como mecanismo de avaliação
  • Avalia a precisão das chamadas de ferramentas e decisões de classificação

4. Colaboração Humano-Máquina (HITL)

• Notebook: notebooks/hitl.ipynb
• Código: src/email_assistant/email_assistant_hitl.py
• Funcionalidade:
  • Integra mecanismo de revisão humana
  • Suporta confirmação humana para chamadas de ferramentas específicas (como enviar e-mails, agendar reuniões)
  • Usa Agent Inbox como interface de interação humano-máquina

5. Sistema de Memória

• Código: src/email_assistant/email_assistant_hitl_memory.py
• Funcionalidade:
  • Aprende e se adapta ao feedback do usuário
  • Usa LangGraph Store para persistir a memória
  • Suporta configurações de preferências personalizadas

6. Integração com o Gmail

• Código: src/email_assistant/email_assistant_hitl_memory_gmail.py
• Funcionalidade:
  • Conexão real com a API do Gmail
  • Funcionalidade completa de gerenciamento de e-mail
  • Suporta implantação na LangGraph Platform

Sistema de Testes

Suíte de Testes Automatizados

O projeto inclui um sistema de testes automatizados completo para verificar a correção da implementação do assistente de e-mail:

# Executar testes de implementação padrão
python tests/run_all_tests.py

# Executar testes de implementação específica
python tests/run_all_tests.py --implementation email_assistant_hitl

# Executar testes de todas as implementações
python tests/run_all_tests.py --all

# Especificar o nome do experimento para rastreamento LangSmith
python tests/run_all_tests.py --experiment-name "Custom Test Run"

Versões de Implementação Testáveis

• email_assistant - Assistente de e-mail básico
• email_assistant_hitl - Versão de colaboração humano-máquina
• email_assistant_hitl_memory - Versão HITL com funcionalidade de memória
• email_assistant_hitl_memory_gmail - Versão de integração com o Gmail

Métricas de Avaliação

• Inspeção visual do rastreamento do agente
• Métricas de avaliação detalhadas
• Análise comparativa de diferentes implementações de agentes

Instruções de Implantação

Implantação na LangGraph Platform

O projeto suporta a implantação na LangGraph Platform, permitindo serviços de agentes em ambiente de produção.

Configuração da Ferramenta Gmail

É necessário configurar as credenciais da API do Google de acordo com as instruções em src/email_assistant/tools/gmail/README.md.

Sugestões de Roteiro de Aprendizagem

1. Iniciantes: Comece com o notebook LangGraph 101 para entender os conceitos básicos
2. Praticantes: Conclua os quatro notebooks principais em ordem, construindo gradualmente a funcionalidade completa
3. Desenvolvedores: Estude o código de implementação no diretório src para entender a prática de engenharia
4. Implantadores: Configure a API do Gmail e implante em um ambiente de produção

Características Técnicas

• Aprendizado Progressivo: Do básico ao avançado, passo a passo
• Aplicação Prática: Cenário real de processamento de e-mail
• Engenharia Completa: Inclui testes, avaliação e solução completa de implantação
• Escalabilidade: Os princípios podem ser aplicados a outras tarefas de agentes