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

# Built-in Tools

> Tools that ship with GitAgent — web search, file operations, code execution, and more.

GitAgent ships with a set of built-in tools available in every agent without any installation. Enable them in `agent.yaml` or reference them directly in skills.

## Enabling built-in tools

```yaml theme={null}
# agent.yaml
tools:
  web_search: true
  file_ops: true
  code_exec: false      # disabled by default — opt in explicitly
  http: true
```

Or use them directly in a skill:

```python theme={null}
from gitagent.tools import web_search, read_file

@skill(name="research", description="Search the web for information")
def research(query: str) -> str:
    results = web_search(query, num_results=5)
    return "\n".join(r["snippet"] for r in results)
```

## Available tools

### `web_search`

Search the web using a configured search provider.

```python theme={null}
from gitagent.tools import web_search

results = web_search(
    query="latest AI research papers 2024",
    num_results=10,         # default: 5
    provider="serper"       # serper | serpapi | brave | duckduckgo
)
# Returns: list of {title, url, snippet}
```

Configure the provider in `agent.yaml`:

```yaml theme={null}
tools:
  web_search:
    provider: serper
    api_key: ${SERPER_API_KEY}
```

***

### `fetch_url`

Fetch the content of a URL and return it as text.

```python theme={null}
from gitagent.tools import fetch_url

content = fetch_url(
    url="https://example.com/article",
    extract_text=True,      # strip HTML, return plain text
    max_chars=5000          # truncate long pages
)
```

***

### `read_file`

Read a file from the local filesystem (relative to the agent directory).

```python theme={null}
from gitagent.tools import read_file

content = read_file("data/report.txt")
```

By default, only files within the agent directory can be read. Override the allowed paths in `agent.yaml`:

```yaml theme={null}
tools:
  file_ops:
    allowed_paths:
      - ./data/
      - /tmp/agent-workspace/
```

***

### `write_file`

Write content to a file.

```python theme={null}
from gitagent.tools import write_file

write_file("output/summary.md", content="# Summary\n\n...")
```

***

### `list_files`

List files in a directory.

```python theme={null}
from gitagent.tools import list_files

files = list_files("data/", pattern="*.csv")
```

***

### `run_code`

Execute a Python code snippet in a sandboxed environment. The sandbox has no network access and no filesystem access outside the agent's workspace.

```python theme={null}
from gitagent.tools import run_code

result = run_code("""
import json
data = [1, 2, 3, 4, 5]
print(json.dumps({"mean": sum(data) / len(data)}))
""")
# result.stdout, result.stderr, result.exit_code
```

<Warning>
  `run_code` is disabled by default. Enable it explicitly in `agent.yaml` with `tools.code_exec: true`. Only enable it for agents where you fully control the input.
</Warning>

***

### `http_request`

Make an HTTP request to any URL.

```python theme={null}
from gitagent.tools import http_request

response = http_request(
    method="POST",
    url="https://api.example.com/data",
    headers={"Authorization": "Bearer token"},
    json={"key": "value"}
)
# response.status_code, response.json(), response.text
```

***

### `memory_read` / `memory_write`

Read from and write to the agent's persistent memory. These tools wrap the memory provider configured in `agent.yaml`.

```python theme={null}
from gitagent.tools import memory_read, memory_write

# Write a fact
memory_write("user_preference", "prefers bullet-point summaries")

# Read it back in a future run
pref = memory_read("user_preference")
```

***

### `call_agent`

Invoke another GitAgent as a sub-agent.

```python theme={null}
from gitagent.tools import call_agent

result = call_agent(
    agent_path="./agents/researcher",   # path to another agent
    prompt="Research quantum computing advances in 2024"
)
```

The sub-agent runs with its own context but can share memory if configured.

## Configuring tool defaults

```yaml theme={null}
# agent.yaml
tools:
  web_search:
    provider: serper
    api_key: ${SERPER_API_KEY}
    num_results: 10

  fetch_url:
    max_chars: 8000
    extract_text: true
    user_agent: "GitAgent/0.8"

  http:
    timeout: 30
    max_redirects: 5
    allowed_domains:          # restrict to specific domains
      - api.github.com
      - api.openai.com

  code_exec:
    timeout: 10               # max execution time in seconds
    memory_mb: 128            # max memory
```