LbAgents 0.18.2

LangGraph-based agent workflows for LHCb Analysis Productions

LbAgents

LangGraph-based agent workflows plugged into LbAPI.

This package contains pure agent logic — graph definitions, prompt templates, state schemas, tools, and a Pydantic workflow registry. It has no infrastructure dependencies (no database, no HTTP server, no Celery). MCP tools are discovered at runtime and passed to graph factories by the host application (LbAPI).

Architecture

graph LR
    subgraph LbAgents ["LbAgents (this package)"]
        Registry[Workflow Registry]
        Factories[Graph Factories]
        Schemas[State Schemas]
        Prompts[Prompt Templates]
        Tools[GitLab Tools]
    end

    subgraph LbAPI ["LbAPI (host)"]
        Router["/agent/* router"]
        Celery[Celery tasks]
        MCP[MCP tool discovery]
        LLM[KServe LLM clients]
        PG[AsyncPostgresSaver]
        LF[Langfuse observability]
    end

    Router -->|imports| Registry
    Celery -->|builds graph from| Factories
    MCP -->|passes tools to| Factories
    LLM -->|passes LLMs to| Factories
    PG -->|compiles with| Factories

Key design decisions

• Factory pattern: Graph factories return an uncompiled StateGraph. The caller (LbAPI) compiles it with a checkpointer.
• Tools as parameters: Factories accept a tools list — no hardcoded tool definitions. LbAPI discovers MCP tools at runtime and combines them with GitLab tools from this package.
• Self-registration: Importing LbAgents populates WORKFLOW_REGISTRY with all available workflows. Adding a new graph to this package makes it available in LbAPI with zero LbAPI code changes.
• Single LLM tier (current PoC): The current workflows use a single orchestrator LLM tier. The llms_required field on WorkflowSpec declares which tiers a workflow needs, allowing multi-tier setups in the future.

Workflows

Name	Description	Trigger	Delivery	Human Review
ap_debug_ci_failure	Diagnose CI pipeline failures and post review on GitLab MR	Internal (Celery dispatch)	GitLab MR review	Yes (before posting review)
ap_debug_stuck_productions (planned)	Diagnose a single stuck production, propose fixes	Internal (Celery dispatch), Manual	GitLab Issue, Mattermost	Yes
mattermost_debug_user_request (planned)	Answer user support questions via Mattermost bot	Mattermost webhook, Manual	Mattermost	Yes (admin verifies before posting)

ap_debug_ci_failure

Single ReAct loop using one LLM tier (orchestrator):

The agent investigates the failure using pipeline MCP tools (logs, validation reports, job info), reads the MR diff using GitLab tools, and posts a structured review — all in a single reasoning-and-acting loop.

The post_mr_review tool is a write operation — human approval is required before the review is posted.

ap_debug_stuck_productions

Diagnoses a single stuck production. A Celery scanning task identifies stuck samples and dispatches one instance of this graph per production. The graph follows the debug-production-job MCP skill workflow: gets sample details and progress → investigates MaxReset failures → classifies as known/new pattern → proposes fixes or GitLab issues. All write actions (adding known failures, creating issues) require human review before execution.

mattermost_debug_user_request

Called by an admin in a Mattermost channel thread (usually based on a user's support message). The agent investigates using available tools, drafts a response with advice/next steps, then always pauses for admin verification before the response is posted. The admin can approve, edit, or reject the draft.

Tools

GitLab tools (LbAgents.tools.gitlab)

Factory function make_gitlab_review_tools(gitlab_token, mr_iid) returns LangChain tools scoped to a specific merge request. The model cannot access other MRs — the IID is closed over in the factory.

• get_mr_info() — MR metadata (title, author, branches, labels)
• get_mr_diff() — File-level diffs for the MR
• get_mr_file_content(file_path) — Full file content from the source branch
• post_mr_review(body, inline_comments) — Post a review with optional inline comments

LbAPI provides the GitLab token and MR IID at graph invocation time.

Usage

from LbAgents import WORKFLOW_REGISTRY
from LbAgents.tools.gitlab import make_gitlab_review_tools

# All workflows are registered at import time
for name, spec in WORKFLOW_REGISTRY.items():
    print(f"{name}: {spec.description}")

# Build a graph with MCP tools + GitLab tools
from LbAgents.graphs import build_ap_debug_ci_failure_graph

gitlab_tools = make_gitlab_review_tools(gitlab_token="...", mr_iid=42)
all_tools = mcp_tools + gitlab_tools

graph = build_ap_debug_ci_failure_graph(
    orchestrator_llm=orchestrator,
    tools=all_tools,
    write_tool_names=["post_mr_review"],
)
compiled = graph.compile(checkpointer=my_checkpointer)

Adding a new workflow

1. Create a new module in src/LbAgents/graphs/ with a build_*_graph() factory function.
2. Add a state schema in src/LbAgents/schemas/state.py if needed.
3. Add a prompt template in src/LbAgents/prompts/templates.py.
4. Register the workflow in src/LbAgents/graphs/__init__.py via register_workflow().
5. Add tests in tests/test_graphs.py.

The workflow will automatically appear in LbAPI's GET /agent/workflows endpoint.

Development

pixi install
pixi run pytest        # Run tests
pixi run ruff check    # Lint
pixi run ruff format   # Format

Package structure

src/LbAgents/
├── __init__.py              # Re-exports registry, imports graphs to trigger registration
├── registry.py              # WorkflowSpec, WORKFLOW_REGISTRY, register_workflow()
├── schemas/
│   └── state.py             # TypedDict state definitions
├── prompts/
│   └── templates.py         # System prompts + ChatPromptTemplate instances
├── tools/
│   ├── __init__.py           # Tool factory exports
│   └── gitlab.py             # GitLab MR tools (get_mr_info, get_mr_diff, post_mr_review)
└── graphs/
    ├── __init__.py                        # Imports factories + calls register_workflow()
    ├── ap_debug_ci_failure.py             # Single ReAct loop: investigation + review posting
    ├── ap_debug_stuck_productions.py      # Stuck production triage + GitLab routing (planned)
    └── mattermost_debug_user_request.py   # Mattermost support bot with admin verification (planned)

License

GPL-3.0 — see COPYING.