agentwall-sdk

agentwall

Safety middleware for AI agent tool calls, available for Python and TypeScript.

Agents routinely execute shell commands, write files, mutate databases, and call authenticated APIs. Most tool-use stacks pass those calls directly to application code. agentwall adds a small interception layer that classifies each call, requests approval when required, emits a structured event, and registers an optional rollback.

from agentwall import Agentwall, BlockedError
wall = Agentwall()
@wall.tool("bash")
def bash(command: str) -> str:
    return f"executed: {command}"
try:
    bash("rm -rf /tmp/build-cache")
except BlockedError:
    print("blocked")
# The destructive call runs only after terminal approval.

Install

Python 3.9+:

pip install agentwall-sdk

Node.js 18+:

npm install agentwall-sdk

The core packages have no runtime dependencies. Framework clients are optional.

Demo

Quickstart

Python

Decorate an existing tool, or execute a ToolSpec inside a rollback-capable session:

from pathlib import Path
from agentwall import Agentwall, ToolSpec

wall = Agentwall()  # loads ./agentwall.yaml

def write_file(path: str, content: str) -> str:
    Path(path).write_text(content)
    return path

def remove_file(path: str, content: str) -> None:
    Path(path).unlink(missing_ok=True)

with wall.session(agent_id="worker-1") as session:
    session.call(
        ToolSpec("write_file", write_file, remove_file),
        path="result.txt",
        content="done",
    )

If the session exits with an exception, successful calls with rollback functions are compensated in reverse order. Normal exit commits the session.

Adapters accept the native OpenAI, Anthropic, and LangChain tool-call shapes:

from agentwall.integrations import (
    execute_anthropic_tool_use,
    execute_openai_tool_call,
    wrap_langchain_tool,
)

result = execute_openai_tool_call(tool_call, tools_by_name, wall)
result = execute_anthropic_tool_use(tool_use, tools_by_name, wall)
guarded_tool = wrap_langchain_tool(langchain_tool, wall)

TypeScript

import { Agentwall } from "agentwall-sdk";

const wall = new Agentwall();
const guarded = wall.wrap("bash", async ({ command }) => {
  return runCommand(String(command));
});

await guarded({ command: "rm -rf /tmp/build-cache" });

executeOpenAIToolCall, executeAnthropicToolUse, and wrapLangChainTool are exported from the TypeScript package.

Classification and approval

Each call is classified as:

Terminal approval is fail-closed. WebhookApproval posts the tool name, arguments, and classification to an HTTP endpoint and accepts only a successful response containing {"approved": true}.

Configuration

agentwall reads one agentwall.yaml from the working directory. Set AGENTWALL_CONFIG to use another YAML or JSON file.

approval:
  levels: ["destructive"]
logging:
  sink: file
  path: .agentwall/events.jsonl
webhook:
  url: null
  timeout_seconds: 30
default_classification: safe
redact_keys: ["authorization", "api_key", "token", "password", "secret"]
rules:
  - name: destructive-shell
    classification: destructive
    tool_pattern: "(?i)^(bash|shell|terminal)$"
    argument_pattern: "(?i)(rm\\s+-rf|mkfs|shutdown)"
  - name: file-writes
    classification: cautious
    tool_pattern: "(?i)(write|save|patch)_file"

Rules are evaluated in order; the first complete match wins.

Environment overrides:

The dependency-free YAML reader supports mappings, nested mappings, scalar lists, and lists of mappings. It does not support anchors, tags, or multiline scalars.

Replay

Dry-run approved, successful calls in log order:

agentwall replay .agentwall/events.jsonl

Execution replay requires an explicit ReplayRegistry containing sandbox-safe implementations:

agentwall replay .agentwall/events.jsonl --execute --module sandbox_tools

Development

See CONTRIBUTING.md.

License

Apache-2.0