Habilitar herramientas de edición de archivos, Bash y Web en el SDK del Agente
El SDK del Agente Claude incluye cuatro familias de herramientas integradas listas para usar: edición de archivos, ejecución de bash, búsqueda web y obtención web.
//
Busca en todas las páginas de la documentación
El SDK del Agente Claude incluye cuatro familias de herramientas integradas listas para usar: edición de archivos, ejecución de bash, búsqueda web y obtención web.
Ninguna de ellas está activada por defecto de forma sin ámbito; usted elige cuáles puede alcanzar un agente y, a menudo, hasta dónde puede llegar cada una, antes de llamar a query().
Las herramientas integradas son lo que permite que el bucle de uso de herramientas cambie archivos, ejecute comandos o obtenga información de la web en lugar de solo producir texto.
Cada familia de herramientas tiene su propia superficie de configuración, no solo un interruptor de encendido/apagado, por lo que "habilitar bash" y "habilitar bash sin restricciones" son dos decisiones diferentes.
Acertar con esto es importante porque cada herramienta que habilita es algo que el bucle puede invocar por sí solo, sujeto únicamente al modo de permisos y puntos de control que haya superpuesto.
Esta página cubre cómo habilitar y acotar cada familia de herramientas integradas, y cómo interactúan con los modos de permisos del SDK.
Tarjeta de receta de referencia rápida, lista para copiar y pegar.
from claude_agent_sdk import query, AgentOptions
options = AgentOptions(
allowed_tools=["file_edit", "bash", "web_search", "web_fetch"],
cwd="/path/to/project",
permission_mode="default",
)
async for message in query(
prompt="Actualiza el changelog y verifica que las pruebas sigan pasando.",
options=options,
):
print(message)Cuándo recurrir a esto:
permission_mode como red de seguridad.cwd.import asyncio
from claude_agent_sdk import query, AgentOptions
async def run_release_notes_agent(repo_path: str) -> None:
options = AgentOptions(
cwd=repo_path,
allowed_tools=["bash", "file_edit", "web_fetch"],
# bash está limitado a comandos de inspección de solo lectura que el agente necesita
# para recopilar contexto; no se le da web_search ya que la tarea
# solo necesita obtener una URL conocida, no buscar en la web abierta.
tool_config={
"bash": {"allowed_commands": ["git log", "git diff", "git status"]},
},
permission_mode="default",
)
prompt = (
"Lee el log de git desde la última etiqueta, obtén el issue vinculado "
"para cada commit desde https://api.example.com/issues/{id}, y "
"escribe un RELEASE_NOTES.md resumiendo los cambios."
)
async for message in query(prompt=prompt, options=options):
if message.get("type") == "text":
print(message["text"], end="", flush=True)
elif message.get("type") == "tool_call":
print(f"\n[llamada a herramienta: {message['tool_name']}]")
asyncio.run(run_release_notes_agent("/home/dev/my-project"))Lo que esto demuestra:
bash, file_edit, web_fetch) para una tarea que realmente necesita leer historial, obtener datos externos y escribir un archivo.allowed_commands en lugar de conceder acceso de shell sin restricciones.web_search porque la tarea solo necesita obtener URLs conocidas, no buscar en la web.allowed_tools se evalúa antes del paso de decisión del bucle; un nombre de herramienta que no está en la lista es invisible para el modelo, no simplemente bloqueado en tiempo de ejecución.file_edit cubre la lectura y escritura de archivos bajo cwd; algunas versiones del SDK le permiten restringirlo aún más a rutas o patrones específicos a través de tool_config.bash ejecuta comandos de shell en el directorio de trabajo; acotarlo a una lista de allowed_commands (o una lista de denegación, según la versión del SDK) lo limita a prefijos de comandos específicos en lugar de un shell abierto.web_search consulta un índice de búsqueda y devuelve resultados que el modelo puede procesar; web_fetch recupera el contenido de una URL específica. Son herramientas separadas porque "buscar en la web" y "obtener esta página" tienen perfiles de riesgo y costo diferentes.permission_mode opera independientemente de allowed_tools: el ámbito decide qué es alcanzable en absoluto, el modo de permisos decide si una llamada permitida y alcanzable aún necesita la aprobación de un humano.| Herramienta | Qué hace | Perilla de ámbito común |
|---|---|---|
file_edit | Leer/escribir archivos bajo cwd | Restricciones de ruta o patrón |
bash | Ejecutar comandos de shell | Prefijos de comandos permitidos/denegados |
web_search | Consultar un índice de búsqueda | Recuento de resultados, restricciones de dominio |
web_fetch | Recuperar el contenido de una URL | Lista de dominios permitidos |
# Limitar file_edit a un subdirectorio evita que un agente monorepo grande
# toque archivos fuera del paquete en el que se le pidió trabajar.
options = AgentOptions(
cwd="/repo",
allowed_tools=["file_edit"],
tool_config={
"file_edit": {"allowed_paths": ["packages/billing/**"]},
},
)| Parámetro | Tipo | Descripción |
|---|---|---|
allowed_tools | list[str] | Lista de permitidos de nombres de herramientas integradas que el bucle puede llamar |
cwd | str | Directorio de trabajo raíz para file_edit y bash |
tool_config | dict | Opciones de ámbito por herramienta (comandos permitidos, rutas, dominios) |
permission_mode | str | Si las llamadas permitidas aún necesitan aprobación humana (default, bypass, etc.) |
tool_config no establecida significa "sin restricciones". Una entrada bash sin ámbito en allowed_tools puede significar acceso completo al shell en algunas configuraciones. Solución: siempre empareje bash con allowed_commands explícito o una restricción equivalente a menos que realmente necesite acceso arbitrario al shell.web_search con web_fetch. Habilitar web_search cuando la tarea solo necesita leer una URL conocida le da al agente una capacidad mucho mayor e impredecible de la que necesita. Solución: habilite web_fetch solo para tareas con URL conocidas; reserve web_search para investigación abierta.cwd en entornos multiproyecto. Sin un cwd explícito, file_edit y bash por defecto al directorio de trabajo del proceso, lo que es frágil entre entornos. Solución: establezca siempre cwd explícitamente en lugar de depender del directorio ambiental.permission_mode como sustituto del ámbito. Una lista amplia de allowed_tools con puertas de aprobación solo en llamadas "obviamente destructivas" todavía deja muchas acciones sin revisar. Solución: acote primero las herramientas; use el modo de permisos como una segunda capa, no la única.file_edit a un agente de informes de solo lectura. Si una tarea nunca necesita escribir archivos, incluir file_edit de todos modos es un área de superficie innecesaria. Solución: conceda solo las herramientas que requieren los resultados reales de la tarea.bash con ámbito de antemano. Una lista de allowed_commands demasiado estricta rompe silenciosamente al agente a mitad de la tarea con un error de permisos que el modelo tiene que sortear. Solución: realice una prueba simulada de los comandos exactos que espera que el agente necesite antes de bloquear la lista de permitidos.| Alternativa | Usar cuando | No usar cuando |
|---|---|---|
| Conceder todas las herramientas integradas, depender de puntos de control | Prototipado localmente con un humano observando cada paso | Ejecución sin supervisión o contra datos de producción |
| Servidor MCP como única herramienta externa | La tarea necesita un sistema externo específico, no acceso general a archivos/bash/web | La tarea realmente necesita editar archivos locales o ejecutar comandos de shell |
| Sin herramientas, generación simple | La tarea es generación de texto pura sin necesidad de actuar sobre nada | La tarea requiere leer, escribir u obtener datos reales |
No. Habilite solo lo que necesita la tarea; allowed_tools acepta cualquier subconjunto, y una lista vacía o mínima es válida para tareas de texto puro.
La herramienta no se expone al modelo en primer lugar, por lo que no puede solicitarla; el bucle se comporta como si esa herramienta no existiera.
permission_mode y puntos de control se encuentran encima de él.Sí, normalmente a través de tool_config con restricciones de ruta o patrón, de modo que el agente solo pueda leer o escribir dentro de un subconjunto definido del proyecto.
web_search consulta un índice de búsqueda y devuelve resultados clasificados para que el modelo los procese. web_fetch recupera el contenido de una URL específica y conocida. Habilite la que realmente coincida con la tarea.
No hay un costo de tiempo de ejecución significativo; el ámbito se evalúa antes de que el bucle ofrezca la herramienta al modelo, por lo que no añade latencia por llamada.
Para cualquier cosa que toque sistemas de producción, datos de usuario reales o acciones irreversibles, sí. El ámbito limita lo que es posible; el modo de permisos añade una verificación antes de que lo posible realmente suceda.
Sí, cada subagente tiene su propio allowed_tools y tool_config, independiente del ámbito del principal.
Comience con los comandos reales que requiere la tarea (inspeccionar, probar, compilar), pruébelos manualmente primero y agregue a la lista solo a medida que surjan necesidades reales en lugar de adivinar ampliamente de antemano.
No es estrictamente obligatorio, pero omitirlo significa que file_edit y bash por defecto al directorio de trabajo ambiental del proceso, lo cual es frágil entre entornos. Establécelo explícitamente.
El ámbito de las herramientas se establece por llamada a query() a través de AgentOptions; para cambiarlo a mitad de tarea, normalmente terminaría la llamada actual y comenzaría una nueva con opciones actualizadas, reanudando opcionalmente la sesión.
query() con herramientas predeterminadasVersiones de la pila: Escrito contra la línea de modelos Claude actual a partir de ~junio de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (el predeterminado) y Claude Haiku 4.5 - y el SDK del Agente Claude (última versión, Python y TypeScript). Los nombres de los modelos, las versiones del SDK y los precios cambian rápidamente; verifique los detalles actuales en platform.claude.com/docs antes de confiar en ellos.
Revisado por Chris St. John·Última actualización: 16 jul 2026