> ## Documentation Index
> Fetch the complete documentation index at: https://amd-gaia.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Tool Mixins

<Note>
  ⚡ **You are viewing:** Quick Reference - Common mixin usage patterns

  **See also:** [17 Detailed Mixin Specifications](/docs/spec/file-tools-mixin) (under Specifications → Tool Mixins)
</Note>

<Info>
  **Source Code:** [`src/gaia/agents/tools/`](https://github.com/amd/gaia/tree/main/src/gaia/agents/tools/), [`hub/agents/python/code/gaia_agent_code/tools/`](https://github.com/amd/gaia/tree/main/hub/agents/python/code/gaia_agent_code/tools/)
</Info>

<Note>
  **Import:** `from gaia.agents.tools.file_monitor_tools import FileToolsMixin`
</Note>

***

**Purpose:** Reusable tool sets that can be mixed into your agents.

**Available Mixins:** For complete API specifications of all 17 mixins, see [Specifications → Tool Mixins](/docs/spec/file-tools-mixin)

## Composable mixins (registry)

The agent registry exposes these mixins by name in `KNOWN_TOOLS`
([`src/gaia/agents/registry.py`](https://github.com/amd/gaia/blob/main/src/gaia/agents/registry.py)).
A [custom agent](/docs/guides/custom-agent) can compose any of them by listing the
tool name — BuilderAgent's template wires the import and base class for you.
Each row is the exact `name → module.Class` mapping the registry resolves:

| Tool name     | Import                                                                | Purpose                                 |
| ------------- | --------------------------------------------------------------------- | --------------------------------------- |
| `rag`         | `from gaia.agents.tools.rag_tools import RAGToolsMixin`               | Document retrieval                      |
| `code_index`  | `from gaia.agents.tools.code_index_tools import CodeIndexToolsMixin`  | Semantic code search (FAISS)            |
| `file_search` | `from gaia.agents.tools.file_tools import FileSearchToolsMixin`       | Fuzzy/glob file search                  |
| `file_io`     | `from gaia.agents.tools.file_io_tools import FileIOToolsMixin`        | Read/write/edit files                   |
| `shell`       | `from gaia.agents.tools.shell_tools import ShellToolsMixin`           | Sandboxed shell commands                |
| `screenshot`  | `from gaia.agents.tools.screenshot_tools import ScreenshotToolsMixin` | Screen capture                          |
| `filesystem`  | `from gaia.agents.tools.filesystem_tools import FileSystemToolsMixin` | File system navigation                  |
| `scratchpad`  | `from gaia.agents.tools.scratchpad_tools import ScratchpadToolsMixin` | SQL scratchpad tables for data analysis |
| `browser`     | `from gaia.agents.tools.browser_tools import BrowserToolsMixin`       | Web search, page fetch, download        |
| `sd`          | `from gaia.sd.mixin import SDToolsMixin`                              | Stable Diffusion image generation       |
| `vlm`         | `from gaia.vlm.mixin import VLMToolsMixin`                            | Vision LLM / structured extraction      |

The sections below show usage patterns for the most common mixins; the
`file_io` mixin is covered under [Code Development](./code-mixins).

## 9.1 File Watching Mixin

**Detailed Spec:** [FileToolsMixin](/docs/spec/file-tools-mixin)

The chat-tools `FileToolsMixin` is narrowly scoped to **watching** directories
for new documents; it does not register read/write/list tools. Use
`FileSearchToolsMixin` (§9.4 below) when you need generic filesystem I/O.

```python theme={null}
from gaia.agents.base.agent import Agent
from gaia.agents.tools.file_monitor_tools import FileToolsMixin

class MyAgent(Agent, FileToolsMixin):
    """Agent that can watch directories for new files."""

    def _register_tools(self):
        super()._register_tools()
        self.register_file_tools()
        # Registers: add_watch_directory(directory: str) -> dict
```

***

## 9.2 RAG Tools Mixin

**Import:** `from gaia.agents.tools.rag_tools import RAGToolsMixin`
**Detailed Spec:** [RAGToolsMixin](/docs/spec/rag-tools-mixin)

```python theme={null}
from gaia.agents.base.agent import Agent
from gaia.agents.tools.rag_tools import RAGToolsMixin

class MyAgent(Agent, RAGToolsMixin):
    """Agent with document Q&A tools."""

    def __init__(self, documents_path: str = "./docs", **kwargs):
        self.documents_path = documents_path
        super().__init__(**kwargs)

    def _register_tools(self):
        super()._register_tools()
        self.register_rag_tools()
        # Registers:
        # - query_documents(query, max_chunks=...)
        # - query_specific_file(file_path, query, max_chunks=...)
        # - search_indexed_chunks(query, limit=...)
        # - index_document(file_path)            # singular — one file per call
        # - index_directory(directory_path)
        # - list_indexed_documents()
        # - summarize_document(file_path, summary_type="detailed")
        # - dump_document(file_path)
        # - evaluate_retrieval(query)
        # - rag_status()
```

***

## 9.3 Shell Commands Mixin

**Import:** `from gaia.agents.tools.shell_tools import ShellToolsMixin`
**Detailed Spec:** [ShellToolsMixin](/docs/spec/shell-tools-mixin)

```python theme={null}
from gaia.agents.base.agent import Agent
from gaia.agents.tools.shell_tools import ShellToolsMixin

class MyAgent(Agent, ShellToolsMixin):
    """Agent that can execute shell commands."""

    def _register_tools(self):
        super()._register_tools()
        self.register_shell_tools()
        # Registers:
        # - run_shell_command(command, working_directory=None, timeout=30)
```

***

## 9.4 File Search Mixin

**Import:** `from gaia.agents.tools.file_tools import FileSearchToolsMixin`
**Detailed Spec:** [FileSearchToolsMixin](/docs/spec/file-search-mixin)

`FileSearchToolsMixin` is the general-purpose filesystem toolbox — it's what
powers `read_file` / `write_file` in the chat agent.

```python theme={null}
from gaia.agents.base.agent import Agent
from gaia.agents.tools.file_tools import FileSearchToolsMixin

class MyAgent(Agent, FileSearchToolsMixin):
    """Agent with generic file I/O and search capabilities."""

    def _register_tools(self):
        super()._register_tools()
        self.register_file_search_tools()
        # Registers:
        # - search_file(filename, directory=".")
        # - search_directory(pattern, directory=".")
        # - search_file_content(pattern, directory=".", file_pattern="*")
        # - read_file(file_path, start_line=None, end_line=None)
        # - write_file(file_path, content, append=False)
        # - browse_directory(directory_path=None, show_hidden=False, sort_by="name")
        # - get_file_info(file_path)
        # - analyze_data_file(file_path, ...)
        # - list_recent_files(location="all", ...)
```

***

## 9.5 Stable Diffusion Mixin

**Import:** `from gaia.sd import SDToolsMixin`
**Detailed Guide:** [Image Generation Guide](/docs/guides/sd)
**Source:** [`src/gaia/sd/mixin.py`](https://github.com/amd/gaia/tree/main/src/gaia/sd/mixin.py)

```python theme={null}
from gaia.agents.base.agent import Agent
from gaia.sd import SDToolsMixin

class MyImageAgent(Agent, SDToolsMixin):
    """Agent with image generation tools."""

    def __init__(self):
        super().__init__(
            model_id="Qwen3-8B-GGUF",  # LLM for orchestration
            min_context_size=8192,  # 8K sufficient for SD
        )

        # Initialize SD tools (auto-registers generate_image, list_sd_models, etc.)
        self.init_sd(
            output_dir=".gaia/cache/sd/images",
            default_model="SDXL-Turbo",  # Fast, good quality
        )

    def _register_tools(self):
        pass  # Tools already registered by init_sd()

    def _get_system_prompt(self):
        return "You generate images. Use generate_image with enhanced prompts."

# Usage
agent = MyImageAgent()
result = agent.process_query("create a sunset over mountains")
# Agent enhances prompt and calls generate_image automatically
```

**Available Tools:**

* `generate_image(prompt, model, size, steps, cfg_scale, seed)` - Generate images with SD
* `list_sd_models()` - Show available models
* `get_generation_history(limit)` - See generated images from session

**Supported Models:**

* **SDXL-Turbo** (default) - Fast, 512x512, \~17s
* **SD-Turbo** - Faster, 512x512, \~13s
* **SDXL-Base-1.0** - Photorealistic, 1024x1024, \~9min
* **SD-1.5** - Legacy, 512x512, \~88s

***

## 9.6 Vision Language Model Mixin

**Import:** `from gaia.vlm import VLMToolsMixin`
**Source:** [`src/gaia/vlm/mixin.py`](https://github.com/amd/gaia/tree/main/src/gaia/vlm/mixin.py)

```python theme={null}
from gaia.agents.base.agent import Agent
from gaia.vlm import VLMToolsMixin

class MyVisionAgent(Agent, VLMToolsMixin):
    """Agent with vision analysis tools."""

    def __init__(self):
        super().__init__(min_context_size=8192)

        # Initialize VLM tools (auto-registers analyze_image, create_story_from_image, etc.)
        self.init_vlm(model="Qwen3-VL-4B-Instruct-GGUF")

    def _register_tools(self):
        pass  # Tools already registered by init_vlm()

    def _get_system_prompt(self):
        return "You analyze images. Use VLM tools for descriptions, stories, and Q&A."

# Usage
agent = MyVisionAgent()
result = agent.process_query("analyze this image: photo.jpg")
# Agent calls analyze_image automatically
```

**Available Tools:**

* `analyze_image(image_path, focus)` - Get detailed image description
* `create_story_from_image(image_path, story_style)` - Generate creative narrative
* `answer_question_about_image(image_path, question)` - Answer specific questions

**Focus Options:** `composition`, `colors`, `mood`, `details`, `all` (default)
**Story Styles:** `whimsical`, `dramatic`, `educational`, `adventure`, `any` (default)

***

## Related Topics

* [Core Agent System](../core/agent-system) - Learn about the base Agent class
* [Code Development Mixins](./code-mixins) - Specialized code development tools
* [User Guides](/docs/guides/index) - Pre-built agent implementations
* [Best Practices](../best-practices) - Agent development guidelines

***

<small style="color: #666;">
  **License**

  Copyright(C) 2024-2026 Advanced Micro Devices, Inc. All rights reserved.

  SPDX-License-Identifier: MIT
</small>