Skip to content

refactor: reunify tools architecture with tinyagent native OpenAI tool support #388

@larock22

Description

@larock22

Problem Statement

Now that we've migrated to tinyagent (which supports standard OpenAI tool calls), our tools architecture has accumulated adapter layers that may be unnecessary. The current implementation manually builds OpenAI JSON schemas in _build_openai_parameters_schema() and maintains a custom to_tinyagent_tool() adapter.

This creates several fragmentation points:

  1. Manual schema generation: We maintain ~120 lines of custom code to generate OpenAI JSON schemas from type annotations, when tinyagent likely handles this natively
  2. Type system bifurcation: We maintain parallel type hierarchies (CanonicalToolCall, ToolCallPart, etc.) alongside tinyagent's native types
  3. Legacy migration artifacts: The decorator system (@base_tool, @file_tool) was designed for pydantic-ai compatibility and may be redundant

Direction

We should use native tinyagent tool definitions wherever possible. The goal is to identify what minimal (if any) adapter layer is required beyond what tinyagent provides out of the box.

Constraints

  • Must maintain existing tool behavior and error handling semantics
  • Tool execution must remain async with abort signal support
  • XML prompts must be preserved (they are part of agent steering)
  • File tools need path-specific error handling (@file_tool behavior)

Context

Current tool-to-tinyagent flow:

@base_tool/@file_tool decorated function
    -> to_tinyagent_tool() [manual schema building]
        -> AgentTool with custom execute() wrapper
            -> tinyagent agent loop

Files involved:

  • src/tunacode/tools/decorators.py - Custom adapters and schema generation
  • src/tunacode/tools/xml_helper.py - XML prompt loading
  • src/tunacode/core/agents/agent_components/agent_config.py - Tool registration
  • src/tunacode/types/canonical.py - Parallel type definitions

Research Questions

  1. What native @tool decorators or patterns does tinyagent provide?
  2. How does tinyagent handle schema generation from type annotations?
  3. What error handling hooks does tinyagent expose?
  4. Can tinyagent integrate with our XML prompt system for tool descriptions?
  5. Should we use tinyagent's type system directly instead of maintaining CanonicalToolCall?
  6. What is the minimal adapter layer needed for our specific requirements?

Upstream Changes

  • tinyagent native retry: tinyagent will be implementing native retry functionality, which may supersede our custom ToolRetryError handling

Acceptance Criteria

  • Research and document tinyagent's native tool definition capabilities
  • Document the current adapter layer and identify what it provides beyond tinyagent's defaults
  • Identify how XML prompt integration would work with native tinyagent tools
  • Identify which manual JSON schema generation can be delegated to tinyagent
  • Note any blockers or incompatibilities with going fully native

Metadata

Metadata

Assignees

No one assigned

    Labels

    hardVery challenging issues requiring significant architectural changesrefactorCode restructuring without behavior change

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions