Skip to content

Add tool-use logging for agent tool invocations #8

@pnilan

Description

@pnilan

Summary

When the agent invokes tools during a conversation, there is no logging or user-visible feedback about which tools were called, what arguments were passed, or what results were returned. This makes it difficult to debug unexpected behavior, audit agent actions, and understand what's happening during longer multi-tool interactions.

Motivation

  • Debugging: When the agent produces an unexpected result, there's no way to trace which tools it called or what arguments it used without inspecting PydanticAI internals.
  • User feedback: In the REPL, the user sees only the streamed text response — tool calls happen silently. A brief indicator (e.g., ⚙ send_cc(synth="minilogue-xd", parameter="cutoff", value=80)) would improve the interactive experience.
  • Audit trail: For patch management and MIDI operations, it's useful to have a record of what the agent actually did (e.g., which CCs were sent, which patches were saved/deleted).

Current behavior

  • Tools are async functions registered on the PydanticAI Agent in agent.py
  • The CLI loop in cli.py uses agent.run_stream() which handles tool dispatch internally
  • No logging module is used anywhere in the codebase
  • Errors are returned as plain strings from tool functions or printed via rich.Console

Proposed behavior

  1. Add Python logging with a patchwork logger hierarchy (e.g., patchwork.tools.midi, patchwork.tools.patches)
  2. Log tool calls at INFO level with tool name and arguments when a tool is invoked
  3. Log tool results at DEBUG level with the return value
  4. Log errors at WARNING/ERROR level when tool execution fails
  5. Surface tool use in the REPL — display a brief, styled indicator in the console when the agent calls a tool (before the streamed text response), so the user can see what's happening in real time

Implementation notes

  • PydanticAI exposes message types like ToolCallPart and ToolReturnPart in the message history (result.all_messages()). These can be inspected after each run_stream() call, or the stream's message events can be consumed to show tool calls as they happen.
  • Consider a --verbose / -v CLI flag to control whether tool-call indicators are shown in the REPL (default on for tool names, off for full args/results).
  • Log output should go to a file (e.g., data/patchwork.log) or stderr, not stdout, to avoid mixing with the streamed agent response.

References

  • Agent definition: patchwork/agent.py
  • CLI loop: patchwork/cli.py
  • Tool modules: patchwork/tools/midi_control.py, patchwork/tools/patches.py

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions