Guia do Investigador

A quem se destina este guia

Investigadores de IA e programadores que pretendem explorar, reproduzir e alargar experiências no Agent-Lab. Quem escreve Python, utiliza Jupyter e pensa em termos de experiências, agentes e pipelines vai sentir-se em casa. Conhecer LLM, RAG e as bases de containers é útil, mas não obrigatório.

O Agent-Lab disponibiliza componentes reutilizáveis (tipos de agente, ferramentas, integrações) e uma coleção de notebooks Jupyter com exemplos passo a passo, para que seja possível ser produtivo rapidamente.

Início rápido — executar os exemplos

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

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

Abra notebooks/ e comece por 01_…, avançando pelos que forem do seu interesse.

Notas:

• Os notebooks são, na sua maioria, autónomos; o cabeçalho de cada um indica 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 Estender a framework no Guia do Programador.

Estrutura do projeto — visita rápida

• notebooks/ — exemplos interativos de tipos de agente, avaliação e integrações. Comece aqui.
• agent_lab/ — o pacote da 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 base de dados, autenticação, métricas/tracing.
• tests/ — suites unit/, integration/, template/ e simulation/ (consulte Testes e Simulações).
• doc/ — a documentação que está a ler.

Compreender estas camadas indica onde reside cada comportamento: exemplos em notebooks, contratos fundamentais em core/ e domain/, e adaptadores em infrastructure/.

Notebooks — o principal percurso de aprendizagem

Progressão típica:

Cada notebook contém: uma breve descrição do objetivo da experiência, as variáveis de ambiente e os segredos necessários, funções auxiliares e resultados impressos/visuais para inspecionar as decisões e as métricas do agente.

Dica: execute os notebooks por ordem para uma curva de aprendizagem progressiva. Utilize conjuntos de dados e amostras mais pequenos durante as iterações para manter as execuções rápidas.

Conceitos fundamentais

• Agent — uma implementação registada em agent_lab/services/agent_types/ (@discoverable_agent). O registo resolve-a de forma lazy através do container de DI, injetando as extra_deps declaradas.
• Tools — capacidades discretas que um agente pode chamar (pesquisa, 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 às suas experiências.
• Repositories — interfaces de acesso a dados em agent_lab/domain/repositories/.
• ConfigSource — a origem da configuração; utilize as fontes YAML nas experiências e o Vault em produção.

Quando pretender modificar um comportamento, determine se a alteração é: experimental (apenas no notebook), arquitetural (core/domain/services) ou ao nível da integração (adaptador em infrastructure). Privilegie alterações pequenas e testáveis — e adicione ou atualize um notebook que mostre o novo comportamento.

Executar experiências e registar resultados

Os notebooks imprimem os passos intermédios; para experiências mais robustas:

• Utilize seeds determinísticas sempre que a aleatoriedade for relevante.

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

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

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

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

Prototipar novos comportamentos

1. Adicionar 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 através do container de DI e a exercite com um pequeno cenário. O guia completo encontra-se em Construir workflows agênticos.
2. Trocar o fornecedor de embeddings: implemente um adaptador compatível em agent_lab/infrastructure/ e valide-o com o notebook 01.
3. Adicionar um repositório de recuperação ou uma base de dados vetorial: implemente métodos de repositório em agent_lab/domain/repositories/ e um adaptador em agent_lab/infrastructure/database/; carregue dados com um pequeno notebook de carregamento e demonstre a recuperação num notebook de consulta.

Dica de design: mantenha as interfaces dos adaptadores restritas 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 alterar o comportamento fundamental, adicione um teste unitário e um pequeno notebook que demonstre a alteração — é essa combinação que torna a investigação reprodutível neste projeto. O harness completo, a configuração do juiz e as plataformas de avaliação são descritos em Testes e Simulações.

Lista de verificação de reprodutibilidade

• Fixe o seu ambiente (uv + pyproject.toml / uv.lock).
• Registe as seeds e os ficheiros de configuração (config-dev.yml, config-test.yml).
• Guarde o checkpoint do notebook e quaisquer artefactos de saída (CSV/JSON) junto da sua experiência.
• Anote os endpoints de tracing para os quais exportou — os traces são o registo da sua experiência.