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.
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().
Resumen
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.
Receta
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:
- Sabe exactamente qué familias de herramientas necesita una tarea y desea conceder solo esas.
- Está creando un agente que se ejecutará sin supervisión y necesita
permission_modecomo red de seguridad. - Quiere que las operaciones de archivos y bash estén limitadas a un directorio de proyecto específico a través de
cwd. - Está auditando el acceso a herramientas de un agente existente antes de implementarlo.
Ejemplo de trabajo
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:
- Combinación de tres familias de herramientas (
bash,file_edit,web_fetch) para una tarea que realmente necesita leer historial, obtener datos externos y escribir un archivo. - Acotar bash aún más con
allowed_commandsen lugar de conceder acceso de shell sin restricciones. - Omitir deliberadamente
web_searchporque la tarea solo necesita obtener URLs conocidas, no buscar en la web. - Imprimir eventos de llamada a herramienta por separado del texto para que pueda ver las acciones del bucle a medida que ocurren.
Análisis en profundidad
Cómo funciona
allowed_toolsse 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_editcubre la lectura y escritura de archivos bajocwd; algunas versiones del SDK le permiten restringirlo aún más a rutas o patrones específicos a través detool_config.bashejecuta comandos de shell en el directorio de trabajo; acotarlo a una lista deallowed_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_searchconsulta un índice de búsqueda y devuelve resultados que el modelo puede procesar;web_fetchrecupera 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_modeopera independientemente deallowed_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.
Familias de herramientas de un vistazo
| 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 |
Notas de Python
# 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ámetros y valores de retorno
| 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.) |
Trampas
- Asumir que una
tool_configno establecida significa "sin restricciones". Una entradabashsin ámbito enallowed_toolspuede significar acceso completo al shell en algunas configuraciones. Solución: siempre emparejebashconallowed_commandsexplícito o una restricción equivalente a menos que realmente necesite acceso arbitrario al shell. - Confundir
web_searchconweb_fetch. Habilitarweb_searchcuando la tarea solo necesita leer una URL conocida le da al agente una capacidad mucho mayor e impredecible de la que necesita. Solución: habiliteweb_fetchsolo para tareas con URL conocidas; reserveweb_searchpara investigación abierta. - Olvidar
cwden entornos multiproyecto. Sin uncwdexplícito,file_editybashpor defecto al directorio de trabajo del proceso, lo que es frágil entre entornos. Solución: establezca siemprecwdexplícitamente en lugar de depender del directorio ambiental. - Tratar
permission_modecomo sustituto del ámbito. Una lista amplia deallowed_toolscon 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. - Conceder
file_edita un agente de informes de solo lectura. Si una tarea nunca necesita escribir archivos, incluirfile_editde todos modos es un área de superficie innecesaria. Solución: conceda solo las herramientas que requieren los resultados reales de la tarea. - No probar los comandos
bashcon ámbito de antemano. Una lista deallowed_commandsdemasiado 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.
Alternativas
| 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 |
Preguntas frecuentes
¿Tengo que habilitar las cuatro familias de herramientas integradas juntas?
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.
¿Qué sucede si el modelo intenta llamar a una herramienta que no está en allowed_tools?
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.
¿Es el acceso a bash siempre peligroso?
- Bash sin restricciones es de alto riesgo ya que puede ejecutar cualquier comando de shell.
- Bash con ámbito, limitado a prefijos de comandos específicos, es de mucho menor riesgo.
- El riesgo también depende de qué
permission_modey puntos de control se encuentran encima de él.
¿Puedo restringir file_edit a archivos o carpetas específicos?
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.
¿Cuál es la diferencia entre web_search y web_fetch?
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.
¿Acelera el ámbito de las herramientas al agente?
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.
¿Debería usar siempre permission_mode junto con el ámbito?
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.
¿Puede el ámbito de las herramientas diferir entre un agente principal y sus subagentes?
Sí, cada subagente tiene su propio allowed_tools y tool_config, independiente del ámbito del principal.
¿Cómo sé qué comandos poner en una lista allowed_commands?
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.
¿Es cwd obligatorio?
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.
¿Puedo cambiar el ámbito de las herramientas a mitad de sesión?
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.
Relacionado
- El Modelo Mental del SDK del Agente Claude - cómo encaja el ámbito de las herramientas en el bucle general
- Conceptos básicos del SDK del Agente Claude - una primera llamada a
query()con herramientas predeterminadas - Añadir puntos de control de intervención humana a un flujo de trabajo del SDK del Agente Claude - la capa de aprobación sobre el ámbito
- Referencia de opciones de configuración del SDK del Agente Claude - comparación completa de opciones entre Python y TypeScript
- Conectar el SDK del Agente Claude a servidores MCP - extender el alcance más allá de las herramientas integradas
Versiones 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.