[Kaap10]

Description

This PR introduces the foundational agent architecture on top of the newly integrated multi-provider chat abstractions. It provides a robust, strictly-typed tool execution framework, a resilient ReAct loop capable of autonomous tool-use and error recovery, and a Planner for decomposing complex goals into sequential execution steps. This sets up the critical infrastructure needed for more advanced agentic workflows in the future.

Related issue

Fixes #288

Changes

• Implemented AgentTool class and a @tool decorator that leverages inspect.signature to automatically extract docstrings and generate strict JSON schemas (including robust support for __future__ stringified annotations).
• Implemented ReActAgent with synchronous (run) and asynchronous (arun) Think-Act-Observe loops, complete with step budget guards to prevent infinite loops and graceful observation-based error handling for failed tool executions.
• Implemented Planner agent to break down high-level objectives into strictly ordered PlanStep sequences using structured JSON outputs.
• Added a comprehensive suite of unit tests (tests/test_agents.py) verifying multi-step tool execution, async runtimes, budget exhaustion, unregistered tools, and error recovery using a deterministic offline fake model.

Testing

• Tests pass locally
• Ruff checks pass
• Documentation updated, if applicable (N/A for internal architecture, but docstrings are strictly enforced)

Checklist

• My changes are focused and relevant to this pull request.
• I have added or updated tests where appropriate.
• I have reviewed my changes for unrelated modifications.
• I have updated documentation where necessary.

[Kaap10]

Ready for review!

[codeforstartups]

Reviewed in depth — excellent work, this cleanly implements the P2 agent primitives (closes #288). 🎯

Design — builds right on the #317 chat layer: ReActAgent runs the think→act→observe loop (model invoke → if no tool_calls it's done, else execute tools, append role="tool" messages with tool_call_id, repeat), with a max_steps budget guard and a clean AgentResult/AgentStep record of the trace. Planner decomposes a goal into an ordered Plan with robust JSON extraction + a line-split fallback. Both expose sync + async (run/arun, plan/aplan). The function→JSON-schema AgentTool generator is a nice touch for ergonomic tool registration.

Tests — 8 genuine offline tests via a ScriptedChatModel fake: schema generation, 2-tool task, max-steps guard, tool-error handling, unregistered-tool path, async arun, planner decomposition + async aplan. Verified locally (8 passed) and all 4 CI checks green incl. strict mypy on 3.9/3.11/3.12.

Non-blocking follow-ups for later: the sync/async run/arun bodies duplicate a fair bit — could share a step helper; and #289 (multi-agent supervisor/handoffs) is the natural next piece on top of this.

Merging — great contribution @Kaap10!