toolkits

An agent's tool list should read as a description of what that agent may do. Bundling also means a tool added to a category reaches every agent that claimed the category, instead of drifting between hand-maintained arrays.

Every bundle is a function rather than a constant, matching searchTools() in std::agents/lib/search, which must be a function because it reads API keys at call time. An agent whose list includes searchTools() must build that list inside a function too, or it freezes the environment at module load.

Constants

ASK_USER_HINT

export static const ASK_USER_HINT = "\n\nWhen the work turns on something only the user can tell you — which account they mean, which of two readings of the request, a value you cannot look up — ask with the `question` tool, and ask before you build on the guess rather than after. Do not ask for anything you could find yourself, and do not ask the user to narrow a scope they left broad on purpose. When nobody can answer, your question comes back rejected; when that happens, pick the most reasonable reading, say which one you picked, and carry on."

(source)

SAVE_DRAFT_HINT

export static const SAVE_DRAFT_HINT = "\n\nIf you might run low on time or budget, call `saveDraft` with your best answer so far as you work, and update it as you improve. If the run is cut short, the last draft you saved is what the user receives — a run that saved nothing returns nothing."

(source)

Functions

whatIAmDoing

whatIAmDoing(message: string): string

Tell the user what you are doing. Use this tool often to update the user on what you're up to.

Parameters:

Name	Type	Default
message	string

Returns: string

(source)

communicationTools

communicationTools(): any[]

Return tools that help the agent communicate with the user: whatIAmDoing to report progress, and question to ask for a fact only the user has.

question raises an interrupt rather than reading the terminal, so whoever hosts the agent can answer it: a person at a prompt, an HTTP host, or a handler in a test. A run with no one to ask rejects it. An approval policy rule can never answer it, because the answer is a value and approve() carries none; see docs/dev/stdlib/asking-the-user.md.

Returns: any[]

(source)

readOnlyFileTools

readOnlyFileTools(): any[]

Return tools that inspect the file system without changing it: read, list, glob, and grep, resolved against the agent working directory.

grep honours .gitignore, and the setting is locked by partial application so the model cannot turn it off and search generated files.

Returns: any[]

(source)

writableFileTools

writableFileTools(): any[]

Return the read-only file tools plus write and edit.

Returns: any[]

(source)

shellTools

shellTools(): any[]

Return tools that run commands: safeBash for a shell pipeline, exec for a single binary with arguments. safeBash rather than raw bash: it parses the command and raises the narrowest effects that describe it (a recognized write raises std::write, a git read raises its git effect), so a policy can pre-approve what raw bash never could. It needs no useAgentCwd binding — its empty cwd already resolves to the agent working directory (resolveCwd in std::safeBash). readSpill and grepSpill read back the output safeBash saved to a file when a command printed too much to return inline.

Returns: any[]

(source)

readOnlyGitTools

readOnlyGitTools(): any[]

Return the read-only git tools: history, diffs, status, branches. Nothing here changes the repository, so read-only agents (verifiers, reviewers, writers with read-only project access) can carry them. gitIsRepo is included because "am I inside a repo?" is the question an agent otherwise answers by probing for a .git directory by hand — which fails in a monorepo, where .git lives above the package directory (git itself walks up; a manual probe does not).

Returns: any[]

(source)

gitTools

gitTools(): any[]

Return the git tools. The read-only ones run without an approval prompt; the ones that change the repository prompt for approval.

Returns: any[]

(source)

githubReadTools

githubReadTools(): any[]

Return the read-only GitHub tools: pull requests, their diffs, files, reviews, and checks; issues, their comments, and search. Nothing here posts anything, so read-only agents (reviewers) can carry them. Each tool resolves the repository from the origin remote of the agent working directory, so an agent with these tools needs a working directory set.

Returns: any[]

(source)

githubTools

githubTools(): any[]

Return the GitHub tools. The read-only ones are in githubReadTools; the rest post comments and reviews, and create, comment on, close, and label issues. Every write prompts for approval unless a policy approves it. ghPrApprove raises its own effect (std::github::prApprove), so a policy can forbid approving a pull request while allowing every other review action.

Returns: any[]

(source)

webTools

webTools(): any[]

Return tools that retrieve a named web resource: HTTP fetches and Wikipedia lookups. These retrieve something you can already name; to discover a source you cannot name yet, add a search tool as well.

Returns: any[]

(source)

agencyDocTools

agencyDocTools(): any[]

Return the bundled Agency documentation tools: the language guide, the CLI reference, the type-checker diagnostic codes, and the standard-library reference.

Returns: any[]

(source)

agencyDocToolsBrief

agencyDocToolsBrief(): any[]

Return the same five documentation tools as agencyDocTools, under the same names, with each page listed as one path - description line. For an agent whose prompt already teaches the language. Offer one set or the other: the names collide.

Returns: any[]

(source)

agencyCodeTools

agencyCodeTools(): any[]

Return tools for checking Agency source: the type checker, the parser, and testFile, which runs a .test.json harness in a sandboxed subprocess.

Returns: any[]

(source)

memoryTools

memoryTools(): any[]

Return tools that persist and retrieve facts across sessions.

Returns: any[]

(source)

planningTools

planningTools(): any[]

Return tools an agent uses to organize a long run: writing and reading a todo list.

Returns: any[]

(source)