Skip to Content
Agentic WorkspaceToolsBuilt-in toolsCode & repositoriesWorkspace & files

Workspace & files

Nine tools. code_workspace_open creates the working copy; everything else acts on it.

Every tool here takes _workspace and _sandbox — bind both. See Filling in tool parameters. Only the other parameters are listed below.

ℹ️

Which working copy? With one repository open, the other tools find it automatically and you leave workspace_id empty. With several open, pass workspace_name — the short name you opened it with, such as catalog-service. It is easier to get right than the id.

code_workspace_open

Clone a repository into a working copy, or refresh one already open. Call this first — nothing else works until a working copy exists. Category: Action · Needs: a git credential.

  • Bind: token (an Azure DevOps or GitHub Integration)
  • Pin or let the agent fill: repos — one entry per repository
  • Optional: refresh (default on) fetches the latest before working

The branch is part of a working copy’s identity, so the same repository on two branches is two working copies.

The code_workspace_open tool showing its repos parameter

Opening more than one repository

repos takes an entry per repository, which is how a task spanning several services works:

{ "repos": [
    { "name": "api", "repo_url": "https://dev.azure.com/Org/Project/_git/payments-api" },
    { "name": "web", "repo_url": "https://dev.azure.com/Org/Project/_git/payments-web", "branch": "develop" }
] }

If the project’s Code Workspace declares its repositories, an entry can be a name alone — {"name": "api"} — and calling the tool with nothing opens all of them.

⚠️

With several repositories open, later tools need to be told which one. There is no single “current” working copy, so pass workspace_name on every later call. Also set Pinned executor on the Code Workspace configuration, or a later build can be routed to a machine that has no working copy.

code_file_list

List files and directories, depth-limited and filtered. Use it to orient before searching or reading. Category: Data Pull.

  • The agent fills: path (omit for the repository root), include_globs, exclude_globs
  • Optional: max_depth, max_entries

Build output and dependency directories — node_modules, bin, obj, dist — are always excluded.

code_file_read

Read a file, optionally a line range. Category: Data Pull.

  • The agent fills: path, start_line, end_line
  • Optional: max_bytes — defaults to the workspace’s limit

On a large file, outline it first and read only the lines that matter. Reading a whole large file and then patching from a truncated view is how files get corrupted. Files matching the workspace’s Protected files are refused.

code_file_write

Create a file, or replace one completely. Category: Action.

  • The agent fills: path, content (the complete new contents), expected_sha256
⚠️

Prefer code_file_patch for editing. A whole-file write from a partial view silently deletes everything the agent did not include. expected_sha256 guards against this — pass the hash from the read and the write is refused if the file changed meanwhile.

code_file_patch

Replace an exact block of text. The preferred way to edit code. Category: Action.

  • The agent fills: path, search (copied verbatim from a read, including indentation), replace, replace_all

If the text is not found the call fails and changes nothing — it never silently does nothing. replace_all defaults to off, which replaces the first occurrence and fails if there are several.

code_file_delete

Delete a file. Category: Action · Pauses for approval.

  • The agent fills: path

Search for text or a regular expression, returning matches with line numbers and context. Category: Data Pull.

  • The agent fills: query, is_regex, case_sensitive
  • Optional: max_matches, context_lines

Use it to find where something is defined or used before reading whole files.

code_symbol_outline

Map a file’s classes, functions and other symbols without reading all of it. Category: Data Pull.

  • The agent fills: path, kinds

The right first step on any file big enough that reading it whole would be wasteful.

code_workspace_archive

Zip the working copy. Category: Action.

  • Optional: include_git (default off)

Common issues

  • Every tool says there is no workspace — code_workspace_open has not run, or it opened several repositories and this call did not say which.
  • A read or write is refused on a particular file — It matches the workspace’s Protected files. That is deliberate.
  • A patch fails saying the text was not found — The search text does not match the file byte for byte, usually indentation. Re-read the file first.
  • A patch fails saying there are several matches — Set replace_all, or include more surrounding context to make the search unique.
  • A clone is refused — The host is not in Allowed git hosts, or the repository is over the size or file-count limit. See Code & Execution.
Filling in tool parametersVersion control