LLM Agents

Implements an iterative reasoning loop where the agent maintains a previous_responses list accumulating all Thoughts, Actions, and Observations across iterations. Each cycle constructs an augmented prompt containing system instructions, tool descriptions, prior context, and the original user question, then parses the LLM response for Thought/Action/Action Input or Final Answer patterns, executing tools and feeding observations back until a Final Answer is produced or iteration limit is reached. This creates a stateful, multi-turn reasoning pattern that enables complex task decomposition.

Parses unstructured LLM responses to extract structured Thought, Action, Action Input, and Final Answer fields using pattern matching or regex-based parsing. The parser identifies when the LLM intends to invoke a tool (Action: tool_name, Action Input: parameters) versus when it has reached a conclusion (Final Answer: result), enabling the agent to route responses to either tool execution or return-to-user paths. This decouples the LLM's natural language generation from the agent's control flow.

Implements a dispatch mechanism that matches the Action field from parsed LLM responses to registered ToolInterface instances by name, then invokes the matched tool's execute() method with the Action Input as a parameter. The tool's return value (observation) is captured and appended to the conversation history, completing the action phase of the reasoning loop. This decouples tool selection from tool execution, allowing the agent to support arbitrary tool sets.

Enforces a configurable max_iterations parameter that terminates the reasoning loop if the iteration count exceeds the limit, even if no Final Answer has been produced. The agent tracks the current iteration number and checks it before each loop iteration, returning a timeout or max-iterations-exceeded message if the limit is reached. This prevents infinite loops and runaway agent behavior, but may prematurely terminate complex reasoning tasks.

Defines a ToolInterface base class that standardizes how external tools are integrated into the agent. Developers implement ToolInterface with a name, description, and execute() method, then register tool instances with the agent. The agent automatically includes tool descriptions in the system prompt and routes Action commands to the corresponding tool's execute() method by name matching. This enables pluggable tool composition without modifying agent core logic.

Provides pre-built search tool implementations (SerpAPITool, GoogleSearchTool, SearxSearchTool, HackerNewsSearchTool) that wrap different search APIs and backends. Each tool implements the ToolInterface, accepting a search query as action_input and returning formatted search results as observations. The library abstracts away API-specific authentication and response formatting, enabling developers to swap search providers by changing tool registration without modifying agent logic.

Implements a PythonREPLTool that allows agents to execute arbitrary Python code in a sandboxed REPL environment. The tool accepts Python code as action_input, executes it in an isolated Python process or namespace, captures stdout/stderr, and returns execution results as observations. This enables agents to perform computations, data transformations, and logic that would be difficult to express in natural language or tool parameters.

Implements a ChatLLM class that interfaces with OpenAI's Chat Completion API, maintaining a conversation history as a list of message dicts with role (system/user/assistant) and content fields. The class accepts accumulated context (system prompt, previous thoughts/actions/observations, current query) and constructs a messages array that respects OpenAI's message format. It handles API authentication via OPENAI_API_KEY environment variable and returns raw LLM responses for parsing by the agent.

Provides an Agent class constructor that accepts an LLM instance (ChatLLM), a list of ToolInterface implementations, and optional parameters like max_iterations and system_prompt. The constructor validates inputs, registers tools, and initializes internal state (previous_responses list, iteration counter). This enables developers to declaratively configure agents with specific LLM and tool combinations without writing boilerplate initialization code.

Implements an Agent.run(user_query: str) method that executes the thought-action-observation loop until a Final Answer is produced or max_iterations is reached. The method returns the final answer string and optionally the full conversation history (previous_responses list). This provides a simple synchronous interface for running agents end-to-end without exposing the internal loop mechanics.

Automatically constructs an augmented system prompt that includes the original system_prompt parameter, formatted descriptions of all registered tools (name, description, expected input format), and instructions for the Thought-Action-Observation format. This augmented prompt is prepended to each LLM request, enabling the LLM to discover available tools and understand how to invoke them without hardcoding tool information in the base system prompt.

Maintains a previous_responses list that accumulates all Thought, Action, Observation, and Final Answer entries across agent iterations. Each iteration appends the new thought/action/observation to this list before constructing the next LLM prompt, creating a growing context window that includes the full reasoning history. The list is passed to the LLM as part of the augmented prompt, enabling the LLM to reference prior observations and reasoning steps.