# Using aisuite Agents API Toolkits: Files, Git, and Shell Integration

> Learn to integrate files, git, and shell toolkits with the aisuite Agents API for real-world LLM operations. Explore the power of schema-validated tools.

- Repository: [Andrew Ng/aisuite](https://github.com/andrewyng/aisuite)
- Tags: how-to-guide
- Published: 2026-06-15

---

**The aisuite Agents API provides built-in files, git, and shell toolkits that enable LLM agents to execute real-world operations through schema-validated tools defined in the `aisuite.toolkits` package.**

The `andrewyng/aisuite` repository offers a lightweight framework for creating LLM-driven agents with practical capabilities. By integrating the **files**, **git**, and **shell** toolkits with the `aisuite.Agent` class, you can automate filesystem manipulation, version control workflows, and system command execution within a controlled, policy-enforced environment. This guide demonstrates how to instantiate these toolkits and bind them to agents using the concrete implementations found in `aisuite/toolkits/` and the abstract `Tool` base class defined in [`aisuite/utils/tools.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/utils/tools.py).

## Core Architecture of aisuite Toolkits

The toolkit system consists of three layers: the Agent orchestrator, the abstract Tool interface, and the concrete toolkit implementations.

### The Agent Class

The `aisuite.Agent` class, exposed in [`aisuite/__init__.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/__init__.py), serves as the primary orchestrator. It accepts a `model` identifier (e.g., `openai:gpt-4o`), a `name`, optional tags, and a list of **tool** objects via the `tools` parameter. When you pass toolkit instances to the constructor, the Agent automatically registers their schemas and makes them available to the LLM during inference.

### The Tool Abstraction Layer

All toolkits inherit from `aisuite.utils.tools.Tool`, located in [`aisuite/utils/tools.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/utils/tools.py). This abstract base class enforces a consistent interface:

- **Metadata**: Each tool defines a `name`, `description`, and JSON Schema for its input arguments.
- **Execution**: The `run` method contains the actual implementation logic.
- **Policy Enforcement**: The class integrates with `ToolPolicyDecision` to support whitelist/blacklist restrictions on a per-agent basis.

The base class also handles argument validation, ensuring that inputs from the LLM conform to the declared schema before execution.

### Concrete Toolkit Implementations

The `aisuite/toolkits/` directory contains three primary implementations:

- **`aisuite.toolkits.shell.ShellTool`**: Executes arbitrary shell commands on the host system using safe subprocess wrappers defined in [`aisuite/utils/utils.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/utils/utils.py).
- **`aisuite.toolkits.git.GitTool`**: Performs version control operations (clone, status, add, commit, push) within a specified `work_dir`.
- **`aisuite.toolkits.files.FilesTool`**: Provides read, write, list, and delete operations constrained to a designated `root_dir` to prevent path traversal attacks.

These toolkits are **stateless** apart from their configured directories, allowing safe reuse across multiple agents without cross-contamination.

## How Toolkits Integrate with the Agents API

The integration follows a structured request-response cycle between the LLM and the tool implementations.

### Tool Registration and Schema Exposure

When you instantiate an `Agent` with toolkit objects, the runtime serializes each tool's JSON Schema into the system prompt. This informs the LLM about available functions, their purposes, and required arguments. The Agent manages this registration automatically based on the `tools` list passed to the constructor.

### Runtime Execution Flow

During a conversation, the execution flow proceeds as follows:

1. **Invocation**: The LLM generates a JSON payload containing `"name": "<tool_name>"` and `"arguments": { ... }`.
2. **Validation**: The Agent retrieves the matching tool by name and validates the arguments against the schema defined in the `Tool` subclass.
3. **Execution**: The Agent calls the tool's `run` method, which performs the actual work (e.g., executing a shell command or reading a file).
4. **Integration**: The result (or a raised `ToolError`) is appended to the conversation history as an observation, allowing the LLM to continue with the updated context.

This loop continues until the LLM produces a final response without requesting additional tool calls.

## Practical Implementation Examples

### Multi-Toolkit Agent Configuration

The following example demonstrates how to combine all three toolkits to create an agent capable of filesystem introspection, git operations, and shell command execution:

```python
import aisuite as ai
from aisuite.toolkits.shell import ShellTool
from aisuite.toolkits.git import GitTool
from aisuite.toolkits.files import FilesTool

# Instantiate toolkits with specific working directories

shell = ShellTool()
git = GitTool(work_dir=".")
files = FilesTool(root_dir=".")

# Create agent with multiple capabilities

assistant = ai.Agent(
    name="dev-assistant",
    model="openai:gpt-4o",
    tools=[shell, git, files],
)

# Run a complex task requiring multiple tools

result = assistant.run(
    """
    List all Python files in the current directory, 
    check the git status, and show the last commit message.
    """
)
print(result)

```

In this configuration, the LLM can chain tool calls: first using `files.list` to discover Python files, then `git.status` to check repository state, and finally `git.log` to retrieve commit history.

### Restricting Access with Tool Policies

To limit an agent's capabilities, use the `ToolPolicyDecision` class to whitelist specific operations:

```python
from aisuite.utils.tools import ToolPolicyDecision

# Create a read-only policy

read_only_policy = ToolPolicyDecision(allow=["files.list", "files.read"])

# Agent can only list and read files, not write or delete

viewer_agent = ai.Agent(
    name="file-viewer",
    model="openai:gpt-4o-mini",
    tools=[FilesTool(root_dir="./docs")],
    tool_policy=read_only_policy,
)

```

This policy mechanism prevents the agent from invoking destructive operations even if the toolkit supports them.

## Key Source Files and Implementation Details

| File | Purpose | Key Components |
|------|---------|----------------|
| [`aisuite/__init__.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/__init__.py) | Exports `Agent`, `Client`, and `Runner` classes | `Agent` constructor, tool binding logic |
| [`aisuite/utils/tools.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/utils/tools.py) | Abstract base class and policy types | `Tool` class, `ToolPolicyDecision`, validation logic |
| [`aisuite/utils/utils.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/utils/utils.py) | Helper utilities for safe execution | Subprocess wrappers, logging, path sanitization |
| [`aisuite/toolkits/shell.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/toolkits/shell.py) | Shell command execution | `ShellTool` class, command sanitization |
| [`aisuite/toolkits/git.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/toolkits/git.py) | Git operations | `GitTool` class, `work_dir` parameter handling |
| [`aisuite/toolkits/files.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/toolkits/files.py) | Filesystem operations | `FilesTool` class, `root_dir` constraints, path traversal prevention |
| [`tests/toolkits/test_shell.py`](https://github.com/andrewyng/aisuite/blob/main/tests/toolkits/test_shell.py) | Unit tests for shell toolkit | Usage examples and edge case handling |
| [`tests/toolkits/test_git.py`](https://github.com/andrewyng/aisuite/blob/main/tests/toolkits/test_git.py) | Unit tests for git toolkit | Reference implementations of git workflows |
| [`tests/toolkits/test_files.py`](https://github.com/andrewyng/aisuite/blob/main/tests/toolkits/test_files.py) | Unit tests for files toolkit | Safety validation and file operation tests |

## Summary

- **The `aisuite.Agent` class** accepts toolkit instances via the `tools` parameter and manages their registration and execution lifecycle.
- **Three built-in toolkits**—`ShellTool`, `GitTool`, and `FilesTool`—provide schema-validated interfaces for system commands, version control, and filesystem operations.
- **The `Tool` base class** in [`aisuite/utils/tools.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/utils/tools.py) enforces JSON Schema validation and integrates with `ToolPolicyDecision` for security restrictions.
- **Toolkits are stateless** and configurable via parameters like `work_dir` and `root_dir`, ensuring safe reuse across agents.
- **Execution follows a structured flow**: LLM requests tool call → Agent validates → Tool runs → Result returns to LLM.

## Frequently Asked Questions

### How do I prevent an agent from executing dangerous shell commands?

Use the `ToolPolicyDecision` class from [`aisuite/utils/tools.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/utils/tools.py) to create a whitelist of permitted tools or operations. Alternatively, avoid attaching `ShellTool` to agents that do not require system command access, or restrict the `FilesTool` to specific `root_dir` paths to prevent access to sensitive system files.

### Can I combine multiple toolkits with a single agent instance?

Yes. The `tools` parameter in `aisuite.Agent` accepts a list of toolkit objects. You can combine `ShellTool`, `GitTool`, and `FilesTool` in a single agent, allowing the LLM to orchestrate complex workflows that involve file manipulation, git operations, and shell commands in a single conversation turn.

### What parameters control the working directory for git and file operations?

`GitTool` accepts a `work_dir` parameter that specifies the repository path for all git operations. `FilesTool` accepts a `root_dir` parameter that constrains all file operations to that directory and its subdirectories, preventing path traversal outside the designated scope.

### How does the Agents API handle tool call validation?

The `Tool` base class defines a JSON Schema for each tool's arguments. When the LLM requests a tool call, the Agent validates the provided arguments against this schema before invoking the `run` method. If validation fails, a `ToolError` is raised and returned to the LLM, which can then attempt to correct its input.