Wrapping a CLI as an Agent Tool

from langchain.agents import create_agent
from langchain.agents.middleware import DockerExecutionPolicy, ShellToolMiddleware

agent = create_agent(
    "anthropic:claude-sonnet-5",
    tools=[],
    middleware=[
        ShellToolMiddleware(
            workspace_root="/workspace",
            execution_policy=DockerExecutionPolicy(image="python:3.12-slim"),
        ),
    ],
)

"""One narrow LangChain tool per docsctl subcommand."""
import os
import re
import subprocess

from langchain.tools import ToolException, tool

DOCSCTL = "/usr/local/bin/docsctl"
NAME = re.compile(r"[A-Za-z0-9][A-Za-z0-9._-]{0,63}")


@tool(parse_docstring=True)
def docsctl_search(query: str, component: str | None = None, limit: int = 10) -> str:
    """Search the documentation and return matching pages as JSON.

    Args:
        query: Free-text query, for example "kalman filter".
        component: Optional component name to restrict the search, for example "irurueta-statistics".
        limit: Maximum number of results, 1 to 100.
    """
    if component is not None and not NAME.fullmatch(component):
        raise ToolException(f"invalid component name {component!r}")
    if not 1 <= limit <= 100:
        raise ToolException("limit must be between 1 and 100")
    argv = [DOCSCTL, "search", "--json", "--no-input", "--limit", str(limit)]
    if component:
        argv += ["--component", component]
    argv += ["--", query]                                    # argv list, "--" before the operand
    try:
        proc = subprocess.run(argv, shell=False, capture_output=True, text=True, timeout=25,
                              stdin=subprocess.DEVNULL, env={"PATH": "/usr/bin:/bin"})
    except subprocess.TimeoutExpired:
        raise ToolException("docsctl timed out; retry with a narrower query")
    if proc.returncode != 0:                                 # the CLI's error envelope already has a hint
        raise ToolException(f"docsctl exited {proc.returncode}: {proc.stderr.strip()[:2000]}")
    return proc.stdout


docsctl_search.handle_tool_error = True                      # return the ToolException message to the model


@tool
def docsctl_publish_plan(component: str) -> str:
    """Show what publishing a component would change (a dry run). It never publishes."""
    if not NAME.fullmatch(component):
        raise ToolException(f"invalid component name {component!r}")
    argv = [DOCSCTL, "publish", "--json", "--no-input", "--dry-run", "--component", component]
    proc = subprocess.run(argv, shell=False, capture_output=True, text=True, timeout=25,
                          stdin=subprocess.DEVNULL, env={"PATH": "/usr/bin:/bin"})
    if proc.returncode != 0:
        raise ToolException(f"docsctl exited {proc.returncode}: {proc.stderr.strip()[:2000]}")
    return proc.stdout


docsctl_publish_plan.handle_tool_error = True

from langchain.agents import create_agent
from langchain.agents.middleware import HumanInTheLoopMiddleware
from langgraph.checkpoint.memory import InMemorySaver
from docsctl_tools import docsctl_publish_plan, docsctl_search

agent = create_agent(
    "anthropic:claude-sonnet-5",
    tools=[docsctl_search, docsctl_publish_plan],
    checkpointer=InMemorySaver(),
    middleware=[HumanInTheLoopMiddleware(interrupt_on={"docsctl_publish_plan": True})],
)

package com.example;

import java.util.List;
import org.springframework.ai.tool.annotation.Tool;
import org.springframework.ai.tool.annotation.ToolParam;
import org.springframework.stereotype.Component;

@Component
public class DocsctlSpringAiTools {

    @Tool(name = "docsctl_search",
            description = "Search the documentation of this site. Returns JSON with a results array; "
                    + "use a small limit and refine the query instead of paging through everything.")
    public String search(
            @ToolParam(description = "Free-text query, for example 'kalman filter'") String query,
            @ToolParam(description = "Number of results, 1 to 100", required = false) Integer limit) {
        int n = limit == null ? 10 : limit;
        if (n < 1 || n > 100 || query == null || query.isBlank() || query.length() > 200) {
            throw new IllegalArgumentException("query must be 1-200 characters and limit 1-100");
        }
        return DocsctlTools.runDocsctl(List.of("/usr/local/bin/docsctl", "search", "--json", "--no-input",
                "--limit", String.valueOf(n), "--", query));
    }
}

ChatClient chat = builder.defaultTools(new DocsctlSpringAiTools()).build();

package com.example;

import dev.langchain4j.agent.tool.P;
import dev.langchain4j.agent.tool.Tool;
import java.util.List;

public class DocsctlLc4jTools {

    @Tool("Search the documentation of this site. Returns JSON with a results array.")
    String docsctlSearch(@P("free-text query") String query,
                         @P(value = "number of results, 1 to 100", required = false) Integer limit) {
        int n = limit == null ? 10 : limit;
        if (n < 1 || n > 100 || query == null || query.isBlank() || query.length() > 200) {
            throw new IllegalArgumentException("query must be 1-200 characters and limit 1-100");
        }
        return DocsctlTools.runDocsctl(List.of("/usr/local/bin/docsctl", "search", "--json", "--no-input",
                "--limit", String.valueOf(n), "--", query));
    }
}

Assistant assistant = AiServices.builder(Assistant.class)
        .chatModel(model)
        .tools(new DocsctlLc4jTools())
        .build();