dspy-agent-tools 0.1.3

About

DSPy Agent Tools is a library of tool functions for DSPy agents. Every tool is a plain, type-hinted Python function with a tool-optimized docstring, so you can hand them straight to dspy.ReAct or dspy.RLM — no adapters, no wrappers.

Three families of tools:

• Bash — shell execution, file search (ripgrep/fd-style, no binaries needed), directory listing, and URL fetching
• Files — read, write, and edit files with snapshot-based optimistic concurrency and tree-sitter block addressing
• Search — DuckDuckGo web and news search

Tools are just Python functions, exactly as DSPy's docs describe: DSPy reads the name, type-hinted parameters, and docstring of each function to assemble the instructions it sends to the LM. These docstrings are written for that purpose — each one tells the model WHAT the tool does, WHEN to use it instead of a sibling tool, and HOW to pass arguments.

Requires Python 3.13+ and DSPy 3.1+.

(back to top)

Quick Start

Install

Install dspy-agent-tools with uv (recommended):

uv add dspy-agent-tools

Or with pip:

pip install dspy-agent-tools

bash_curl, bash_exec, and bash_ls shell out to real bash/curl/ls binaries, which must be on your PATH. The search tools (bash_ripgrep, bash_find, bash_glob) run through the rgapi library — ripgrep's and fd's engines as Python modules — so no rg/fd binary is needed.

Basic Usage with dspy.ReAct

Import the tools you need and put them in the tools list:

import dspy
from dspy_agent_tools import web_search, bash_fetch

haiku_bot = dspy.ReAct(
    "location -> haiku",
    tools=[web_search, bash_fetch],
)

result = haiku_bot(location="Camp Meeker")
print(result.haiku)

Basic Usage with dspy.RLM

The same functions go into dspy.RLM's tools list, where they are injected into the REPL namespace and callable from the model's generated code:

import dspy
from dspy_agent_tools import bash_exec, read_file, edit_file

rlm = dspy.RLM(
    "task -> report",
    tools=[bash_exec, read_file, edit_file],
)

result = rlm(task="Add a docstring to every public function in src/utils.py")

(back to top)

Usage

With dspy.ReAct

dspy.ReAct runs an agentic reasoning loop over your tools. Pick the tools the agent should see — a coding agent might get the file and shell tools, a research agent the search and fetch tools:

import dspy
from dspy_agent_tools import (
    web_search,
    bash_fetch,
    bash_curl,
    web_news,
)

researcher = dspy.ReAct(
    "question -> answer, sources",
    tools=[web_search, web_news, bash_fetch, bash_curl],
    max_iters=8,
)

result = researcher(question="What changed in DSPy 3.1?")
print(result.answer)

Each tool is presented to the LM by name, docstring, and parameters. The docstrings shipped in this package are already tuned for that presentation — they steer the model toward the right tool (e.g. bash_fetch for readable pages, bash_curl for raw API responses).

With dspy.RLM

dspy.RLM executes model-written Python in a sandboxed REPL and hands the model the same functions to call from inside its code:

import dspy
from dspy_agent_tools import (
    bash_exec,
    bash_ripgrep,
    bash_find,
    read_file,
    write_file,
    edit_file,
)

coder = dspy.RLM(
    "task -> summary",
    tools=[bash_exec, bash_ripgrep, bash_find, read_file, write_file, edit_file],
    max_iters=20,
)

result = coder(task="Rename the class SessionManager to Session across the repo")

A full coding-agent toolbox, all in one import:

from dspy_agent_tools import (
    bash_exec,
    bash_curl,
    bash_fetch,
    bash_find,
    bash_find_batch,
    bash_glob,
    bash_glob_batch,
    bash_ls,
    bash_ripgrep,
    bash_ripgrep_batch,
    edit_file,
    read_file,
    write_file,
    web_news,
    web_search,
)

Batching

Search tools come in single and _batch variants. A batch takes list[dict] — one spec per search, each with pattern, path, and options — and returns labeled sections. Use it when several independent lookups are needed; it saves round trips and shares one timeout across the batch:

bash_ripgrep_batch(
    [
        {"pattern": r"def main", "path": "src", "options": "-n"},
        {"pattern": "TODO|FIXME", "options": "-n -i"},
    ]
)
# == def main in src ==
# src/cli.py:12:def main(args):
# ...
# == TODO|FIXME in . ==
# ...

bash_find_batch and bash_glob_batch work the same way for path lookups.

Safety Notes

• bash_exec runs arbitrary shell commands with the caller's permissions. Sandbox or restrict the agent before giving it that power.
• File tools are guarded by snapshots: read_file returns a short hash of the file's content, and edit_file/write_file reject the change if the file has changed since it was read, so concurrent edits can't be silently overwritten.
• Non-zero exits, timeouts, and failed transfers are reported inline as "[exit code N]" / "[command timed out ...]" notices rather than raised, so an agent can read and recover from failures.

(back to top)

Tool Reference

Bash (dspy_agent_tools.bash)

Files (dspy_agent_tools.files)

Search (dspy_agent_tools.search)

Shared behaviour across the bash tools:

• Output is capped at ~30KB (first 20KB + last 10KB kept) with a truncation notice.
• Wall time is appended as (Ns).
• Timeouts kill the whole process group and return partial output.
• Bad regexes and unknown flags come back as [Error] text instead of raising.

(back to top)

Development

Code Quality

This project uses several tools to maintain code quality:

• Ruff: Linting and formatting
• isort: Import sorting
• pytest: Testing framework
• ty: Type checking
• deptry: Dependency analysis

Available commands:

# Run all quality checks
uv run poe clean-full

# Individual checks
uv run poe lint          # Ruff linting
uv run poe format        # Ruff formatting
uv run poe sort          # Import sorting
uv run poe typecheck     # Type checking
uv run poe deptry        # Dependency analysis

Testing

Run tests using pytest:

# Run all tests
uv run pytest

# Run with coverage
uv run poe test-cov

# Run specific test
uv run pytest path/to/test.py::test_name

(back to top)

Contributing

Quick workflow:

1. Fork and branch: git checkout -b feature/name
2. Make changes
3. Run checks: uv run poe clean-full
4. Commit and push
5. Open a Pull Request

(back to top)

License

MIT (as declared in pyproject.toml).