Dale herramientas de verdad
La suma era solo una demostración. En esta sección pondremos herramientas realmente útiles: leer y escribir archivos, ejecutar comandos, capturar páginas web. Al terminar tendrás la primera versión funcional de myagent y sabrás cómo evitar que cause desastres.
Descarga el código completo myagent.zip, descomprímelo y entra en el directorio myagent. En esta sección veremos la primera mitad de agent.py.
Una herramienta es simplemente una función normal
def list_dir(path="."):
return "\n".join(sorted(p.name + ("/" if p.is_dir() else "") for p in Path(path).iterdir()))
def read_file(path):
return Path(path).read_text(encoding="utf-8")[:8000]
def fetch_url(url):
req = urllib.request.Request(url, headers={"User-Agent": "myagent/1.0"})
html = urllib.request.urlopen(req, timeout=20).read().decode("utf-8", "ignore")
text = re.sub(r"<script.*?</script>|<style.*?</style>|<[^>]+>", " ", html, flags=re.S)
return re.sub(r"\s+", " ", text)[:6000]Fíjate en que el valor de retorno de cada herramienta está truncado (8000 caracteres, 6000 caracteres). Los resultados de las herramientas se insertan tal cual en la conversación, y un archivo grande puede desbordar el contexto del modelo.
Herramientas peligrosas: preguntar primero al usuario
Escribir archivos y ejecutar comandos modifican tu computadora. Pregunta primero dentro de la función:
def ask(question): # 危险操作先问人
return input(f"\n⚠️ {question} [y/N] ").strip().lower() == "y"
def run_shell(command):
if not ask(f"运行命令:{command}"):
return "用户拒绝了运行。"
r = subprocess.run(command, shell=True, capture_output=True, text=True, timeout=60)
return (r.stdout + r.stderr)[-4000:] or f"(没有输出,退出码 {r.returncode})"Un rechazo tampoco es un error, sino un mensaje de "el usuario rechazó la ejecución" que se devuelve al modelo, para que busque otra forma o te pregunte a ti.
Lo probamos de verdad: le pedimos que "elimine la carpeta worklog" y en la confirmación escribimos n:
[1] list_dir({"path": "./worklog"})
[2] run_shell({"command": "rm -rf ./worklog"})
⚠️ Ejecutar comando: rm -rf ./worklog [y/N] n
Agent: ¿Está seguro de que desea eliminar la carpeta worklog? Esta operación borrará los archivos de forma permanente y no se podrán recuperar. Se recomienda hacer una copia de seguridad primero...La carpeta sigue ahí. Por eso en la sección anterior dijimos que "el modelo solo hace peticiones, el poder de ejecución está en tus manos": el control de permisos se escribe aquí.
Decirle al modelo qué herramientas hay
Cada herramienta lleva una descripción. Con muchas herramientas, escribir el JSON Schema a mano es muy engorroso; escribe una pequeña función que lo genere:
def spec(tool_name, desc, **params):
return {"type": "function", "function": {"name": tool_name, "description": desc, "parameters": {
"type": "object", "properties": {k: {"type": "string", "description": v} for k, v in params.items()},
"required": list(params)}}}
TOOLS = [
spec("list_dir", "列出目录里的文件", path="目录路径"),
spec("read_file", "读取一个文本文件的内容", path="文件路径"),
spec("write_file", "写入文本文件(会先请用户确认)", path="文件路径", content="完整内容"),
spec("run_shell", "在终端运行一条命令(会先请用户确认)", command="要运行的命令"),
spec("fetch_url", "抓取网页并返回纯文本", url="网址"),
]En la primera versión que escribimos, el primer parámetro de esta función se llamaba name, y spec("load_skill", ..., name="技能名") daba directamente el error got multiple values for argument 'name': los parámetros de la herramienta en sí también se llamaban name. Así que lo cambiamos a tool_name.
Ejecútalo
python agent.py "看看 worklog 文件夹里有哪些文件"Deberías ver:
[1] list_dir({"path": "worklog"})
Agent: la carpeta worklog contiene los siguientes archivos:
- 11-16.txt
- 11-18.txt
- 11-20.txtEl modelo comete errores, así que hay que devolverle los errores
En esa ejecución real de la página de inicio del curso, la primera vez que el modelo leyó un archivo escribió /worklog/11-16.txt (con una barra diagonal extra al principio) y obtuvo:
出错了:FileNotFoundError: [Errno 2] No such file or directory: '/worklog/11-16.txt'Como devolvimos el error tal cual, en el siguiente paso fue a mirar con list_dir y luego leyó correctamente con ./worklog/11-16.txt. Si el programa hubiera fallado aquí, toda la tarea se habría perdido.
Anthropic menciona en «Building effective agents» que dedican más tiempo a pulir las herramientas que a pulir los prompts, por ejemplo, haciendo que las herramientas exijan rutas absolutas. Cuanto más claras sean las descripciones de las herramientas y la información que devuelven, menos errores comete el modelo.
BuscarAl diseñar herramientas…
Toca uno para ver.
Pon a prueba tus conocimientosSi el usuario rechaza rm -rf al confirmar, ¿qué debe hacer el programa?
Compruébalo
- Logré ejecutar
list_diry vi la lista de archivos - Probé rechazar una vez
run_shelly los archivos quedaron intactos - Puedo enunciar los cuatro puntos clave del diseño de herramientas
Siguiente sección: Memoria: que recuerde el contexto.