Guia do Programador

Duas formas de desenvolver

O Agent-Lab é uma framework que se consome como biblioteca e é também um repositório no qual se pode trabalhar diretamente. Ambas as abordagens 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(). A framework é estendida através da sua API pública — subclasses, decorators e configuração — sem nunca editar o código da framework. Comece pelo Tutorial ou pelo Início rápido e, em seguida, leia Estender a framework. Para evitar o código repetitivo, gere um projeto consumidor pronto a usar com uvx cookiecutter gh:btech-software/agent-lab --directory cookiecutter (consulte cookiecutter/README.md).
• No repositório (para contribuidores 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 utilize os notebooks e os testes de integração. É assim que os agentes incluídos são desenvolvidos. Consulte Construir workflows agênticos.

Ambos os percursos utilizam os mesmos blocos de construção; a diferença está apenas em onde reside o seu código. Escolha o que melhor se adequa ao seu projeto.

Configuração inicial

Instalar

O Agent-Lab destina-se a Python 3.12+ e utiliza o uv para a gestão de dependências.

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

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

Trabalhar 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 está instalado e em execução — os testes de integração utilizam-no (através do testcontainers) e os ficheiros Docker Compose incluídos disponibilizam as dependências da aplicação.

Copiar o ficheiro de ambiente de exemplo

cp .env.example .env

Este ficheiro contém chaves de API de fornecedores de IA e os endpoints utilizados 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 regista todos os agentes incluídos — RAG, automação de browser, memorandos de voz, visão e supervisores multiagente. É simultaneamente um produto pronto para deployment e o exemplo canónico de como consumir a framework: não passa de uma chamada a create_app() sobre os pacotes de agentes incluídos.

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

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

Utilize-a como referência viva durante a construção da sua própria aplicação e como a forma mais rápida de experimentar o Agent-Lab de ponta a ponta. O aprovisionamento da respetiva infraestrutura (as três bases de dados PostgreSQL, Redis, Keycloak, Vault) em desenvolvimento ou produção é descrito no guia de deployment. A secção seguinte mostra como executá-la localmente.

Executar a aplicação

Iniciar a aplicação com Uvicorn

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

uvicorn agent_lab.main:app --reload

Aceda à documentação OpenAPI interativa em http://localhost:8000/docs.

Quando 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=[...])`

Iniciar a aplicação com Docker Compose

Dois ficheiros Docker Compose pré-configurados executam a aplicação de referência em conjunto 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 de a aplicação arrancar, a API fica disponível em http://localhost:18000/docs. Dashboards de observabilidade:

• Grafana: http://localhost:3000 (credenciais predefinidas: 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 utiliza o Dependency Injector para a injeção de dependências, o que mantém as responsabilidades separadas e facilita os testes.

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

Configuração da aplicação

A configuração é carregada através de uma ConfigSource (consulte agent_lab/core/config.py) e associada ao container de DI. A framework inclui três fontes YAML para desenvolvimento e testes, selecionadas automaticamente através de variáveis de ambiente:

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

Estes ficheiros definem parâmetros como as ligações às bases de dados e a autenticação, e destinam-se apenas a desenvolvimento e testes. Em produção, utilize o Vault através de VaultConfigSource (a predefinição quando não está definida nenhuma variável de ambiente). Para fornecer a configuração a partir de outro backend, implemente a sua própria ConfigSource e passe-a a 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 as respetivas relações utilizadas em toda a aplicação.

Registos e observabilidade

A aplicação utiliza o OpenTelemetry para registos e observabilidade; a configuração encontra-se em agent_lab/infrastructure/metrics/tracer.py. As chamadas FastAPI, HTTPX, LangChain, SQLAlchemy e OpenAI são instrumentadas de origem, com backends intercambiáveis para o Langfuse e o LangWatch. Consulte o guia de observabilidade para mais detalhes.

Testes

O projeto utiliza o pytest com foco em testes de integração (limiar de cobertura: 90%), suportados pelo Testcontainers, para que os testes sejam executados contra serviços reais em containers Docker. Uma suite de simulação separada avalia o comportamento dos agentes de ponta a ponta com um LLM-as-judge.

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

A primeira execução pode demorar vários minutos, uma vez que transfere imagens Docker e modelos de embeddings. Consulte o guia de testes para uma visão completa.

Inicializar o pre-commit

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

pre-commit install

Isto garante que o seu código segue as normas de programação do projeto antes de cada commit.

Construir workflows agênticos

O Agent-Lab assenta no LangGraph, que oferece uma forma poderosa de construir workflows agênticos com LLM. Construir um workflow é um processo simples graças à arquitetura modular e às classes base de agentes.

Definir uma nova implementação de Agent

O Agent é 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ões e interações com outros agentes ou sistemas externos.
• parâmetros de inicialização, como os prompts (templates Jinja2) e outras definições que personalizam o comportamento do agente (coleções do vector store, temperatura, etc.).

Segue-se um exemplo de parâmetros de inicialização persistidos para um agente que efetua transcrição e análise de voz, depois de o agente ser criado e guardado na base de dados:

É possível criar e refinar vários agentes suportados pela mesma implementação através da API REST.

Registar o agente com @discoverable_agent

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

• detetável pelo registo de agentes (agent_lab/services/agent_types/registry.py),
• resolúvel através do container de DI, que o instancia de forma lazy e injeta quaisquer extra_deps declaradas,
• válido na API, porque o esquema de criação de agentes valida agent_type face ao registo de forma dinâmica.

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
    ...

Nota (migração): as versões anteriores exigiam ligar manualmente cada agente em container.py, adicioná-lo a registry.py e estender o esquema Pydantic em agents/schema.py. Esses passos estão obsoletos — @discoverable_agent trata de todos eles. As extra_deps declaradas são resolvidas pelo nome a partir do container (eventualmente uma subclasse) no momento da instanciação.

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

Tornar o agente detetável

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

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

• Como biblioteca: passe o seu pacote a create_app(scan_packages=[*DEFAULT_SCAN_PACKAGES, "my_agents"]) — uma lista explícita substitui as predefinições (que é também a forma de excluir capacidades incluídas) — ou publique-o a partir de um pacote instalado através do 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"

Experimentar a implementação do agente

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

Interface REST API do agente

Depois de registar um agente, crie e gira instâncias do mesmo através da API REST — é possível executar várias instâncias configuradas da mesma implementação, cada uma com os seus próprios prompts e definições. Consulte a Referência da API REST para o catálogo de endpoints e exemplos de pedidos.

Testar o agente

• Os testes de integração (tests/integration/) validam o agente contra infraestrutura real com pytest e testcontainers.
• As simulações (tests/simulation/) avaliam o comportamento de ponta a ponta com um LLM-as-judge. Consulte o guia de testes.

Servidor MCP

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

Estender a framework

Ao consumir o Agent-Lab como biblioteca, a aplicação é moldada inteiramente através de create_app() e da API pública exportada pelo pacote de topo agent_lab — nunca através da edição do código da 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 apresentado acima é exportado a partir de agent_lab (consulte agent_lab/__init__.py); a lista completa de chaves de configuração consumidas por estes parâmetros encontra-se na Referência de configuração.

Contribuir

O apoio da comunidade é muito apreciado. Se encontrar algum problema ou tiver sugestões de melhoria, comunique-os criando uma issue na nossa página de GitHub Issues.

Para contribuir para o projeto, siga estes passos:

1. Faça um fork do repositório.
2. Crie um novo branch para a sua funcionalidade ou correção.
3. Ative os hooks de pre-commit executando pre-commit install, faça as suas alterações e efetue o commit com mensagens claras e concisas.
4. Certifique-se de que as suas alterações passam nos hooks de pre-commit e no limiar de cobertura de 90% (make test).
5. Faça push das alterações para o seu fork do repositório.
6. Crie um Pull Request (PR) para o branch main do repositório original.

Iremos rever o seu PR e dar feedback. Obrigado pelas vossas contribuições e pelo vosso apoio!

Deployment em produção

Consulte o guia de deployment para fazer o deployment da aplicação de referência em produção com os Helm charts e os scripts Terraform incluídos.