Common Production Tools: Files, Web, Code

~38 min · files, web, sandbox, code-execution

Level 0Observer

0 XP0/40 lessons0/12 achievements

0/100 XP to next level100 XP to go0% complete

Agent에게 필요한 건 지루한 손이야

화려한 부분은 model choice야. 유용한 부분은 file을 읽고, web을 검색하고, URL을 fetch하고, draft를 쓰고, test를 돌리고, workspace를 박살내지 않고 failure를 보고하는 toolbelt다. 많은 agent product는 slogan보다 tool quality에서 갈린다.

read, write, execute를 분리해

list, read, write, delete, shell 실행을 한 vague file_tool에 몰아넣지 마. blast radius로 tool을 쪼개. read tool은 넓어도 되고, write tool은 scope가 있어야 하고, execute tool은 sandbox, timeout, output cap, approval이 필요해.

Tool result는 dump가 아니라 pointer여야 해

search tool은 id, title, URL, snippet, confidence를 돌려줘야지 웹페이지 전체를 토하면 안 돼. file search는 path와 match range를 돌려줘. 모델이 자격을 얻으면 다음 tool이 full content를 가져오면 된다.

Code

File tools with scoped writes·python

from pathlib import Path

WORKSPACE = Path("/workspace").resolve()

def resolve_safe(path: str) -> Path:
    target = (WORKSPACE / path).resolve()
    if not str(target).startswith(str(WORKSPACE)):
        raise PermissionError("Path escapes workspace")
    return target

def read_file(path: str, max_chars: int = 12000) -> dict:
    target = resolve_safe(path)
    return {"path": str(target), "content": target.read_text()[:max_chars]}

def write_draft(path: str, content: str) -> dict:
    target = resolve_safe(path)
    if not str(target).endswith(".md"):
        raise PermissionError("write_draft only writes markdown")
    target.parent.mkdir(parents=True, exist_ok=True)
    target.write_text(content)
    return {"path": str(target), "chars": len(content), "changed_state": True}

Web tools with result envelopes·python

def web_search(query: str, max_results: int = 5) -> dict:
    raw = search_provider(query, max_results=max_results)
    return {
        "query": query,
        "results": [
            {
                "id": f"r{i}",
                "title": item["title"],
                "url": item["url"],
                "snippet": item["snippet"][:240],
            }
            for i, item in enumerate(raw[:max_results])
        ],
        "next_action": "Use fetch_url(url) for the most relevant official source.",
    }

Code execution needs a real sandbox·python

import subprocess, tempfile, textwrap

def run_python_sandboxed(code: str, timeout: int = 10) -> dict:
    with tempfile.NamedTemporaryFile("w", suffix=".py", delete=False) as f:
        f.write(textwrap.dedent(code))
        filename = f.name
    result = subprocess.run(
        ["python", filename],
        text=True,
        capture_output=True,
        timeout=timeout,
    )
    return {
        "exit_code": result.returncode,
        "stdout": result.stdout[-4000:],
        "stderr": result.stderr[-4000:],
    }

External links

Exercise

agent용 file system API를 세 개 tool로 설계해봐. read tool 하나, scoped write tool 하나, approval-required destructive tool 하나.

Hint

blast radius가 다르면 tool도 달라야 해. mega-tool 뒤에 숨기지 마.

Progress

Progress is local-only — sign in to sync across devices.

← PreviousTool Result: 작고, 구조적이고, 다음 행동이 보이게 Next →권한, 샌드박스, 사람 승인

이 페이지에서 버그를 발견하셨거나 피드백이 있으세요?문제 신고

🔔 답글 알림 (로그인 필요)

로그인 — 댓글을 남기려면 로그인해 주세요.

아직 댓글이 없어요. 첫 댓글을 남겨보세요.