Metadata-Version: 2.4
Name: btech-agent-lab
Version: 1.9.0
Summary: Cloud-native LLM Agent Development and Testing Toolkit
Project-URL: Homepage, https://github.com/btech-software/agent-lab
Project-URL: Repository, https://github.com/btech-software/agent-lab
Project-URL: Documentation, https://github.com/btech-software/agent-lab/tree/main/doc
Project-URL: Changelog, https://github.com/btech-software/agent-lab/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/btech-software/agent-lab/issues
Author-email: Bruno Sant'Anna <mail@bsantanna.me>
License-Expression: MIT
License-File: LICENSE
Keywords: agents,ai,fastapi,langchain,langgraph,llm,mcp,rag
Classifier: Development Status :: 5 - Production/Stable
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.12
Requires-Dist: browser-use
Requires-Dist: charset-normalizer~=3.4.7
Requires-Dist: ddgs~=9.14.4
Requires-Dist: dependency-injector~=4.48.3
Requires-Dist: fastapi-keycloak-middleware~=1.6.0
Requires-Dist: fastapi[standard]~=0.139.0
Requires-Dist: fastmcp~=3.4.4
Requires-Dist: hvac~=2.4.0
Requires-Dist: icalendar~=7.1.0
Requires-Dist: jinja2~=3.1.6
Requires-Dist: langchain-anthropic~=1.4.8
Requires-Dist: langchain-community~=0.4.1
Requires-Dist: langchain-core~=1.4.9
Requires-Dist: langchain-experimental~=0.4.1
Requires-Dist: langchain-openai~=1.2.1
Requires-Dist: langchain-postgres~=0.0.16
Requires-Dist: langchain-text-splitters~=1.1.2
Requires-Dist: langchain-xai~=1.2.2
Requires-Dist: langchain~=1.3.13
Requires-Dist: langgraph-checkpoint-postgres~=3.0.5
Requires-Dist: langgraph-prebuilt~=1.1.0
Requires-Dist: langgraph~=1.2.9
Requires-Dist: langwatch-scenario~=0.7.26
Requires-Dist: langwatch~=0.26.0
Requires-Dist: litellm~=1.84.0
Requires-Dist: markitdown[all]~=0.1.5
Requires-Dist: msal~=1.37.0
Requires-Dist: opentelemetry-api~=1.40.0
Requires-Dist: opentelemetry-exporter-otlp-proto-http~=1.40.0
Requires-Dist: opentelemetry-instrumentation-fastapi~=0.61b0
Requires-Dist: opentelemetry-instrumentation-httpx~=0.61b0
Requires-Dist: opentelemetry-instrumentation-langchain~=0.60.0
Requires-Dist: opentelemetry-instrumentation-psycopg2~=0.61b0
Requires-Dist: opentelemetry-instrumentation-psycopg~=0.61b0
Requires-Dist: opentelemetry-instrumentation-sqlalchemy~=0.61b0
Requires-Dist: opentelemetry-sdk~=1.40.0
Requires-Dist: psutil~=7.2.2
Requires-Dist: psycopg-binary~=3.3.4
Requires-Dist: psycopg-pool~=3.3.1
Requires-Dist: psycopg2-binary~=2.9.12
Requires-Dist: pydantic~=2.13.4
Requires-Dist: pyyaml~=6.0.3
Requires-Dist: redis~=8.0.1
Requires-Dist: requests~=2.33.1
Requires-Dist: slowapi~=0.1.9
Requires-Dist: sqlalchemy~=2.0.51
Requires-Dist: starlette~=1.3.1
Requires-Dist: typing-extensions~=4.16.0
Requires-Dist: uvicorn~=0.51.0
Description-Content-Type: text/markdown

<h2 align="center"><a href="https://github.com/btech-software/agent-lab">Agent-Lab | 🤖🧪</a></h2>
<h3 align="center">LLM Agent Development and Testing Toolkit</h3>

<div align="center">

[![PyPI version](https://img.shields.io/pypi/v/btech-agent-lab.svg)](https://pypi.org/project/btech-agent-lab/)
[![Continuous Integration](https://github.com/btech-software/agent-lab/actions/workflows/build.yml/badge.svg)](https://github.com/btech-software/agent-lab/actions/workflows/build.yml)
[![Quality Gate](https://sonarcloud.io/api/project_badges/measure?project=btech-software_agent-lab&metric=alert_status)](https://sonarcloud.io/dashboard?id=btech-software_agent-lab)
[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=btech-software_agent-lab&metric=coverage)](https://sonarcloud.io/component_measures?metric=coverage&selected=btech-software_agent-lab%3Aapp&id=btech-software_agent-lab)
[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![FastAPI](https://img.shields.io/badge/FastAPI-009485.svg?logo=fastapi&logoColor=white)](#key-features)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/btech-software/agent-lab/blob/main/LICENSE)

</div>

---

### Table of Contents
- [What is Agent-Lab?](#what-is-agent-lab)
- [Overview](#overview)
- [Project Principles](#project-principles)
- [Key Features](#key-features)
- [MCP Server](#mcp-server)
- [Getting Started](#getting-started)
- [Contributing](#contributing)
- [License](#license)

---

## What is Agent-Lab?

Agent-Lab is a cloud-native toolkit for building, testing, and deploying LLM-powered autonomous agents. Think of it as a platform where you wire up different AI agent types (RAG, browser automation, voice memos, vision, multi-agent supervisors) and interact with them via a REST API.

It features relational persistence with PostgreSQL, secure secrets management using Vault, observability through OpenTelemetry, and PgVector for vector storage and similarity search.

---

## Overview

**Tech stack:** Python 3.12, FastAPI, LangChain/LangGraph, PostgreSQL (3 databases: relational, vectors via pgvector, LangGraph checkpoints), Redis for pub/sub, Keycloak for auth, Docker Compose for orchestration.

**Architecture** — Clean Architecture with Dependency Injection:
- **Interface** — FastAPI routers + MCP server
- **Services** — Business logic, agent implementations
- **Domain** — SQLAlchemy models, repository interfaces
- **Infrastructure** — DB, auth, metrics (OpenTelemetry)

All wiring lives in `agent_lab/core/container.py` via `dependency-injector`.

**Agent system** — Agents extend `WorkflowAgentBase` (which uses LangGraph state graphs). Each agent type lives under `agent_lab/services/agent_types/` and is registered in a registry. The hierarchy goes from simple (echo, adaptive RAG) to complex (coordinator-planner-supervisor multi-agent). Agents process messages, have configurable settings (Jinja2-templated prompts), and persist state in the checkpoints database.

**Testing** — Two layers:
- **Integration tests** spin up real infrastructure via testcontainers (Postgres, Redis, Keycloak, Ollama as an OpenAI-compatible embeddings mock, headless Chrome).
- **Simulation tests** use `langwatch-scenario` with LLM judges to evaluate agent behavior end-to-end.

**Deployment** — Ships with Helm charts (`charts/`) for Kubernetes and Terraform scripts (`terraform/`) for provisioning cloud infrastructure including databases, auth realms, and secrets. See [Setup guide](https://github.com/btech-software/agent-lab/blob/main/doc/SETUP.md) for details.

---

## Project Principles

- Give researchers and developers everything they need to build, test, and experiment with LLM agents, with ready-to-use reference implementations.
- Expose an MCP server for agent discovery, conversation history, and agent-to-agent communication.
- Ship with integration and simulation test suites so every agent change is validated automatically.
- Provide full observability through logs, metrics, and traces for explainability and evaluation.
- Make it easy to create new custom agents by extending base classes and registering them in the agent registry.
- Run anywhere with a cloud-native architecture built for containerized deployment and horizontal scaling.

---

## Key Features

- **REST API**: Manage integrations with AI suppliers, LLMs settings, agents, and conversation histories with our [REST API](https://github.com/btech-software/agent-lab/blob/main/doc/REST_API.md).
- **MCP Server**: Utilize the [Model Control Protocol (MCP) server](https://github.com/btech-software/agent-lab/blob/main/doc/MCP.md) for agent discovery, dialog history, and agent-to-agent communication.
- **Observability**: Obtain detailed insights through logs, metrics, and traces powered by [OpenTelemetry](https://github.com/btech-software/agent-lab/blob/main/doc/OTEL.md).
  - Includes reference implementations for [Grafana](https://github.com/btech-software/agent-lab/blob/main/doc/otel/GRAFANA.md) and [OpenSearch Dashboards](https://github.com/btech-software/agent-lab/blob/main/doc/otel/OPENSEARCH.md).
- **Cloud-Native**: Optimized for cloud environments with Docker, Kubernetes, and [Terraform scripts](https://github.com/btech-software/agent-lab/blob/main/doc/SETUP.md) for streamlined deployment.
- **Relational Persistence**: Store data reliably using PostgreSQL to support the [entity domain model](https://github.com/btech-software/agent-lab/blob/main/doc/DOMAIN.md) for prompts, agent-specific settings, conversations, and more.
- **Secrets Management**: Securely store and retrieve secrets with [Vault](https://github.com/btech-software/agent-lab/blob/main/doc/VAULT.md).
- **Vector Storage and Search**: Efficiently manage vector data using PgVector for similarity search and retrieval.
- **Agent Memory**: Using PostgreSQL checkpointer to store and retrieve agent memory, enabling agents to maintain context across interactions.
- **Integration Testing**: Ensure reliability and correctness with a comprehensive [integration test suite](https://github.com/btech-software/agent-lab/blob/main/doc/TESTS.md).

---

## MCP Server

Agent-Lab features a MCP Server that allows agent discovery (`get_agent_list` tool), dialog history (`get_message_list` tool) and agent-to-agent communication (`post_message` tool).

The following example shows MCP Server discovering and obtaining dialog history of a [supervised coder agent](https://github.com/btech-software/agent-lab/blob/main/notebooks/05_test_agent_type-multiagent-coder.ipynb) instance:

<div align="center">

![Claude Desktop Demo](https://raw.githubusercontent.com/btech-software/agent-lab/main/doc/claude_demo.gif)

</div>

Please refer to [MCP guide](https://github.com/btech-software/agent-lab/blob/main/doc/MCP.md) for more details.


**Note**: Claude Desktop is used only for demonstration purposes. This project is not affiliated with Anthropic AI.

---

## Getting Started

Agent-Lab is designed for ease of setup and use, whether you're a developer building LLM agents or a researcher experimenting with agentic workflows.

Documentation in this repository is divided into two main sections:

- **Developer's Guide**: Tailored for developers who want to customize Agent-Lab or build agentic workflows. It includes setup instructions and development practices. Please refer to our [developer's guide](https://github.com/btech-software/agent-lab/blob/main/doc/DEV_GUIDE.md).
- **Researcher's Guide**: Provides detailed instructions for researchers on setting up and using Agent-Lab, including how to run the MCP server, manage agents, conduct experiments, tune prompts, and prototype new agents. Please refer to our [researcher's guide](https://github.com/btech-software/agent-lab/blob/main/doc/RESEARCHER_GUIDE.md).

Please consult these guides for detailed instructions on getting started with Agent-Lab.

---

## Contributing

Community support is greatly appreciated. If you encounter any issues or have suggestions for enhancements, please report them by creating an issue on our [GitHub Issues](https://github.com/btech-software/agent-lab/issues) page.

Refer to our [developer's guide](https://github.com/btech-software/agent-lab/blob/main/doc/DEV_GUIDE.md) for instructions on how to contribute to the project.

---

## License

This project is licensed under the MIT License. See the [LICENSE](https://github.com/btech-software/agent-lab/blob/main/LICENSE) file for details.
