patterns

# Langroid Patterns

## Instructions

Below is an INDEX of design patterns organized by category. Each item describes
WHAT you might want to implement, followed by a REFERENCE to a document with
a complete code example.

Scan this index to find patterns matching your needs, then consult the
corresponding document.

---

## Agent & Task Basics

1. **Task Returns Tool Directly**

   Create a Langroid Agent equipped with a single Tool (a ToolMessage), and wrap
   it in a Task so that running the task returns that ToolMessage directly. Use
   this pattern when you want a simple LLM agent that returns a structured
   response.

   - Reference: `./task-return-tool.md`

---

## Tool Handlers

2. **Stateful Handler on Agent**

   Define a STATEFUL tool handler as a METHOD on the agent (not inside the
   ToolMessage). Use this pattern when: (a) the tool handler needs to execute
   external operations (API calls, database queries, file I/O), (b) you need to
   track state across retries (e.g., failure counter), (c) the handler needs
   access to agent-level resources (connections, configs), or (d) you want
   Langroid to automatically loop errors back to the LLM for self-correction.
   The method name must match the `request` field of the ToolMessage. Return a
   string for errors (LLM sees it and can retry), or DoneTool(content=result)
   to terminate successfully.

   - Reference: `./agent-tool-handler-with-state.md`

3. **Handler with Validation**

   Validate tool output against agent state before accepting it. Use this
   pattern when: (a) the LLM's tool output must preserve certain content from
   the input (e.g., placeholders, required fields), (b) you want automatic
   retry if validation fails, (c) you need to compare tool output against
   context the LLM received. Define a handler method on a custom agent class
   that stores the input context as state, validates the tool output, and
   returns an error string for retry or AgentDoneTool for success (note: use
   Ag