Tools

These are the agent’s own tools, exposed as plain endpoints. Reach for them when you know exactly what needs to happen and do not want a model deciding: a CI step that writes a build report, a script that greps for a pattern before deciding what to do next, a service that runs one command in a sandbox. Every tool is POST /api/workspaces/{workspace_id}/tools/{tool}.

export ARG_API_KEY="arg_live_your_key_here"
export ARG_API="https://api.arg.ai"

Two kinds of path

This trips people up once and then never again.

File tools (read-file, write-file, edit-file, multi-edit) take workspace paths: /data.csv, /reports/august.mdx. They read and write storage directly and never start a sandbox.
Shell tools (run-bash, grep) run inside the sandbox, where the workspace is mounted at /ws - which is also the working directory. So ls lists the workspace root, and /ws/data.csv is the same file as /data.csv.

Run bash

curl -sS -X POST "$ARG_API/api/workspaces/$WS/tools/run-bash" \
  -H "X-API-Key: $ARG_API_KEY" -H "Content-Type: application/json" \
  -d '{"command": "python3 analyze.py > report.txt && wc -l report.txt"}'

{ "status": "completed", "stdout": "12 report.txt\n", "stderr": "", "duration_ms": 2841 }

status is completed or failed; a non-zero exit is failed, not an HTTP error. Commands are cut off after 10 minutes. The sandbox keeps a persistent shell between calls, so cd and exported variables survive to the next command. Two consequences worth knowing: a bare exit in your command kills that shell (state is lost, a fresh one starts on the next call), and files written anywhere under /ws land in the workspace. Pass sandbox_id to run in an isolated named container instead of the workspace’s default one - useful for keeping a long build away from everything else. Ids are scoped to the workspace, so the same id in two workspaces cannot collide.

{ "command": "npm ci && npm test", "sandbox_id": "ci" }

Read a file

curl -sS -X POST "$ARG_API/api/workspaces/$WS/tools/read-file" \
  -H "X-API-Key: $ARG_API_KEY" -H "Content-Type: application/json" \
  -d '{"path": "/src/main.py", "offset": 10, "limit": 20}'

Field	Type	Description
`path`	string	Workspace path. Required.
`offset`	integer	First line to return, zero-based.
`limit`	integer	Maximum lines to return.
`raw`	boolean	Return the file as-is instead of line-numbered.

Output is line-numbered by default, which is what makes edit-file easy to aim. Set raw: true when a program is going to parse the result. Binary files return 400 - download them instead.

Write a file

curl -sS -X POST "$ARG_API/api/workspaces/$WS/tools/write-file" \
  -H "X-API-Key: $ARG_API_KEY" -H "Content-Type: application/json" \
  -d '{"path": "/reports/august.md", "content": "# August\n\nRevenue up 12%.\n"}'

{ "success": true, "path": "/reports/august.md", "bytes": 31, "revision": "…" }

This overwrites. To write only if the file does not exist, or to write only if nobody else has changed it since you read it, use PUT /files/content with createOnly or baseRevision.

Edit a file

curl -sS -X POST "$ARG_API/api/workspaces/$WS/tools/edit-file" \
  -H "X-API-Key: $ARG_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "path": "/config.json",
    "old_string": "\"debug\": false",
    "new_string": "\"debug\": true"
  }'

old_string must appear in the file or the call returns 400. By default only the first occurrence is replaced; set replace_all: true for every occurrence. The response reports how many replacements it made.

Apply several edits at once

curl -sS -X POST "$ARG_API/api/workspaces/$WS/tools/multi-edit" \
  -H "X-API-Key: $ARG_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "path": "/config.json",
    "edits": [
      { "old_string": "\"debug\": false", "new_string": "\"debug\": true" },
      { "old_string": "\"port\": 3000", "new_string": "\"port\": 8080" }
    ]
  }'

Up to 200 edits, applied in order, in one write - so later edits see the text earlier ones produced.

Edits are applied best-effort, not all-or-nothing. Edits that match are written even if others do not. Check the response rather than assuming a 200 means everything applied:

{ "success": true, "applied_edits": 1, "total_edits": 2, "failed_indices": [1] }

Only a request where nothing matched returns 400.

Grep

curl -sS -X POST "$ARG_API/api/workspaces/$WS/tools/grep" \
  -H "X-API-Key: $ARG_API_KEY" -H "Content-Type: application/json" \
  -d '{"pattern": "TODO|FIXME", "path": "/src", "include": "*.py"}'

{ "status": "completed", "output": "/ws/src/main.py:42:# TODO: handle retries\n", "no_matches": false }

Field	Type	Description
`pattern`	string	Regular expression, up to 500 characters. Required.
`path`	string	Folder or file to search. Defaults to the workspace root.
`include`	string	Glob filter on file names, for example `*.ts`.
`sandbox_id`	string	Search from a named sandbox.

Matches come back with /ws-prefixed paths, because grep runs in the sandbox. Output is capped at 10,000 characters, so narrow the path or include rather than paging. Large binary and media files are skipped. For meaning rather than exact text - “the doc about refund policy” - use semantic search.

Permissions

Tool	Requires
`read-file`, `grep`	Read access
`write-file`, `edit-file`, `multi-edit`, `run-bash`	Write access

run-bash and grep need workspace-wide access, not access to a single file, because a shell command can reach anything mounted.

Agents overview - when to let an agent choose the tools instead
Files - uploads, downloads, versions, and conditional writes
Actions - typed capabilities beyond files and shell
Agent Tools API reference - full schemas

Getting started

Building with agents

Core concepts

Apps

Arg SDK

Integrations

Command line

Recipes & patterns

Changelog

Two kinds of path

Run bash

Read a file

Write a file

Edit a file

Apply several edits at once

Grep

Permissions

​Two kinds of path

​Run bash

​Read a file

​Write a file

​Edit a file

​Apply several edits at once

​Grep

​Permissions

​Related

Two kinds of path

Run bash

Read a file

Write a file

Edit a file

Apply several edits at once

Grep

Permissions

Related