Guia do pesquisador

Para quem é este guia

Pesquisadores de IA e desenvolvedores que querem explorar, reproduzir e estender experimentos no Agent-Lab. Se você escreve Python, usa Jupyter e pensa em termos de experimentos, agentes e pipelines, vai se sentir em casa. Familiaridade com LLMs, RAG e noções básicas de containers ajuda, mas não é obrigatória.

O Agent-Lab fornece componentes reutilizáveis (tipos de agentes, ferramentas, integrações) e uma coleção de notebooks Jupyter com exemplos passo a passo, para que você se torne produtivo rapidamente.

Início rápido — execute os exemplos

Requisitos: Python 3.12+, um ambiente Jupyter funcional (JupyterLab ou Notebook) e, opcionalmente, Docker local para integrações de ponta a ponta. Trabalhando em um clone do repositório:

uv sync --group notebooks   # runtime + notebook dependencies in one virtualenv
jupyter lab                 # from the repository root

Abra notebooks/ e comece pelo 01_…, avançando pelos que mais interessarem a você.

Observações:

• Os notebooks são, em sua maioria, autocontidos; o cabeçalho de cada um informa as variáveis de ambiente e os serviços externos necessários (chaves de API, endpoints).
• As chaves necessárias ficam em .env — copie .env.example e preencha-o (consulte a Referência de configuração).
• Para experimentar com o Agent-Lab a partir do seu próprio projeto em vez do repositório, execute pip install btech-agent-lab e monte a aplicação com create_app() — consulte Estendendo o framework no Guia do desenvolvedor.

Estrutura do projeto — visão geral rápida

• notebooks/ — exemplos interativos de tipos de agentes, avaliação e integrações. Comece aqui.
• agent_lab/ — o pacote do framework:
  • app_factory.py — a raiz de composição: create_app().
  • core/ — fontes de configuração, container de DI, resolução de extra_deps.
  • domain/ — modelos, interfaces de repositórios, exceções (o Modelo de domínio de entidades).
  • services/ — lógica de negócio e as implementações em agent_types/.
  • interface/ — api/ (routers HTTP) e mcp/ (o servidor MCP).
  • infrastructure/ — adaptadores de banco de dados, autenticação e métricas/tracing.
• tests/ — suítes unit/, integration/, template/ e simulation/ (consulte Testes e simulações).
• doc/ — a documentação que você está lendo.

Entender essas camadas mostra onde cada comportamento vive: exemplos em notebooks, contratos centrais em core/ e domain/, e adaptadores em infrastructure/.

Notebooks — o principal caminho de aprendizado

Progressão típica:

Cada notebook contém: uma breve descrição do objetivo do experimento, as variáveis de ambiente e os segredos necessários, funções auxiliares e saídas impressas/visuais para inspecionar as decisões e as métricas dos agentes.

Dica: execute os notebooks em ordem para uma curva de aprendizado incremental. Use datasets e amostras menores enquanto itera, para manter as execuções rápidas.

Conceitos centrais

• Agente — uma implementação registrada em agent_lab/services/agent_types/ (@discoverable_agent). O registro a resolve de forma lazy por meio do container de DI, injetando as extra_deps declaradas.
• Ferramentas — habilidades específicas que um agente pode chamar (busca, navegação, TTS/ASR), implementadas como adaptadores em agent_lab/infrastructure/ ou agent_lab/interface/.
• Container — o objeto de composição de DI (agent_lab/core/container.py); crie uma subclasse para adicionar providers aos seus experimentos.
• Repositórios — interfaces de acesso a dados em agent_lab/domain/repositories/.
• ConfigSource — de onde vem a configuração; use as fontes YAML em experimentos e o Vault em produção.

Quando quiser modificar um comportamento, decida se a mudança é experimental (apenas no notebook), arquitetural (core/domain/services) ou de integração (adaptador em infrastructure). Prefira mudanças pequenas e testáveis — e adicione ou atualize um notebook para mostrar o novo comportamento.

Executando experimentos e registrando resultados

Os notebooks imprimem os passos intermediários; para experimentos mais robustos:

• Use seeds determinísticas onde a aleatoriedade importa.

• Registre as métricas relevantes para a sua pergunta — latência, uso de tokens, número de chamadas de ferramentas, pontuações do juiz. A camada de observabilidade exporta tudo como OpenTelemetry (consulte Observabilidade); o harness de simulação registra as pontuações do juiz no Langfuse/LangWatch (consulte Testes e simulações).

• Para execuções repetíveis, exporte as células do notebook para scripts e execute-os no CI ou em nós de computação:

  jupyter nbconvert --to script notebooks/02_test_agent_type-adaptive_rag.ipynb

• O docker/app/Dockerfile gera uma imagem de runtime com versões fixadas para execução reproduzível.

Prototipando novos comportamentos

1. Adicione um novo tipo de agente: crie a classe em agent_lab/services/agent_types/, decore-a com @discoverable_agent("your_type") e adicione um notebook que a monte por meio do container de DI e a exercite com um pequeno cenário. O passo a passo completo está em Construindo workflows agênticos.
2. Troque o provedor de embeddings: implemente um adaptador compatível em agent_lab/infrastructure/ e valide-o com o notebook 01.
3. Adicione um armazenamento de recuperação ou banco vetorial: implemente os métodos do repositório em agent_lab/domain/repositories/ e um adaptador em agent_lab/infrastructure/database/; popule-o com um pequeno notebook de carga e demonstre a recuperação em um notebook de consulta.

Dica de design: mantenha as interfaces dos adaptadores enxutas e teste-as isoladamente com pequenos testes unitários.

Testes e avaliação

make test_unit           # unit tests — no infrastructure needed
make test                # unit + integration with coverage
make test_simulations    # LLM-as-judge agent simulations (live LLMs)

Quando você alterar um comportamento central, adicione um teste unitário e um notebook curto demonstrando a mudança — é essa combinação que torna a pesquisa reproduzível aqui. O harness completo, a configuração do juiz e as plataformas de avaliação são explicados em Testes e simulações.

Checklist de reprodutibilidade

• Fixe as versões do seu ambiente (uv + pyproject.toml / uv.lock).
• Registre as seeds e os arquivos de configuração (config-dev.yml, config-test.yml).
• Salve o checkpoint do notebook e quaisquer artefatos de saída (CSV/JSON) junto com o seu experimento.
• Anote os endpoints de tracing para os quais você exportou — os traces são o log do seu experimento.