nexau-agent

Original source / Raw SKILL.md

---
name: nexau-agent
description: Guide for building NexAU agents from scratch. This skill should be used when implementing a new NexAU agent — including YAML configuration, system prompt, tool definitions, tool bindings, entry point scripts.
---

# NexAU Agent Builder

This skill provides the procedural knowledge and reference material needed to implement NexAU agents correctly and efficiently.

## When to Use

- Implementing a new standalone agent (YAML config + system prompt + tools + entry point)
- Adding custom tools to an existing agent
- Writing or refining system prompts for NexAU agents
- Setting up skills for an agent
- Looking up NexAU framework concepts (agents, tools, LLMs, transports, sessions, etc.)

> **NexAU Documentation**: The `docs/` directory contains the full user-facing documentation for NexAU. Start with `docs/index.md` for an overview, `docs/getting-started.md` for setup, `docs/core-concepts/` for fundamentals (agents, tools, LLMs), and `docs/advanced-guides/` for topics like skills, hooks, MCP, sandbox, transports, and session management.

## Agent Implementation Workflow

### 1. Understand the Requirements

Before writing any code, read the RFC or requirements document thoroughly. Identify:

- Agent purpose and capabilities
- Required tools (builtin vs custom)
- LLM configuration needs (model, temperature, token limits)
- Any skills the agent should have

### 2. Create the Directory Structure

A standalone agent follows this layout:

```
agent_name/
├── agent_name.yaml          # Agent configuration
├── systemprompt.md           # System prompt (Jinja2 or plain string)
├── start.py                  # Entry point script
├── tools/                    # Tool definitions
│   ├── read_file.tool.yaml
│   ├── write_file.tool.yaml
│   └── custom_tool.tool.yaml
├── skills/                   # Optional skills
│   └── skill-name/
│       └── SKILL.md
└── custom_tools/             # Custom tool implementations (if any)
    └── custom_tool.py
```


### 3. Write the Agent YAML Config

Refer to `references/agent-yaml-reference.md` for the complete field reference. Key points:

- Use `${env.VAR_NAME}` for environment variable substitution (LLM keys, sandbox paths)
- Set `system_prompt_type: jinja` when using template variables like `{{ date }}`
- Set `system_prompt_type: string` for plain text prompts
- Choose `tool_call_mode: openai` for OpenAI-compatible APIs
- Reference tool YAMLs with relative paths: `./tools/tool.tool.yaml`
- Reference system prompt with relative path: `./systemprompt.md`

Template available at: `assets/templates/agent.yaml`

### 4. Define Tools

For each tool the agent needs:

1. Check if a builtin tool exists — see `references/builtin-tools-reference.md`
2. If builtin, copy the tool YAML from an existing example and set the binding path
3. If custom, create both a `.tool.yaml` definition and a Python implementation

Refer to `references/tool-yaml-reference.md` for the tool YAML schema.

Template available at: `assets/templates/tool.tool.yaml`

### 5. Write the System Prompt

Follow the conventions in `references/system-prompt-guide.md`:

- Start with a clear role description
- Define a numbered step-by-step workflow
- Include guidelines and constraints
- Add template variables at the bottom: `{{ date }}`, `{{ username }}`, `{{ working_directory }}`

Template available at: `assets/templates/systemprompt.md`

### 6. Create the Entry Point

For standalone agents, use `Agent.from_yaml()`.

Template available at: `assets/templates/start.py` (standalone)

### 7. Verify the Implementation

- **Validate agent config**:
  ```bash
  python {THIS_SKILL_FOLDER}/scripts/validate_agent.py path/to/agent.yaml
  ```
  - Add `--recursive` to also validate sub-agent configs
  - Add `--json` for machine-readable output
- Check Python syntax: `python -c "import ast; ast.parse(open('start.py').read())"`
- Check imports: `python -c "from nexau import Agent"`
- Run the agent with a simple test query

## Common Patterns

### Environment Variable Substitution in YAML

```yaml
llm_config:
  model: ${env.LLM_MODEL}
  base_url: ${env.LLM_BASE_URL}
  api_key: ${env.LLM_API_KEY}
```

### Adding Builtin Tools

```yaml
tools:
  - name: read_file
    yaml_path: ./tools/read_file.tool.yaml
    binding: nexau.archs.tool.builtin.file_tools:read_file
```

### Adding Skills

```yaml
skills:
  - ./skills/skill-name
```

### Stop Tools

Use `stop_tools` to define tools that halt the agent loop when called:

```yaml
stop_tools: [complete_task]    # For task-based agents
stop_tools: [ask_user]         # For interactive agents
```

### Tracers

```yaml
tracers:
  - import: nexau.archs.tracer.adapters.in_memory:InMemoryTracer
```

## Builtin Tools Catalog

All builtin tool YAML configs are located under `builtin_tools/tools/` in this skill folder. When adding a builtin tool to an agent, copy the YAML to your agent's `tools/` directory and set the binding path accordingly.

### File Tools

| Tool | Binding | Config YAML |
|------|---------|-------------|
| read_file | `nexau.archs.tool.builtin.file_tools:read_file` | `builtin_tools/tools/read_file.tool.yaml` |
| write_file | `nexau.archs.tool.builtin.file_tools:write_file` | `builtin_tools/tools/write_file.tool.yaml` |
| replace | `nexau.archs.tool.builtin.file_tools:replace` | `builtin_tools/tools/replace.tool.yaml` |
| search_file_content | `nexau.archs.tool.builtin.file_tools:search_file_content` | `builtin_tools/tools/search_file_content.tool.yaml` |
| glob | `nexau.archs.tool.builtin.file_tools:glob` | `builtin_tools/tools/Glob.tool.yaml` |
| list_directory | `nexau.archs.tool.builtin.file_tools:list_directory` | `builtin_tools/tools/list_directory.tool.yaml` |


### Web Tools

| Tool | Binding | Config YAML |
|------|---------|-------------|
| google_web_search | `nexau.archs.tool.builtin.web_tools:google_web_search` | `builtin_tools/tools/WebSearch.tool.yaml` |
| web_fetch | `nexau.archs.tool.builtin.web_tools:web_fetch` | `builtin_tools/tools/WebFetch.tool.yaml` |

### Shell Tools

| Tool | Binding | Config YAML |
|------|---------|-------------|
| run_shell_command (sync) | `nexau.archs.tool.builtin.shell_tools:run_shell_command` | `builtin_tools/tools/run_shell_command_sync.tool.yaml` |

### Session Tools

| Tool | Binding | Config YAML |
|------|---------|-------------|
| write_todos | `nexau.archs.tool.builtin.session_tools:write_todos` | `builtin_tools/tools/write_todos.tool.yaml` |
| complete_task | `nexau.archs.tool.builtin.session_tools:complete_task` | `builtin_tools/tools/complete_task.tool.yaml` |
| ask_user | `nexau.archs.tool.builtin.session_tools:ask_user` | `builtin_tools/tools/ask_user.tool.yaml` |


> For detailed parameter descriptions of each tool, see `references/builtin-tools-reference.md`.

## Bundled Resources

| Path | Purpose |
|------|---------|
| `references/agent-yaml-reference.md` | Complete agent YAML config field reference |
| `references/tool-yaml-reference.md` | Tool YAML definition schema and examples |
| `references/builtin-tools-reference.md` | Catalog of all builtin tools with binding paths |
| `references/system-prompt-guide.md` | System prompt writing conventions and patterns |
| `assets/templates/agent.yaml` | Starter agent YAML config template |
| `assets/templates/tool.tool.yaml` | Starter tool YAML definition template |
| `assets/templates/systemprompt.md` | Starter system prompt template |
| `assets/templates/start.py` | Standalone agent entry point template |
| `scripts/validate_agent.py` | Agent YAML validator (schema + file reference checks) |
| `docs/index.md` | NexAU documentation index — entry point for all user-facing docs |
| `docs/getting-started.md` | Installation, setup, and first agent walkthrough |
| `docs/core-concepts/agents.md` | Agent architecture, lifecycle, and configuration |
| `docs/core-concepts/tools.md` | Tool system — definition, binding, execution |
| `docs/core-concepts/llms.md` | LLM provider configuration and aggregator usage |
| `docs/advanced-guides/skills.md` | Skill system — folder-based and tool-based skills |
| `docs/advanced-guides/hooks.md` | Hook system for lifecycle event handling |
| `docs/advanced-guides/mcp.md` | Model Context Protocol integration |
| `docs/advanced-guides/sandbox.md` | Sandbox configuration and isolation |
| `docs/advanced-guides/session-management.md` | Session persistence and history management |
| `docs/advanced-guides/streaming-events.md` | Streaming event types and handling |
| `docs/advanced-guides/transports.md` | Transport layer — HTTP, stdio, WebSocket, gRPC |
| `docs/advanced-guides/templating.md` | Jinja2 templating in system prompts and configs |
| `docs/advanced-guides/context_compaction.md` | Context compaction middleware for long conversations |
| `docs/advanced-guides/global-storage.md` | Global storage for cross-turn agent state |
| `docs/advanced-guides/tracer.md` | Tracing and observability setup |
| `docs/advanced-guides/image.md` | Image input handling |

## Setting Up Skills for an Agent

Skills are reusable capabilities that extend an agent's knowledge and workflows. NexAU supports two types: **folder-based skills** and **tool-based skills**. Both are automatically registered and discoverable via the `LoadSkill` tool at runtime.

### Folder-Based Skills

A folder-based skill is a self-contained directory with a `SKILL.md` file. To add one to an agent:

1. Create the skill directory under the agent's `skills/` folder:

```
skills/
└── my-skill/
    ├── SKILL.md              # Required — metadata + instructions
    ├── scripts/              # Optional — executable code
    ├── references/           # Optional — context docs loaded on demand
    └── assets/               # Optional — templates, images, output files
```

2. Reference the skill in the agent YAML:

```yaml
skills:
  - ./skills/my-skill
```

The agent will see a brief description of the skill in its system prompt and can call `LoadSkill` to read the full `SKILL.md` content when needed.

### Tool-Based Skills

A tool-based skill is a regular tool marked with `as_skill: true` in its YAML definition. This is useful for simple, well-defined capabilities that do not need extensive documentation.

```yaml
# tools/generate_code.tool.yaml
type: tool
name: generate_code
description: Generates code based on specifications
as_skill: true
skill_description: Code generation skill for multiple programming languages
input_schema:
  type: object
  properties:
    language:
      type: string
    specification:
      type: string
  required: [language, specification]
```

The `skill_description` field is required when `as_skill: true`. It provides the brief text shown in the skill registry.

### Combining Both Types

Both skill types can coexist in the same agent:

```yaml
# Agent YAML
skills:
  - ./skills/data-analysis       # Folder-based skill
  - ./skills/report-writing      # Folder-based skill

tools:
  - name: web_search
    yaml_path: ./tools/web_search.tool.yaml   # Tool-based skill (as_skill: true)
    binding: nexau.archs.tool.builtin.web_tools:google_web_search
```

### How Skills Work at Runtime

1. All skills are registered in the agent's `skill_registry` during initialization
2. A `LoadSkill` tool is automatically added to the agent
3. The agent sees brief descriptions of all available skills in its system prompt
4. When the agent needs detailed information, it calls `LoadSkill` with the skill name
5. The full `SKILL.md` content (and skill folder path) is returned to the agent

## Writing High-Quality Skills

A well-crafted skill transforms a general-purpose agent into a specialized one. Follow these principles to maximize effectiveness.

### SKILL.md Structure

Every `SKILL.md` must start with YAML frontmatter containing `name` and `description`:

```markdown
---
name: my-skill
description: Brief description of what this skill does. This skill should be used when [trigger conditions].
---

# Skill Title

[Purpose — what this skill provides, in 1-2 sentences]

## When to Use

[Concrete trigger conditions — when should the agent load this skill]

## Workflow / Instructions

[Step-by-step procedural knowledge]

## Bundled Resources

[Table of scripts, references, and assets with their purposes]
```

### Metadata Quality

The `name` and `description` in the frontmatter determine when the agent will load the skill. Write them carefully:

- **name**: Use lowercase kebab-case (`my-skill`, not `MySkill` or `my_skill`)
- **description**: Be specific about what the skill does and when to use it. Use third-person form (e.g., "This skill should be used when..." instead of "Use this skill when...")

### Progressive Disclosure

Skills use a three-level loading system to manage context efficiently:

1. **Metadata** (name + description) — Always in the agent's system prompt (~100 words)
2. **SKILL.md body** — Loaded when the agent calls `LoadSkill` (target: <5k words)
3. **Bundled resources** — Loaded on demand as the agent reads specific files (unlimited)

Keep `SKILL.md` lean by moving detailed reference material to `references/` files. Only include essential procedural instructions and workflow guidance in the main body.

### Writing Style

- Use **imperative/infinitive form** (verb-first instructions), not second person
- Write "To accomplish X, do Y" rather than "You should do X"
- Keep instructions actionable and specific — vague steps produce vague behavior
- Reference bundled resources explicitly so the agent knows they exist and when to use them

### Bundled Resources Guidelines

| Type | Directory | When to Include | Example |
|------|-----------|-----------------|---------|
| Scripts | `scripts/` | Same code is rewritten repeatedly or deterministic reliability is needed | `scripts/validate_config.py` |
| References | `references/` | Documentation the agent should consult while working | `references/api_schema.md` |
| Assets | `assets/` | Files used in the output (templates, images, boilerplate) | `assets/templates/starter.yaml` |

**Avoid duplication**: Information should live in either `SKILL.md` or reference files, not both. For large reference files (>10k words), include grep search patterns in `SKILL.md` to help the agent locate relevant sections.

### Choosing Between Skill Types

| Criteria | Folder-Based | Tool-Based |
|----------|-------------|------------|
| Needs extensive documentation | ✓ | |
| Includes multiple files (scripts, templates) | ✓ | |
| Single, well-defined capability | | ✓ |
| Tool description is sufficient documentation | | ✓ |
| Will be shared across projects | ✓ | |

### Common Pitfalls

- Putting too much detail in `SKILL.md` instead of `references/` — bloats context on every load
- Vague frontmatter description — the agent cannot determine when to use the skill
- Missing resource references — the agent does not know bundled files exist unless told
- Absolute paths in documentation — use relative paths within the skill folder
- Duplicating information between `SKILL.md` and reference files


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### docs/index.md

```markdown
# Welcome to the NexAU Framework

NexAU is a general-purpose agent framework for building intelligent agents with tool capabilities.

## Features

- **Modular Tool System**: Easy-to-configure tools with YAML-based configuration.
- **Agent Architecture**: Create specialized agents with different capabilities.
- **Built-in Tools**: File operations, web search, bash execution, and more.
- **LLM Integration**: Support for various LLM providers (OpenAI, Claude, etc.).
- **Session Management**: Stateful session persistence with pluggable storage backends (SQL, JSONL, Memory, Remote).
- **Transport System**: Multi-protocol communication (HTTP/SSE, stdio today; WebSocket, gRPC may be added later).
- **Middleware Hooks**: Customize LLM behavior with preprocessing, caching, logging, and provider switching.
- **YAML Configuration**: Define agents and tools declaratively.

## Explore the Documentation

* **[🚀 Getting Started](./getting-started.md)**: Installation, environment setup, and running your first agent.

* **Core Concepts**
    * **[🤖 Agents](./core-concepts/agents.md)**: Learn how to create and configure agents.
    * **[🛠️ Tools](./core-concepts/tools.md)**: Use built-in tools and create your own.
    * **[🧠 LLMs](./core-concepts/llms.md)**: Configure LLM providers and middleware-based extensions.

* **Advanced Guides**
    * **[Skills](./advanced-guides/hooks.md)**: Skills (compatible with Claude Skill format) to dynamically ingest skill context (support both tool and file).
    * **[Hooks/Middleware](./advanced-guides/hooks.md)**: Intercept and modify agent behavior.
    * **[Global Storage](./advanced-guides/global-storage.md)**: Share state across tools and agents.
    * **[Templating](./advanced-guides/templating.md)**: Use Jinja2 for dynamic system prompts.
    * **[Tracer Integration](./advanced-guides/tracer.md)**: Configure and share tracers across agents.
    * **[MCP Integration](./advanced-guides/mcp.md)**: Connect to external services via MCP.
    * **[Context Compaction](./advanced-guides/context_compaction.md)**: Compact long context windows.
    * **[Image Handling](./advanced-guides/image.md)**: Handle images in messages and tools.
    * **[Streaming Events](./advanced-guides/streaming-events.md)** ⚠️ *Experimental*: Incremental, provider-agnostic events (text deltas, tool calls, etc.) for streaming UIs.
    * **[Session Management](./advanced-guides/session-management.md)** ⚠️ *Experimental*: Stateful session persistence, agent tracking, and concurrency control.
    * **[Transport System](./advanced-guides/transports.md)** ⚠️ *Experimental*: Multi-protocol communication (HTTP/SSE, stdio today; WebSocket, gRPC may be added later).

```

### docs/getting-started.md

```markdown
# 🚀 Getting Started


## Installation

### From GitHub Release (Recommended)

**Using pip:**
```bash
# Install from the latest release tag using SSH (you need to use ssh because nexau is a private repo)
pip install git+ssh://[email protected]/nex-agi/[email protected]

# or visit https://github.com/nex-agi/nexau/releases/ and download whl, then
pip install nexau-0.3.8-py3-none-any.whl
```

**Using uv:**
```bash
# Install from the latest release tag using SSH
uv pip install git+ssh://[email protected]/nex-agi/[email protected]

# or visit https://github.com/nex-agi/nexau/releases/ and download whl, then
uv pip install nexau-0.3.8-py3-none-any.whl
```

### Install Latest from Main Branch

**Using pip:**
```bash
pip install git+ssh://[email protected]/nex-agi/NexAU.git
```

**Using uv:**
```bash
uv pip install git+ssh://[email protected]/nex-agi/NexAU.git
```

### From Source

```bash
# Clone the repository
git clone [email protected]:nex-agi/NexAU.git
cd NexAU

# Install dependencies using uv
pip install uv
uv sync
```

## Quick Start

1.  **Set up your environment variables** in a `.env` file:
    ```.env
    LLM_MODEL="your-llm-model"
    LLM_BASE_URL="your-llm-api-base-url"
    LLM_API_KEY="your-llm-api-key"
    SERPER_API_KEY="api key from serper.dev" (required if you need to use web search)

    LANGFUSE_SECRET_KEY=sk-lf-xxx
    LANGFUSE_PUBLIC_KEY=pk-lf-xxx
    LANGFUSE_HOST="https://us.cloud.langfuse.com"
    ```
    Optional: NexAU uses Langfuse for tracing, setup your Langfuse keys if you want to enable traces.

2.  **Run an example:**
    ```bash
    # Ensure you have python-dotenv installed (`uv pip install python-dotenv`)
    dotenv run uv run examples/code_agent/start.py

    Enter your task: Build an algorithm art about 3-body problem
    ```

3.  **Prefer Python over YAML?** Create the same agent defined in `examples/code_agent/code_agent.yaml` directly in code, create a new file `code_agent.py`:
    ```python
    import logging
    import os
    from pathlib import Path

    from nexau import Agent, AgentConfig, LLMConfig, Skill, Tool
    from nexau.archs.main_sub.execution.hooks import LoggingMiddleware

    from nexau.archs.tool.builtin import (
        glob,
        google_web_search,
        list_directory,
        read_file,
        read_many_files,
        replace,
        run_shell_command,
        search_file_content,
        web_fetch,
        write_file,
        write_todos,
    )

    logging.basicConfig(level=logging.INFO, format="%(asctime)s [%(name)s] %(levelname)s: %(message)s")

    base_dir = Path("examples/code_agent")

    # NexAU decouples the definition and implementation (binding) of tools
    tools = [
        Tool.from_yaml(base_dir / "tools/WebSearch.tool.yaml", binding=google_web_search),
        Tool.from_yaml(base_dir / "tools/WebFetch.tool.yaml", binding=web_fetch),
        Tool.from_yaml(base_dir / "tools/write_todos.tool.yaml", binding=write_todos),
        Tool.from_yaml(base_dir / "tools/search_file_content.tool.yaml", binding=search_file_content),
        Tool.from_yaml(base_dir / "tools/Glob.tool.yaml", binding=glob),
        Tool.from_yaml(base_dir / "tools/read_file.tool.yaml", binding=read_file),
        Tool.from_yaml(base_dir / "tools/write_file.tool.yaml", binding=write_file),
        Tool.from_yaml(base_dir / "tools/replace.tool.yaml", binding=replace),
        Tool.from_yaml(base_dir / "tools/run_shell_command.tool.yaml", binding=run_shell_command),
        Tool.from_yaml(base_dir / "tools/list_directory.tool.yaml", binding=list_directory),
        Tool.from_yaml(base_dir / "tools/read_many_files.tool.yaml", binding=read_many_files),
    ]

    # NexAU supports Skills (compatible with Claude Skills)
    skills = [
        Skill.from_folder(base_dir / "skills/theme-factory"),
        Skill.from_folder(base_dir / "skills/algorithmic-art"),
    ]

    agent_config = AgentConfig(
        name="nexau_code_agent",
        max_context_tokens=100000,
        system_prompt=str(base_dir / "system-workflow.md"),
        system_prompt_type="jinja",
        tool_call_mode="openai", # xml, openai or anthorpic
        llm_config=LLMConfig(
            temperature=0.7,
            max_tokens=4096,
            model=os.getenv("LLM_MODEL"),
            base_url=os.getenv("LLM_BASE_URL"),
            api_key=os.getenv("LLM_API_KEY"),
            api_type="openai_chat_completion", # support openai_chat_completion (default), openai_responses (especially for gpt-5-codex), anthropic_chat_completion
        ),
        tools=tools,
        skills=skills,
        middlewares=[
            LoggingMiddleware(
                model_logger="nexau_code_agent",
                tool_logger="nexau_code_agent",
                log_model_calls=True,
            ),
        ],
    )

    agent = Agent(config = agent_config)

    print(agent.run("Build an algorithm art about 3-body problem", context={"working_directory": os.getcwd()}))

    ```
    Run it with `dotenv run uv run code_agent.py`

4. **Use NexAU CLI to run**

    **Using the run-agent script (Recommended)**
    ```bash
    # One-liner to run any NexAU agent yaml config
    ./run-agent examples/code_agent/code_agent.yaml
    ```
    NexAU CLI supports multi-round human interaction, tool call traces and sub-agent traces, which makes agent debugging easier.
    ![NexAU CLI](assets/nexau_cli.jpeg)

```

### references/agent-yaml-reference.md

```markdown
# Agent YAML Configuration Reference

Complete field reference for NexAU agent YAML configuration files.

## Minimal Config

```yaml
type: agent
name: my_agent
system_prompt: ./systemprompt.md
llm_config:
  model: ${env.LLM_MODEL}
  base_url: ${env.LLM_BASE_URL}
  api_key: ${env.LLM_API_KEY}
tools:
  - name: read_file
    yaml_path: ./tools/read_file.tool.yaml
    binding: nexau.archs.tool.builtin.file_tools:read_file
```

## Full Config

```yaml
type: agent                          # Required. Must be "agent"
name: agent_name                     # Required. Unique identifier
description: What the agent does     # Optional. Human-readable description

# Context and iteration limits
max_context_tokens: 200000           # Max context window size (default: 200000)
max_iterations: 80                   # Max agent loop iterations (default: 50)

# System prompt
system_prompt: ./systemprompt.md     # Path to system prompt file (relative to YAML)
system_prompt_type: jinja            # "jinja" for template variables, "string" for plain text

# Tool calling format
tool_call_mode: openai               # "openai" | "xml" | "anthropic"

# LLM configuration
llm_config:
  model: ${env.LLM_MODEL}           # Model name/ID
  base_url: ${env.LLM_BASE_URL}     # API base URL
  api_key: ${env.LLM_API_KEY}       # API key
  max_tokens: 16000                  # Max output tokens per response
  temperature: 0.7                   # Sampling temperature (0.0-1.0)
  stream: False                      # Enable streaming (True/False)
  api_type: openai_chat_completion   # "openai_chat_completion" | "openai_responses" | "anthropic_chat_completion"

# Sandbox configuration
sandbox_config:
  type: local                        # Sandbox type
  _work_dir: ${env.SANDBOX_WORK_DIR} # Working directory for file/shell tools

# Tools
tools:
  - name: tool_name                  # Tool identifier
    yaml_path: ./tools/tool.tool.yaml  # Path to tool YAML (relative to agent YAML)
    binding: module.path:function     # Python import path to binding function

# Skills (folder-based)
skills:
  - ./skills/skill-name              # Path to skill folder (relative to agent YAML)

# Stop tools — tools that halt the agent loop when called
stop_tools: [complete_task]          # List of tool names

# Middlewares
middlewares: []                      # List of middleware instances

# Tracers
tracers:
  - import: nexau.archs.tracer.adapters.in_memory:InMemoryTracer
  # Or with params:
  - import: nexau.archs.tracer.adapters.langfuse:LangfuseTracer
    params:
      public_key: ${env.LANGFUSE_PUBLIC_KEY}
      secret_key: ${env.LANGFUSE_SECRET_KEY}
      host: https://us.cloud.langfuse.com
```

## Field Details

### `system_prompt_type`

| Value | Use When | Template Variables |
|-------|----------|-------------------|
| `string` | Plain text prompt, no variables | None |
| `jinja` | Need `{{ date }}`, `{{ username }}`, `{{ working_directory }}` | Passed via `context` dict in `agent.run()` |

### `tool_call_mode`

| Value | Use With |
|-------|----------|
| `openai` | OpenAI-compatible APIs (GPT, Claude via proxy, local models) |
| `xml` | XML-based tool calling |
| `anthropic` | Anthropic native API |

### `api_type`

| Value | Use With |
|-------|----------|
| `openai_chat_completion` | Standard OpenAI Chat Completions API (default) |
| `openai_responses` | OpenAI Responses API (for gpt-5-codex) |
| `anthropic_chat_completion` | Anthropic Messages API |

### `temperature` Guidelines

| Range | Use For |
|-------|---------|
| 0.0-0.3 | Precise tasks (code generation, structured output) |
| 0.3-0.5 | Balanced tasks (analysis, implementation) |
| 0.5-0.7 | Creative tasks (writing, brainstorming) |
| 0.7-1.0 | Highly creative tasks |

### `max_iterations` Guidelines

| Range | Use For |
|-------|---------|
| 20-50 | Simple single-purpose agents |
| 50-100 | Complex agents with multiple tools |
| 100-200 | Team leaders coordinating sub-agents |
| 200-300 | Long-running interactive agents |

### Environment Variable Substitution

Use `${env.VAR_NAME}` syntax in YAML values. The variable is resolved at config load time from the process environment.

```yaml
llm_config:
  model: ${env.LLM_MODEL}           # Reads os.environ["LLM_MODEL"]
  api_key: ${env.LLM_API_KEY}       # Reads os.environ["LLM_API_KEY"]
```

```

### assets/templates/agent.yaml

```yaml
# NexAU Agent YAML Config Template
# Copy this file and customize for your agent.

type: agent
name: my_agent                       # TODO: Replace with agent name
description: >-                      # TODO: Replace with agent description
  A brief description of what this agent does.
max_context_tokens: 200000
system_prompt: ./systemprompt.md
system_prompt_type: jinja            # Use "string" if no template variables needed
tool_call_mode: openai
max_iterations: 80                   # Adjust based on complexity

llm_config:
  model: ${env.LLM_MODEL}
  base_url: ${env.LLM_BASE_URL}
  api_key: ${env.LLM_API_KEY}
  max_tokens: 16000
  temperature: 0.7                   # 0.3 for precise, 0.7 for creative
  api_type: openai_chat_completion

sandbox_config:
  type: local
  _work_dir: ${env.SANDBOX_WORK_DIR}

tools:
  # File operations
  - name: read_file
    yaml_path: ./tools/read_file.tool.yaml
    binding: nexau.archs.tool.builtin.file_tools:read_file
  - name: write_file
    yaml_path: ./tools/write_file.tool.yaml
    binding: nexau.archs.tool.builtin.file_tools:write_file
  - name: replace
    yaml_path: ./tools/replace.tool.yaml
    binding: nexau.archs.tool.builtin.file_tools:replace
  # Search and navigation
  - name: search_file_content
    yaml_path: ./tools/search_file_content.tool.yaml
    binding: nexau.archs.tool.builtin.file_tools:search_file_content
  - name: glob
    yaml_path: ./tools/Glob.tool.yaml
    binding: nexau.archs.tool.builtin.file_tools:glob
  - name: list_directory
    yaml_path: ./tools/list_directory.tool.yaml
    binding: nexau.archs.tool.builtin.file_tools:list_directory
  # Shell
  - name: run_shell_command
    yaml_path: ./tools/run_shell_command.tool.yaml
    binding: nexau.archs.tool.builtin.shell_tools:run_shell_command
  # TODO: Add more tools as needed (web, session, custom)

# skills:
#   - ./skills/skill-name            # TODO: Add skills if needed

# stop_tools: [complete_task]        # TODO: Uncomment if using task-based workflow

middlewares: []

tracers:
  - import: nexau.archs.tracer.adapters.in_memory:InMemoryTracer

```

### references/builtin-tools-reference.md

```markdown
# Built-in Tools Reference

Catalog of all NexAU built-in tools with their binding paths and parameter summaries.

## File Tools

Module: `nexau.archs.tool.builtin.file_tools`

### read_file

Reads file content. Supports text, images, audio, and PDF.

```
Binding: nexau.archs.tool.builtin.file_tools:read_file
Parameters:
  - file_path (string, required): Path to the file
  - offset (number, optional): 0-based line number to start from
  - limit (number, optional): Max lines to read
```

### write_file

Writes content to a file. Creates parent directories if needed.

```
Binding: nexau.archs.tool.builtin.file_tools:write_file
Parameters:
  - file_path (string, required): Path to the file
  - content (string, required): Content to write
```

### replace

Performs string replacement in a file. Use for partial edits.

```
Binding: nexau.archs.tool.builtin.file_tools:replace
Parameters:
  - file_path (string, required): Path to the file
  - old_string (string, required): Text to find
  - new_string (string, required): Replacement text
```

### search_file_content

Searches for patterns in files using regex.

```
Binding: nexau.archs.tool.builtin.file_tools:search_file_content
Parameters:
  - pattern (string, required): Regex pattern to search
  - path (string, optional): Directory to search in
  - file_pattern (string, optional): Glob pattern to filter files
```

### glob

Finds files matching a glob pattern.

```
Binding: nexau.archs.tool.builtin.file_tools:glob
Parameters:
  - pattern (string, required): Glob pattern (e.g., "**/*.py")
  - path (string, optional): Base directory
```

### list_directory

Lists directory contents.

```
Binding: nexau.archs.tool.builtin.file_tools:list_directory
Parameters:
  - path (string, required): Directory path
```

### read_many_files

Reads multiple files at once.

```
Binding: nexau.archs.tool.builtin.file_tools:read_many_files
Parameters:
  - file_paths (array of strings, required): List of file paths
```

## Web Tools

Module: `nexau.archs.tool.builtin.web_tools`

### google_web_search

Searches the web using Google (requires SERPER_API_KEY).

```
Binding: nexau.archs.tool.builtin.web_tools:google_web_search
Parameters:
  - query (string, required): Search query
```

### web_fetch

Fetches and parses content from a URL.

```
Binding: nexau.archs.tool.builtin.web_tools:web_fetch
Parameters:
  - url (string, required): URL to fetch
  - prompt (string, optional): Extraction prompt
```

## Shell Tools

Module: `nexau.archs.tool.builtin.shell_tools`

### run_shell_command

Executes a shell command via `bash -c`.

```
Binding: nexau.archs.tool.builtin.shell_tools:run_shell_command
Parameters:
  - command (string, required): Bash command to execute
  - description (string, optional): Brief description of the command
  - is_background (boolean, optional): Run in background (default: false)
  - dir_path (string, optional): Working directory
```

Note: For synchronous-only execution (no background support), use the same binding but with a tool YAML that omits the `is_background` parameter.

## Session Tools

Module: `nexau.archs.tool.builtin.session_tools`

### write_todos

Writes/updates a todo list for task tracking.

```
Binding: nexau.archs.tool.builtin.session_tools:write_todos
Parameters:
  - todos (array, required): List of todo items with content and status
```

### complete_task

Marks the current task as completed and returns a result.

```
Binding: nexau.archs.tool.builtin.session_tools:complete_task
Parameters:
  - result (string, required): Task completion result/summary
```

### save_memory

Persists a key-value pair to agent memory.

```
Binding: nexau.archs.tool.builtin.session_tools:save_memory
Parameters:
  - key (string, required): Memory key
  - value (string, required): Memory value
```

### ask_user

Asks the user a question and waits for a response.

```
Binding: nexau.archs.tool.builtin.session_tools:ask_user
Parameters:
  - question (string, required): Question to ask the user
```

## Background Task Tools

### background_task_manage_tool

Manages background shell tasks (start, check status, kill).

```
Binding: nexau.archs.tool.builtin:background_task_manage_tool
```

## Common Tool Sets

### Minimal (file read/write only)

```yaml
tools:
  - name: read_file
    yaml_path: ./tools/read_file.tool.yaml
    binding: nexau.archs.tool.builtin.file_tools:read_file
  - name: write_file
    yaml_path: ./tools/write_file.tool.yaml
    binding: nexau.archs.tool.builtin.file_tools:write_file
```

### Standard (file + search + shell)

```yaml
tools:
  - name: read_file
    yaml_path: ./tools/read_file.tool.yaml
    binding: nexau.archs.tool.builtin.file_tools:read_file
  - name: write_file
    yaml_path: ./tools/write_file.tool.yaml
    binding: nexau.archs.tool.builtin.file_tools:write_file
  - name: replace
    yaml_path: ./tools/replace.tool.yaml
    binding: nexau.archs.tool.builtin.file_tools:replace
  - name: search_file_content
    yaml_path: ./tools/search_file_content.tool.yaml
    binding: nexau.archs.tool.builtin.file_tools:search_file_content
  - name: glob
    yaml_path: ./tools/Glob.tool.yaml
    binding: nexau.archs.tool.builtin.file_tools:glob
  - name: list_directory
    yaml_path: ./tools/list_directory.tool.yaml
    binding: nexau.archs.tool.builtin.file_tools:list_directory
  - name: run_shell_command
    yaml_path: ./tools/run_shell_command.tool.yaml
    binding: nexau.archs.tool.builtin.shell_tools:run_shell_command
```

### Full (all builtin tools)

Add web tools, session tools, and background task tools to the standard set. See `examples/code_agent/code_agent.yaml` for a complete example.

```

### references/tool-yaml-reference.md

```markdown
# Tool YAML Definition Reference

Complete reference for NexAU tool YAML definition files.

## Format

```yaml
type: tool                           # Required. Must be "tool"
name: tool_name                      # Required. Tool identifier
description: >-                      # Required. Detailed description of what the tool does
  Multi-line description of the tool's
  purpose, behavior, and return values.
input_schema:                        # Required. JSON Schema for tool parameters
  type: object
  properties:
    param_name:
      type: string                   # "string" | "number" | "boolean" | "array" | "object"
      description: What this parameter does
    optional_param:
      type: string
      description: An optional parameter
  required:                          # List of required parameter names
    - param_name
  additionalProperties: false        # Always set to false
  $schema: http://json-schema.org/draft-07/schema#
```

## Skill-Enabled Tools

To expose a tool as a discoverable skill:

```yaml
type: tool
name: tool_name
description: Tool description
as_skill: true
skill_description: Brief skill description for the registry
input_schema:
  # ... schema as above
```

## Parameter Types

### String

```yaml
param_name:
  type: string
  description: A text parameter
```

### Number

```yaml
param_name:
  type: number
  description: A numeric parameter
```

### Boolean

```yaml
param_name:
  type: boolean
  description: A true/false parameter
```

### Array

```yaml
param_name:
  type: array
  items:
    type: string
  description: A list of strings
```

### Enum

```yaml
param_name:
  type: string
  enum: [option_a, option_b, option_c]
  description: One of the allowed values
```

### Optional Parameters

Simply omit the parameter name from the `required` list. Add "(OPTIONAL)" to the description for clarity:

```yaml
properties:
  required_param:
    type: string
    description: This is required
  optional_param:
    type: string
    description: >-
      (OPTIONAL) This is optional. If not provided, defaults to X.
required:
  - required_param
```

## Tool Binding

In the agent YAML, tools are bound to Python functions:

```yaml
tools:
  - name: tool_name
    yaml_path: ./tools/tool_name.tool.yaml
    binding: module.path:function_name
```

The binding format is `python.module.path:function_name`. For builtin tools:

```
nexau.archs.tool.builtin.file_tools:read_file
nexau.archs.tool.builtin.web_tools:google_web_search
nexau.archs.tool.builtin.shell_tools:run_shell_command
nexau.archs.tool.builtin.session_tools:write_todos
```

For custom tools in the project:

```
custom_tools.my_module:my_function
```

## Custom Tool Implementation

The Python function signature must match the `input_schema` properties:

```python
def my_tool(param_name: str, optional_param: str = "default") -> str:
    """Tool description.

    Args:
        param_name: What this parameter does.
        optional_param: Optional parameter description.

    Returns:
        Result as a string.
    """
    # Implementation
    return result
```

### Accessing Agent State

To access the sandbox (file system, working directory), add `agent_state: AgentState`:

```python
from nexau.archs.main_sub.agent_state import AgentState

def my_tool(param_name: str, agent_state: AgentState) -> str:
    sandbox = agent_state.sandbox
    work_dir = sandbox.work_dir
    # ... use sandbox for file operations
```

Note: `agent_state` is injected automatically — do NOT include it in the tool's `input_schema`.

## Extra Kwargs (Preset Parameters)

To preset fixed arguments that callers don't need to provide:

```yaml
tools:
  - name: my_tool
    yaml_path: ./tools/my_tool.tool.yaml
    binding: my_module:my_function
    extra_kwargs:
      api_key: ${env.MY_API_KEY}
      base_url: https://api.example.com
```

Call-time arguments with the same name override preset values.

```

### assets/templates/tool.tool.yaml

```yaml
# NexAU Tool YAML Definition Template
# Copy this file and customize for your tool.

type: tool
name: my_tool                        # TODO: Replace with tool name
description: >-                      # TODO: Replace with detailed description
  Describe what this tool does, what it returns,
  and any important behavior notes.
input_schema:
  type: object
  properties:
    param_name:                      # TODO: Replace with actual parameter
      type: string
      description: Description of this parameter.
    optional_param:                  # TODO: Replace or remove
      type: string
      description: >-
        (OPTIONAL) Description of this optional parameter.
        If not provided, defaults to X.
  required:
    - param_name                     # TODO: List required parameters
  additionalProperties: false
  $schema: http://json-schema.org/draft-07/schema#

```

### references/system-prompt-guide.md

```markdown
# System Prompt Writing Guide

Conventions and patterns for writing effective NexAU agent system prompts.

## Structure

A well-structured system prompt follows this order:

1. Role description (who the agent is)
2. Workflow (numbered steps)
3. Guidelines and constraints
4. Template variables (at the bottom)

## Role Description

Start with a clear, concise statement of the agent's identity and purpose:

```markdown
You are a [Role Name] agent specialized in [domain/task].

# Role

[1-2 sentences describing what the agent does and its core objective.]
```

## Workflow

Define the agent's step-by-step process using numbered lists:

```markdown
# Workflow

1. [First step — what to do and why]
2. [Second step]
3. [Third step]
4. [Continue as needed]
```

Keep steps actionable and specific. Vague steps like "analyze the problem" produce vague behavior. Prefer "Read the requirements document at the path provided by the user" instead.

## Guidelines and Constraints

Add rules the agent must follow:

```markdown
# Guidelines

- Always read files before modifying them
- Use `replace` for partial edits, `write_file` for new files
- Follow the project's coding conventions
- Include docstrings following the RFC convention
- Use numbered step comments in Chinese for logic blocks
```

## Template Variables

When `system_prompt_type: jinja` is set in the agent YAML, these variables are available:

```markdown
Date: {{ date }}
Username: {{ username }}
Working Dir: {{ working_directory }}
```

Always place these at the bottom of the system prompt. They are populated at runtime via the `context` dict passed to `agent.run()`.

## Patterns by Agent Type

### Code Agent

```markdown
You are a software engineering agent.

# Role
Implement, debug, and refactor code based on user requests.

# Workflow
1. Read and understand the user's request
2. Explore the codebase to understand existing patterns
3. Plan the implementation approach
4. Implement changes using write_file and replace tools
5. Verify changes compile/run correctly
6. Summarize what was done

# Guidelines
- Read files before modifying them
- Follow existing code style and patterns
- Write clean, well-documented code
- Test changes when possible
```

### Research Agent

```markdown
You are a research agent.

# Role
Find, analyze, and synthesize information from the web and local files.

# Workflow
1. Understand the research question
2. Search the web for relevant information
3. Read and analyze sources
4. Synthesize findings into a clear summary
5. Cite sources

# Guidelines
- Use multiple sources to verify information
- Distinguish facts from opinions
- Provide citations for claims
```

### Team Leader Agent

```markdown
You are a team leader agent coordinating a group of specialized agents.

# Role
Break down complex tasks, assign work to team members, review deliverables, and ensure quality.

# Workflow
1. Understand the user's request
2. Break down into subtasks
3. Assign tasks to appropriate team members
4. Monitor progress and review deliverables
5. Iterate based on feedback
6. Present final result to the user

# Guidelines
- Assign tasks based on agent specializations
- Review deliverables before accepting
- Communicate clearly with both user and team members
```

### Task-Based Agent (with stop_tools)

For agents that complete discrete tasks and stop:

```markdown
# Workflow
1. Check available tasks using list_tasks
2. Claim a task using claim_task
3. Execute the task
4. Write deliverable to the task's deliverable_path
5. Mark task as completed using complete_task
6. Check for more tasks
```

## Tips

- Be specific about tool usage — tell the agent which tools to use for which steps
- Include error handling guidance — what to do when things go wrong
- Reference file paths and formats the agent will encounter
- For team agents, describe how to communicate with teammates (via messages, shared files, etc.)
- Keep the prompt focused — a prompt that tries to cover everything covers nothing well

```

### assets/templates/systemprompt.md

```markdown
# TODO: Replace with agent role description
You are a [Role Name] agent specialized in [domain/task].

# Role

[Describe the agent's core objective and what it does.]

# Workflow

1. [First step — be specific about what to do]
2. [Second step]
3. [Third step]
4. [Continue as needed]

# Guidelines

- [Guideline 1]
- [Guideline 2]
- [Guideline 3]

Date: {{ date }}
Username: {{ username }}
Working Dir: {{ working_directory }}

```

### assets/templates/start.py

```python
# NexAU Standalone Agent Entry Point Template

from __future__ import annotations

import logging
import os
from datetime import datetime
from pathlib import Path

from nexau import Agent

logging.basicConfig(level=logging.INFO)

SCRIPT_DIR = Path(__file__).parent


def get_date() -> str:
    return datetime.now().strftime("%Y-%m-%d %H:%M:%S")


def main() -> None:
    """Entry point for the agent."""
    # 1. Load agent from YAML configuration
    agent = Agent.from_yaml(config_path=SCRIPT_DIR / "agent.yaml")  # TODO: Replace with actual YAML filename

    # 2. Get sandbox working directory
    sandbox = agent.sandbox_manager.instance
    work_dir = str(sandbox.work_dir) if sandbox else os.getcwd()

    # 3. Get user input
    user_message = input("Enter your task: ")

    # 4. Run the agent
    response = agent.run(
        message=user_message,
        context={
            "date": get_date(),
            "username": os.getenv("USER", "user"),
            "working_directory": work_dir,
        },
    )
    print(response)


if __name__ == "__main__":
    main()

```

### builtin_tools/tools/read_file.tool.yaml

```yaml
type: tool
name: read_file
description: >-
  Reads and returns the content of a specified file. If the file is large, the
  content will be truncated. The tool's response will clearly indicate if
  truncation has occurred and will provide details on how to read more of the
  file using the 'offset' and 'limit' parameters. Handles text, images (PNG,
  JPG, GIF, WEBP, SVG, BMP), audio files (MP3, WAV, AIFF, AAC, OGG, FLAC),
  video files (MP4, AVI, MOV, MKV, WEBM, FLV, WMV, M4V), and PDF files.
  Video files are processed by extracting key frames via ffmpeg. For text
  files, it can read specific line ranges.
input_schema:
  type: object
  properties:
    file_path:
      type: string
      description: The path to the file to read.
    offset:
      type: number
      description: >-
        Optional: For text files, the 0-based line number to start reading from.
        Requires 'limit' to be set. Use for paginating through large files.
    limit:
      type: number
      description: >-
        Optional: For text files, maximum number of lines to read. Use with
        'offset' to paginate through large files. If omitted, reads the entire
        file (if feasible, up to a default limit).
    image_detail:
      type: string
      enum: [low, high, auto]
      description: >-
        Optional: For image files, the detail level hint passed to the LLM.
        "low" uses fewer tokens, "high" preserves detail, "auto" lets the LLM
        decide. Default: "auto".
    image_max_size:
      type: number
      description: >-
        Optional: For image files, maximum width in pixels. Images wider than
        this are downscaled (preserving aspect ratio) via ffmpeg before
        encoding. Reduces token usage for large images. Requires ffmpeg.
    video_frame_interval:
      type: number
      description: >-
        Optional: For video files, seconds between extracted key frames.
        Default: 5.
    video_max_frames:
      type: number
      description: >-
        Optional: For video files, maximum number of frames to return.
        Default: 10.
    video_frame_width:
      type: number
      description: >-
        Optional: For video files, width in pixels for extracted frames
        (preserving aspect ratio). Smaller values reduce token usage.
        Default: original resolution.
  required:
    - file_path
  additionalProperties: false
  $schema: http://json-schema.org/draft-07/schema#

```

### builtin_tools/tools/write_file.tool.yaml

```yaml
type: tool
name: write_file
description: >-
  Writes content to a specified file in the local filesystem.

  The user has the ability to modify `content`. If modified, this will be stated
  in the response.

  Usage:
  - Creates parent directories if they don't exist
  - Overwrites the file if it already exists
  - Use this for creating new files or completely replacing file content
  - For partial edits, use the 'replace' tool instead
input_schema:
  type: object
  properties:
    file_path:
      type: string
      description: The path to the file to write to.
    content:
      type: string
      description: The content to write to the file.
  required:
    - file_path
    - content
  additionalProperties: false
  $schema: http://json-schema.org/draft-07/schema#

```

### builtin_tools/tools/replace.tool.yaml

```yaml
type: tool
name: replace
description: >-
  Replaces text within a file. By default, replaces a single occurrence, but can
  replace multiple occurrences when `expected_replacements` is specified. This
  tool requires providing significant context around the change to ensure
  precise targeting. Always use the read_file tool to examine the file's current
  content before attempting a text replacement.

  The user has the ability to modify the `new_string` content. If modified, this
  will be stated in the response.

  Expectation for required parameters:

  1. `old_string` MUST be the exact literal text to replace (including all
  whitespace, indentation, newlines, and surrounding code etc.).

  2. `new_string` MUST be the exact literal text to replace `old_string` with
  (also including all whitespace, indentation, newlines, and surrounding code
  etc.). Ensure the resulting code is correct and idiomatic and that `old_string`
  and `new_string` are different.

  3. `instruction` is the detailed instruction of what needs to be changed. Make
  it specific and detailed so developers or large language models can understand
  what needs to be changed and perform the changes on their own if necessary.

  4. NEVER escape `old_string` or `new_string`, that would break the exact
  literal text requirement.

  **Important:** If ANY of the above are not satisfied, the tool will fail.
  CRITICAL for `old_string`: Must uniquely identify the single instance to
  change. Include at least 3 lines of context BEFORE and AFTER the target text,
  matching whitespace and indentation precisely. If this string matches multiple
  locations, or does not match exactly, the tool will fail.

  5. Prefer to break down complex and long changes into multiple smaller atomic
  calls to this tool. Always check the content of the file after changes or not
  finding a string to match.

  **Multiple replacements:** Set `expected_replacements` to the number of
  occurrences you want to replace. The tool will replace ALL occurrences that
  match `old_string` exactly. Ensure the number of replacements matches your
  expectation.
input_schema:
  type: object
  properties:
    file_path:
      type: string
      description: The path to the file to modify.
    instruction:
      type: string
      description: >-
        A clear, semantic instruction for the code change, acting as a
        high-quality prompt for an expert LLM assistant. It must be
        self-contained and explain the goal of the change.

        A good instruction should concisely answer:
        1. WHY is the change needed?
        2. WHERE should the change happen?
        3. WHAT is the high-level change?
        4. WHAT is the desired outcome?

        **GOOD Example:** "In the 'calculateTotal' function, correct the sales
        tax calculation by updating the 'taxRate' constant from 0.05 to 0.075 to
        reflect the new regional tax laws."

        **BAD Examples:**
        - "Change the text." (Too vague)
        - "Fix the bug." (Doesn't explain the bug or the fix)
    old_string:
      type: string
      description: >-
        The exact literal text to replace, preferably unescaped. For single
        replacements (default), include at least 3 lines of context BEFORE and
        AFTER the target text, matching whitespace and indentation precisely.
        If this string is not the exact literal text (i.e. you escaped it) or
        does not match exactly, the tool will fail.
    new_string:
      type: string
      description: >-
        The exact literal text to replace `old_string` with, preferably
        unescaped. Provide the EXACT text. Ensure the resulting code is correct
        and idiomatic.
    expected_replacements:
      type: number
      minimum: 1
      description: >-
        Number of replacements expected. Defaults to 1 if not specified. Use
        when you want to replace multiple occurrences.
  required:
    - file_path
    - instruction
    - old_string
    - new_string
  additionalProperties: false
  $schema: http://json-schema.org/draft-07/schema#

```

### builtin_tools/tools/search_file_content.tool.yaml

```yaml
type: tool
name: search_file_content
description: >-
  Searches for a regular expression pattern within the content of files in a
  specified directory (or current working directory). Can filter files by a glob
  pattern. Returns the lines containing matches, along with their file paths and
  line numbers.

  Uses multiple search strategies: git grep (if in git repo) -> system grep ->
  JavaScript fallback. Results are limited to 20,000 matches for performance.
input_schema:
  type: object
  properties:
    pattern:
      type: string
      description: >-
        The regular expression (regex) pattern to search for within file
        contents (e.g., 'function\\s+myFunction', 'import\\s+\\{.*\\}\\s+from\\s+.*').
    dir_path:
      type: string
      description: >-
        Optional: The absolute path to the directory to search within. If
        omitted, searches the current working directory.
    include:
      type: string
      description: >-
        Optional: A glob pattern to filter which files are searched (e.g.,
        '*.js', '*.{ts,tsx}', 'src/**'). If omitted, searches all files
        (respecting potential global ignores).
  required:
    - pattern
  additionalProperties: false
  $schema: http://json-schema.org/draft-07/schema#

```

### builtin_tools/tools/Glob.tool.yaml

```yaml
type: tool
name: glob
description: >-
  Efficiently finds files matching specific glob patterns (e.g., `src/**/*.ts`,
  `**/*.md`), returning absolute paths sorted by modification time (newest
  first). Ideal for quickly locating files based on their name or path
  structure, especially in large codebases.
input_schema:
  type: object
  properties:
    pattern:
      type: string
      description: >-
        The glob pattern to match against (e.g., '**/*.py', 'docs/*.md').
    dir_path:
      type: string
      description: >-
        Optional: The absolute path to the directory to search within. If
        omitted, searches the root directory.
    case_sensitive:
      type: boolean
      description: >-
        Optional: Whether the search should be case-sensitive. Defaults to false.
    respect_git_ignore:
      type: boolean
      description: >-
        Optional: Whether to respect .gitignore patterns when finding files.
        Only available in git repositories. Defaults to true.
    respect_gemini_ignore:
      type: boolean
      description: >-
        Optional: Whether to respect .geminiignore patterns when finding files.
        Defaults to true.
  required:
    - pattern
  additionalProperties: false
  $schema: http://json-schema.org/draft-07/schema#

```