feat(tools): implement extended tool definitions with native Pydantic…

[Leoyzen]

PR Description

Summary

This PR significantly enhances the Tool system to provide deeper and more native integration with pydantic-ai. It addresses limitations in schema generation for complex context types (like AgentContext) and enables advanced features like the prepare protocol for dynamic tool configuration.

Key Changes

Core Tooling (src/agentpool/tools/base.py)

• Native prepare Protocol Support: Added prepare field to Tool to support pydantic-ai's dynamic tool configuration (middleware-like behavior before tool execution).
• Explicit Schema Overrides: Introduced function_schema to allow direct injection of Pydantic validators and schemas, bypassing auto-generation when needed.
• Robust Schema Generation Strategy:
  • Implemented a smart fallback mechanism: first attempts native pydantic_ai.function_schema, and gracefully falls back to schemez for complex signatures (e.g., those involving AgentContext or forward references) that usually break native generation.
  • Added _detect_takes_ctx to correctly identify and handle RunContext injection requirements.
• Enhanced to_pydantic_ai Conversion: Now utilizes pydantic_ai.Tool.from_schema when custom schemas or overrides are present, ensuring full validation capabilities (including validate_json) are preserved even with custom definitions.

Agent Integration (src/agentpool/agents/native_agent/agent.py)

• Streamlined Tool Loading: Refactored create_pydantic_ai_agent to properly utilize the enhanced Tool.to_pydantic_ai() method, ensuring all tools (native or wrapped) carry their correct schemas and hooks.
• Context Type Safety: Explicitly typed deps_type as AgentContext[TDeps] to ensure correct context propagation throughout the agent lifecycle.

Configuration (src/agentpool_config/tools.py)

• Configurable prepare Hooks: Added support for defining prepare functions via import strings (e.g., module:func) in YAML configuration.

Testing

• Added comprehensive tests in tests/tools/test_tool_schema.py covering:
  • Schema generation fallback scenarios.
  • RunContext vs AgentContext handling.
  • Validation of tools with overridden schemas.
  • Async/Sync execution paths.

Motivation

Previously, tools requiring AgentContext or complex dependencies often failed standard PydanticAI schema generation or lost validation capabilities when manually overridden. This PR ensures that:

1. Complex tools work out-of-the-box with auto-generated schemas via schemez fallback.
2. We can leverage PydanticAI's advanced prepare features for JIT tool modification.
3. Validation logic (validate_json) remains intact even when schemas are customized.

[phil65]

Could you explain some concrete use cases here?

[Leoyzen]

@phil65 Here are the concrete use cases for prepare:

1. Dynamic Context Injection (Hidden from LLM)
Tools often need runtime context like session_id, user_id, knowledge_id, or auth tokens. With prepare, we can:

• Inject these values from ctx.deps at runtime
• Keep them hidden from the LLM schema (the model doesn't need to know or provide them)

2. Dynamic Schema Modification
Example: A delegation tool needs to know which agents are available to delegate to. With prepare:

• Inspect ctx to get active agent roles
• Dynamically inject available agent names into the tool's parameter descriptions
• The LLM sees up-to-date options without hardcoding

Why prepare from pydantic-ai
These use cases all require access to ctx. PydanticAI's prepare protocol provides a clean hook for this — modifying tool configuration JIT before execution with full context access.

Like #23

[phil65]

...and why not just injecting AgentContext/RunContext via tool signature and doing the injection in the tool?

[Leoyzen]

@phil65 Good question. The context injection already works in main (via function signature) — that part is fine.

What's missing is dynamic schema definition based on runtime context.

The schema is generated at tool registration time, before we have access to ctx.deps. So we can't do things like:

# Current limitation:
async def delegate_to(agent_names: list[str], message: str):
    # LLM sees: "agent_names: list of agent names to delegate to"
    # But we want: "Available agents: [writer, reviewer, coder]" <- dynamic!
    ...

With prepare, the schema is modified JIT when ctx is available. This lets us:

1. Inject dynamic parameter descriptions that reflect runtime state
2. Hide internal params from the LLM while still passing them at execution

So prepare isn't about context injection — it's about schema-level dynamism that the current static approach can't support.