Guia do desenvolvedor

Duas formas de desenvolver

O Agent-Lab é um framework que você consome como biblioteca e também um repositório no qual você pode trabalhar diretamente. As duas formas são suportadas:

• Como biblioteca (recomendado para produtos). Adicione btech-agent-lab ao seu próprio projeto, defina agentes estendendo as classes base e monte a aplicação com create_app(). Você estende o framework pela sua API pública — subclasses, decorators e configuração — e nunca edita o código do framework. Comece pelo Tutorial ou pelo Quickstart e depois leia Estendendo o framework. Para pular o boilerplate, gere um projeto consumidor pronto com uvx cookiecutter gh:btech-software/agent-lab --directory cookiecutter (consulte cookiecutter/README.md).
• No repositório (para colaboradores e para a implementação de referência). Clone o repositório e adicione agentes em agent_lab/services/agent_types/, execute a aplicação de referência incluída e use os notebooks e os testes de integração. É assim que os agentes nativos são desenvolvidos. Consulte Construindo workflows agênticos.

Os dois caminhos usam os mesmos blocos de construção; a diferença está apenas em onde o seu código fica. Escolha o que melhor se adapta ao seu projeto.

Configuração inicial

Instalação

O Agent-Lab é voltado para Python 3.12+ e usa o uv para o gerenciamento de dependências.

Consumindo o Agent-Lab como biblioteca — instale-o no seu próprio projeto:

pip install btech-agent-lab
# or
uv add btech-agent-lab

Trabalhando no repositório — clone-o e sincronize o ambiente:

git clone https://github.com/btech-software/agent-lab.git
cd agent-lab
uv sync                 # runtime dependencies
uv sync --group test    # add the test/simulation dependencies

Certifique-se de que o Docker ou outro runtime de containers esteja instalado e em execução — os testes de integração o utilizam (via testcontainers) e os arquivos Docker Compose incluídos fornecem as dependências da aplicação.

Copie o arquivo de ambiente de exemplo

cp .env.example .env

Esse arquivo contém as chaves de API dos fornecedores de IA e os endpoints usados pelas simulações de agentes. Todas as variáveis estão documentadas na Referência de configuração.

Implementação de referência

O repositório inclui uma aplicação de referência completa (agent_lab.main) que registra todos os agentes nativos — RAG, automação de navegador, memos de voz, visão e supervisores multiagente. Ela é ao mesmo tempo um produto implantável e o exemplo canônico de como consumir o framework: não passa de uma chamada a create_app() sobre os pacotes de agentes nativos.

# agent_lab/main.py
from agent_lab.app_factory import create_app

app = create_app()  # scans DEFAULT_SCAN_PACKAGES: all built-in capabilities

Use-a como referência viva enquanto constrói sua própria aplicação e como a forma mais rápida de experimentar o Agent-Lab de ponta a ponta. O provisionamento da sua infraestrutura (os três bancos de dados PostgreSQL, Redis, Keycloak, Vault) em desenvolvimento ou produção é explicado no guia de implantação. A próxima seção mostra como executá-la localmente.

Executando a aplicação

Inicie a aplicação com Uvicorn

Para desenvolvimento e depuração com uma IDE, execute a aplicação de referência diretamente:

uvicorn agent_lab.main:app --reload

Acesse a documentação interativa do OpenAPI em http://localhost:8000/docs.

Quando você consome o Agent-Lab como biblioteca, executa a sua aplicação da mesma forma — aponte o uvicorn para o módulo que chama create_app():

uvicorn app:app --reload    # where app.py defines `app = create_app(scan_packages=[...])`

Inicie a aplicação com Docker Compose

Dois arquivos Docker Compose pré-configurados executam a aplicação de referência junto com uma stack de observabilidade:

• compose-grafana.yml: a aplicação mais Grafana, Prometheus, Tempo e Loki.
• compose-opensearch.yml: a aplicação mais OpenSearch Dashboards.

docker compose -f compose-grafana.yml up --build       # Grafana stack
docker compose -f compose-opensearch.yml up --build    # OpenSearch Dashboards stack

Depois que a aplicação iniciar, a API estará disponível em http://localhost:18000/docs. Dashboards de observabilidade:

• Grafana: http://localhost:3000 (credenciais padrão: admin/admin). Consulte o exemplo com Grafana.
• OpenSearch Dashboards: http://localhost:5601. Consulte o exemplo com OpenSearch.

Práticas de desenvolvimento

Injeção de dependências

A aplicação usa o Dependency Injector para injeção de dependências, o que mantém as responsabilidades separadas e facilita os testes.

O container é definido em agent_lab/core/container.py. Ao consumir o Agent-Lab como biblioteca, crie uma subclasse de Container para adicionar seus próprios providers e passe a instância para create_app(container=...). Ao trabalhar no repositório, registre serviços adicionais do framework diretamente no container.

Configuração da aplicação

A configuração é carregada por meio de um ConfigSource (consulte agent_lab/core/config.py) e vinculada ao container de DI. O framework inclui três fontes YAML para desenvolvimento e testes, selecionadas automaticamente por variável de ambiente:

• config-dev.yml: ambiente de desenvolvimento, ativado quando DEVELOPING está definida — destinado à depuração na IDE.
• config-test.yml: ambiente de testes, ativado quando TESTING está definida — usado pela configuração dos testes de integração.
• config-docker.yml: ambiente Docker Compose, ativado quando DOCKER está definida.

Esses arquivos definem configurações como conexões de banco de dados e autenticação, e são destinados apenas a desenvolvimento e testes. Em produção, use o Vault via VaultConfigSource (o padrão quando nenhuma flag de ambiente está definida). Para fornecer a configuração a partir de outro backend, implemente seu próprio ConfigSource e passe-o para create_app(config_source=...). Todas as chaves de configuração e variáveis de ambiente estão documentadas na Referência de configuração.

Modelo de domínio de entidades

Consulte o Modelo de domínio de entidades para conhecer o modelo de dados — as entidades e os relacionamentos usados em toda a aplicação.

Logging e observabilidade

A aplicação usa o OpenTelemetry para logging e observabilidade; a configuração fica em agent_lab/infrastructure/metrics/tracer.py. As chamadas de FastAPI, HTTPX, LangChain, SQLAlchemy e OpenAI são instrumentadas por padrão, com backends plugáveis para Langfuse e LangWatch. Consulte o guia de observabilidade para mais detalhes.

Testes

O projeto usa pytest com foco em testes de integração (exigência de cobertura: 90%), apoiado pelo Testcontainers para que os testes rodem contra serviços reais em containers Docker. Uma suíte de simulação separada avalia o comportamento dos agentes de ponta a ponta com um LLM como juiz.

make test               # unit + integration with coverage
make test_simulations   # end-to-end agent simulations (calls live LLMs)

A primeira execução pode levar vários minutos, pois baixa imagens Docker e modelos de embeddings. Consulte o guia de testes para o panorama completo.

Inicialize o pre-commit

Se você pretende contribuir com o código ou construir novos agentes sobre o Agent-Lab, instale os hooks de pre-commit:

pre-commit install

Isso garante que seu código siga os padrões de código do projeto antes de cada commit.

Construindo workflows agênticos

O Agent-Lab é construído sobre o LangGraph, que oferece uma forma poderosa de construir workflows agênticos usando LLMs. Construir um é um processo simples graças à arquitetura modular e às classes base de agentes.

Defina uma nova implementação de agente

Agente é um conceito central no Agent-Lab e representa uma entidade autônoma capaz de executar tarefas, tomar decisões e interagir com outros agentes ou sistemas externos. Um agente é uma implementação concreta de uma das classes base:

Uma classe que estende WorkflowAgentBase define:

• um workflow que representa o comportamento do agente — tarefas, tomada de decisão e interações com outros agentes ou sistemas externos.
• parâmetros de inicialização, como os prompts (templates Jinja2) e outras configurações que personalizam o comportamento do agente (coleções do vector store, temperatura etc.).

Veja um exemplo de parâmetros de inicialização persistidos para um agente que faz transcrição e análise de voz, depois que o agente é criado e armazenado no banco de dados:

Vários agentes baseados na mesma implementação podem ser criados e refinados pela API REST.

Registre o agente com @discoverable_agent

Decore sua subclasse de AgentBase com @discoverable_agent("<agent_type>"). Esse único decorator é todo o registro de que um agente precisa — ele torna o agente:

• detectável pelo registro de agentes (agent_lab/services/agent_types/registry.py),
• resolvível por meio do container de DI, que o instancia de forma lazy e injeta as extra_deps declaradas,
• válido na API, porque o schema de criação de agentes valida agent_type contra o registro dinamicamente.

from agent_lab import AgentBase, AgentUtils, discoverable_agent


@discoverable_agent("my_agent", extra_deps=("my_service",))
class MyAgent(AgentBase):
    def __init__(self, agent_utils: AgentUtils, my_service):
        super().__init__(agent_utils)
        self.my_service = my_service
    ...

Observação (migração): versões anteriores exigiam conectar manualmente cada agente em container.py, adicioná-lo a registry.py e estender o schema Pydantic em agents/schema.py. Esses passos estão obsoletos — @discoverable_agent cuida de todos eles. Todas as extra_deps que você declarar são resolvidas por nome a partir do container (possivelmente uma subclasse) no momento da instanciação.

Se um agente precisar de colaboradores além de AgentUtils, exponha-os como providers no container (crie uma subclasse de Container ao consumir a biblioteca) e informe seus nomes em extra_deps.

Torne o agente detectável

O framework só importa os módulos de agentes que lhe são informados, para que o decorator seja executado:

• No repositório: coloque o agente em agent_lab/services/agent_types/ — a aplicação de referência varre esse pacote como parte de DEFAULT_SCAN_PACKAGES (create_app()).

• Como biblioteca: passe seu pacote para create_app(scan_packages=[*DEFAULT_SCAN_PACKAGES, "my_agents"]) — uma lista explícita substitui os padrões (que também é a forma de excluir recursos nativos) — ou publique-o a partir de um pacote instalado pelo grupo de entry points agent_lab.agents, para que os consumidores o carreguem automaticamente:

  # pyproject.toml of the package that ships the agents
  [project.entry-points."agent_lab.agents"]
  my_agents = "my_agents"

Experimentando com a implementação do agente

Consulte os notebooks para ver exemplos de como testar um agente de forma interativa com Jupyter, usando o mesmo mecanismo de injeção de dependências. É uma forma prática de prototipar e validar comportamentos em um ambiente controlado — consulte o Guia do pesquisador.

Interface de agentes da API REST

Depois que um agente é registrado, crie e gerencie instâncias dele pela API REST — você pode executar várias instâncias configuradas da mesma implementação, cada uma com seus próprios prompts e configurações. Consulte a Referência da API REST para ver o catálogo de endpoints e exemplos de requisição.

Testando o agente

• Testes de integração (tests/integration/) validam o agente contra infraestrutura real com pytest e testcontainers.
• Simulações (tests/simulation/) avaliam o comportamento de ponta a ponta com um LLM como juiz. Consulte o guia de testes.

Servidor MCP

Consulte o Guia do servidor MCP para expor seus agentes (e ferramentas extras) a clientes MCP como o Claude Desktop, permitindo descoberta de agentes, histórico de diálogos e comunicação entre agentes.

Estendendo o framework

Ao consumir o Agent-Lab como biblioteca, você molda a aplicação inteiramente por meio de create_app() e da API pública exportada pelo pacote de nível superior agent_lab — nunca editando o código do framework:

from agent_lab import (
    DEFAULT_SCAN_PACKAGES,
    Container,
    RouterMount,
    YamlConfigSource,
    create_app,
)

class MyContainer(Container):
    my_service = ...  # providers.Factory(MyService, ...)

app = create_app(
    container=MyContainer(),
    scan_packages=[*DEFAULT_SCAN_PACKAGES, "my_agents"],
    config_source=YamlConfigSource("config.yml"),
    extra_routers=[RouterMount(my_router, "/custom", ["custom"])],
    mcp_instructions=["Extra guidance for MCP clients."],
)

Tudo o que foi mostrado acima é exportado por agent_lab (consulte agent_lab/__init__.py); a lista completa de chaves de configuração consumidas por esses ajustes está na Referência de configuração.

Como contribuir

O apoio da comunidade é muito bem-vindo. Se você encontrar algum problema ou tiver sugestões de melhorias, informe-os criando uma issue na nossa página de GitHub Issues.

Para contribuir com o projeto, siga estes passos:

1. Faça um fork do repositório.
2. Crie uma nova branch para sua feature ou correção de bug.
3. Ative os hooks de pre-commit executando pre-commit install, faça suas alterações e faça commit delas com mensagens claras e concisas.
4. Garanta que suas alterações passem pelos hooks de pre-commit e pela exigência de 90% de cobertura (make test).
5. Faça push das suas alterações para o seu fork do repositório.
6. Crie um Pull Request (PR) para a branch main do repositório original.

Vamos revisar seu PR e dar feedback. Obrigado pelas suas contribuições e pelo seu apoio!

Implantação em produção

Consulte o guia de implantação para implantar a aplicação de referência em produção usando os Helm charts e os scripts Terraform incluídos.