LinkedInGitHub

Use cases & examples

Patterns that work well with agentpad in agents, CI, and local tools. Every snippet targets a real directory (Runtime root).

Automated tests: Vitest (Node) and pytest (Python). Source: github.com/vgulerianb/agentpad.

Building agents with agentpad

agentpad is the workspace runtime your agent calls when it needs to run shell, Python, Node, or SQL against a real checkout (customer repo, task sandbox, or CI workspace). Typical flow:

  1. Create one Runtime(root) per session (or per task), with readonly, overlay, and limits chosen for trust level.
  2. Register asOpenAITool() / as_openai_tool() (or your provider’s equivalent) so the model emits { language, code }.
  3. On each tool call, run executeToolCall / execute_tool_call, then append stdout / stderr / exit code / changed files back into the chat (truncate large output—see Configuration).

Wire the model’s execute_code tool to Runtime

import type { RunResult } from "agentpad";
import { Runtime } from "agentpad";

/** Call this when the chat API returns a tool_call for `execute_code`. */
export async function dispatchExecuteCode(
  rt: Runtime,
  args: { language: "bash" | "python" | "javascript" | "sql"; code: string },
): Promise<RunResult> {
  return rt.executeToolCall({ language: args.language, code: args.code });
}

// When building tools[] for the model, reuse the schema from the runtime:
const rt = new Runtime("./agent-workspace", { overlay: true, limits: { timeoutMs: 60_000 } });
const executeCodeTool = rt.asOpenAITool();
// Pass `executeCodeTool` in your `tools` array alongside your other agent tools.

Feed results back to the agent

Agents need grounding: after each run, stringify a short summary (trim stdout, cap file list). Example shape:

import type { RunResult } from "agentpad";

function summarizeForAgent(r: RunResult, maxChars = 4000) {
  const out = (r.stdout + r.stderr).slice(0, maxChars);
  const files = r.files.slice(0, 20).map((f) => `${f.type} ${f.path}`);
  return JSON.stringify({
    exitCode: r.exitCode,
    output: out,
    truncated: r.truncated,
    files,
  });
}

Speculative agent edits (overlay)

Let the agent run destructive commands on a copy; only apply() when a human or policy gate approves—see §3 Safe edits below.

Security reminder

agentpad runs real processes with the host user’s privileges. Use read-only or overlay for untrusted prompts, tight timeouts, and never expose Runtime directly on the public internet without another boundary—see Security.

1. CI: run checks in the repo

import { Runtime } from "agentpad";

const rt = new Runtime(process.cwd(), { readonly: true });

const r = await rt.run("bash", "npm test", {
  cwd: ".",
  timeoutMs: 120_000,
});

console.log(r.exitCode === 0 ? "ok" : "failed", r.stdout.slice(0, 500));
rt.close();

Use read-only when you only need to verify the tree, not mutate it.

2. Agent: run Python and read a file from the workspace

import { Runtime } from "agentpad";

const rt = new Runtime("./my-service");

const r = await rt.run(
  "python",
  `import json, pathlib
p = pathlib.Path("package.json")
print(json.dumps({"name": json.loads(p.read_text())["name"]}))`,
);

console.log(JSON.parse(r.stdout));
console.log(r.files); // created / modified / deleted under the workspace

rt.close();

3. Safe edits: overlay, then apply()

Run destructive commands against a temp copy of the project; merge back when satisfied.

import { Runtime } from "agentpad";

const rt = new Runtime("./app", { overlay: true });

await rt.run("bash", 'echo "patched" > config.local.env');
// Live tree under ./app is unchanged until:
rt.apply();
rt.close();

4. Audit trail: session run log

import { Runtime, exportRunLogJSON } from "agentpad";

const rt = new Runtime("./repo", {
  runLog: true,
  runLogMaxEntries: 50,
  onRun: (e) => {
    if (e.stderr) console.warn(e.id, e.stderr);
  },
});

await rt.run("python", "print('hello')");
console.log(exportRunLogJSON(rt.getRunLog()));

rt.clearRunLog();
rt.close();

5. OpenAI-style tool calling

Same function schema shape in both languages; wire the returned JSON into your model, then dispatch with executeToolCall / execute_tool_call.

import { Runtime } from "agentpad";

const rt = new Runtime("./workspace");
const tool = rt.asOpenAITool();

// Pass `tool` to the chat API as a tool definition, then:
const result = await rt.executeToolCall({
  language: "python",
  code: "print(len(open('README.md').read()))",
});

console.log(result.stdout, result.exitCode);
rt.close();

Next steps