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