Interfaces de herramientas para programar (Read, Edit, Bash)

¿Qué herramientas necesita un agente de código?

read_file

def read_file(path: str, start_line: int = 0, end_line: int | None = None) -> str:
    with open(path) as f:
        lines = f.readlines()
    return ''.join(lines[start_line:end_line])

# --- demo ---
with open('demo_source.py', 'w', encoding='utf-8') as f:
    f.write('line0\nline1\nline2\nline3\nline4\n')

snippet = read_file('demo_source.py', start_line=1, end_line=3)
print('Lines 1-2 of demo_source.py:')
print(snippet)

Las lecturas por rango de líneas ahorran tokens

edit_file (reemplazo de cadenas)

def edit_file(path: str, old_string: str, new_string: str):
    contents = read_file(path)
    occurrences = contents.count(old_string)
    if occurrences == 0:
        raise ValueError('old_string not found')
    if occurrences > 1:
        raise ValueError('old_string is not unique')
    contents = contents.replace(old_string, new_string)
    with open(path, 'w') as f:
        f.write(contents)

Por qué usar reemplazo de cadenas en lugar de diferencias

write_file

def write_file(path: str, content: str):
    os.makedirs(os.path.dirname(path), exist_ok=True)
    with open(path, 'w') as f:
        f.write(content)

bash

def bash(command: str, timeout: int = 60) -> dict:
    import subprocess
    try:
        result = subprocess.run(command, shell=True, capture_output=True, text=True, timeout=timeout)
        return {'stdout': result.stdout[-5000:], 'stderr': result.stderr[-5000:], 'exit_code': result.returncode}
    except subprocess.TimeoutExpired:
        return {'error': 'timeout', 'exit_code': -1}

# --- demo ---
result = bash("echo hello from the sandboxed shell")
print(f"exit_code={result['exit_code']}")
print(f"stdout={result['stdout'].strip()!r}")

Aísle la herramienta bash

Trunque las salidas largas

stderr = 'error line\n' * 1000

if len(stderr) > 5000:
    stderr = '...[truncated]...' + stderr[-5000:]

print(f'Truncated stderr length: {len(stderr)}')

search / grep

def grep(pattern: str, path: str = '.', file_glob: str = '**/*') -> list[str]:
    matches = []
    for f in glob(file_glob, recursive=True):
        for i, line in enumerate(open(f)):
            if re.search(pattern, line):
                matches.append(f'{f}:{i+1}: {line.rstrip()}')
    return matches[:50]

list_files

def list_files(path: str = '.') -> list[str]:
    return [p for p in glob(f'{path}/**', recursive=True) if os.path.isfile(p)][:200]

Opcional: herramientas AST

def find_function(name: str, path: str):
    tree = ast.parse(open(path).read())
    for node in ast.walk(tree):
        if isinstance(node, ast.FunctionDef) and node.name == name:
            return ast.unparse(node)

Las descripciones de las herramientas son lo más importante aquí

description='Edit a file by replacing a unique string. The old_string MUST appear exactly once in the file. Reads the file first to validate. Use this for any code change in an existing file.'

Ese es todo el conjunto de herramientas

Patrón de edición

Repaso