O Seu Primeiro Agente

O que vai construir

Uma aplicação Agent-Lab completa e executável: um serviço FastAPI que aloja um agente de eco, um servidor MCP, persistência em PostgreSQL e instrumentação OpenTelemetry — tudo gerado por um único comando, sem nada ligado manualmente. Pelo caminho, vai criar uma instância de agente por REST, enviar-lhe uma mensagem e acompanhar os traces da framework.

Pré-requisitos

• Python 3.12+ e uv (pip install uv)
• Docker (ou outro runtime de containers), em execução

Este tutorial não necessita de chaves de API — o agente de eco não chama nenhum LLM. Os agentes baseados em LLM vêm a seguir (consulte O que se segue?).

1. Gerar a estrutura do projeto

uvx cookiecutter gh:btech-software/agent-lab --directory cookiecutter

Responda às perguntas — os valores predefinidos geram um projeto chamado My Agent App:

cd my-agent-app

O scaffold é um consumidor leve da framework, e não um fork. btech-agent-lab é uma dependência normal em pyproject.toml; o seu código fica ao lado dela e estende-a através da API pública.

2. Perceber o que foi gerado

my-agent-app/
├── my_agent_app/
│   ├── main.py              # the composition root — one create_app() call
│   ├── core/container.py    # your DI container — add providers here
│   ├── agents/echo/agent.py # your first agent (echo)
│   └── mcp/tools.py         # your first MCP tool
├── config-dev.yml / config-test.yml / config-docker.yml
├── tests/                   # unit tests (no infra) + optional testcontainers suite
├── compose.yml              # app + postgres (pgvector) + redis + vault
└── Makefile, docker/, .github/, pyproject.toml

Abra my_agent_app/main.py — esta é a aplicação inteira:

from agent_lab import create_app

from my_agent_app.core.container import Container

# An explicit scan_packages list replaces agent_lab's DEFAULT_SCAN_PACKAGES:
# only this project's agents, MCP tools, and prompts are discovered — none of
# the framework's built-in examples. Add "agent_lab.services.agent_types" or
# "agent_lab.interface.mcp" here if you want the built-ins back.
app = create_app(
    container=Container(),
    scan_packages=[
        "my_agent_app.agents",
        "my_agent_app.mcp",
    ],
)

E my_agent_app/agents/echo/agent.py — o próprio agente:

from langchain_core.messages import AIMessage
from langgraph.graph import MessagesState

from agent_lab import AgentBase, AgentUtils, discoverable_agent
from agent_lab.interface.api.messages.schema import Message, MessageRequest
from agent_lab.services.tasks import TaskProgress


@discoverable_agent("my_agent_app_echo")
class EchoAgent(AgentBase):
    """Minimal agent: echoes the incoming message without calling an LLM."""

    def __init__(self, agent_utils: AgentUtils):
        super().__init__(agent_utils)

    def create_default_settings(self, agent_id: str, schema: str):
        pass

    def get_input_params(self, message_request: MessageRequest, schema: str) -> dict:
        return message_request.model_dump()

    def process_message(self, message_request: MessageRequest, schema: str) -> Message:
        message_content, response_data = self.format_response(
            MessagesState(
                messages=[AIMessage(content=f"Echo: {message_request.message_content}")]
            )
        )

        self.task_notification_service.publish_update(
            task_progress=TaskProgress(
                agent_id=message_request.agent_id,
                status="completed",
                message_content=message_content,
                response_data=response_data,
            )
        )

        return Message(
            message_role="assistant",
            message_content=message_content,
            response_data=response_data,
            agent_id=message_request.agent_id,
        )

Dois aspetos a reter:

• @discoverable_agent("my_agent_app_echo") — esse único decorator regista a classe com um agent_type. Sem edições ao registo nem alterações ao esquema: a API REST valida agent_type face ao registo de forma dinâmica.
• AgentUtils é injetado através do construtor pelo container de DI. Declare mais dependências com extra_deps=("my_provider",) e adicione os providers correspondentes a core/container.py (consulte o Guia do Programador).

3. Testar antes de executar

Os testes unitários do scaffold arrancam a aplicação completa sem qualquer infraestrutura:

uv lock && uv sync --group dev --group test
make test_unit

Também está incluída a variante de integração — make test_integration inicia containers reais de Postgres, Redis e Vault através do testcontainers (requer Docker).

4. Executar a aplicação

docker compose up --build -d
curl http://localhost:18000/status/liveness

A stack é composta pela aplicação (porta 18000), PostgreSQL com pgvector (três bases de dados: relacional, vetores e checkpoints do LangGraph), Redis para atualizações de estado pub/sub e Vault para segredos. A documentação OpenAPI interativa está disponível em http://localhost:18000/docs.

A autenticação está desativada no scaffold (auth.enabled: false). Quando for ativada, cada pedido necessita de um bearer token — consulte Autenticação com Keycloak.

5. Conversar com o agente por REST

Os agentes são instâncias de uma implementação, criadas e configuradas através da API. Crie uma:

curl -s -X POST http://localhost:18000/agents/create \
  -H "Content-Type: application/json" \
  -d '{"agent_name": "my-first-agent", "agent_type": "my_agent_app_echo"}' | jq

Copie o id da resposta e, em seguida, envie-lhe uma mensagem:

curl -s -X POST http://localhost:18000/messages/post \
  -H "Content-Type: application/json" \
  -d '{
        "agent_id": "<agent_id>",
        "message_role": "human",
        "message_content": "Hello, framework!"
      }' | jq

A resposta é devolvida de forma síncrona:

{
  "message_role": "assistant",
  "message_content": "Echo: Hello, framework!",
  "agent_id": "<agent_id>",
  "id": "…"
}

Esta ida e volta exercitou toda a stack: pedido REST → consulta ao registo → container de DI → o seu agente → persistência da mensagem (a resposta também é guardada — verifique com POST /messages/list). O catálogo completo encontra-se na Referência da API REST.

6. Acompanhar o trace

A observabilidade do Agent-Lab é simplesmente OpenTelemetry. Quando a variável de ambiente OTEL_EXPORTER_OTLP_ENDPOINT está definida, a aplicação exporta traces/métricas/registos OTLP; quando não está definida, o tracing fica simplesmente desativado — sem alterações ao código em nenhum dos casos.

Execute a stack Grafana incluída na framework (a partir do repositório da framework) e aponte a sua aplicação para o respetivo collector:

# In the agent-lab framework repo — collector on :4318, Grafana UI on :3000
docker compose -f compose-grafana.yml up --build

# Back in your project — restart the app with the endpoint set
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 docker compose up --build -d

Envie outra mensagem e, em seguida, abra o Grafana em http://localhost:3000 (admin/admin) e explore o dashboard Agent-Lab: o span HTTP, as consultas SQL e — no caso de agentes baseados em LLM — cada chamada ao modelo com a contagem de tokens. Prefere uma plataforma de observabilidade de LLM alojada? Defina antes LANGFUSE_HOST/LANGFUSE_PUBLIC_KEY/LANGFUSE_SECRET_KEY (ou LANGWATCH_ENDPOINT/ LANGWATCH_API_KEY) — detalhes no guia de observabilidade.

7. Encontrá-lo num cliente MCP

O scaffold já inclui uma ferramenta MCP (my_agent_app/mcp/tools.py) exposta em /mcp, juntamente com as ferramentas da framework para descoberta de agentes, histórico e mensagens. Experimente com o MCP Inspector:

npx @modelcontextprotocol/inspector

Ligue-se a http://localhost:18000/mcp (Streamable HTTP), liste as ferramentas e chame my_agent_app_hello_tool. O mesmo servidor funciona com o Claude Desktop e com qualquer cliente MCP — consulte o Guia do servidor MCP.

O que se segue?