Agent Tools - OpenLegion Docs

OpenLegion ships a set of @skill-decorated built-in tools organized into modules under engine/src/agent/builtins/. Worker agents see a curated subset based on their permissions.json ACL; the operator agent sees additional control-plane tools. Agents can also create custom skills at runtime (AST-validated) and use MCP tool servers. Every tool call has a default OPENLEGION_TOOL_TIMEOUT of 300s.

Execution

Tool	Purpose
`run_command`	Shell command execution, scoped to `/data`, 300s ceiling

File Operations

All file operations are scoped to /data with 4-stage path-traversal protection. Limits: _MAX_READ=500_000 bytes, _MAX_LIST_ENTRIES=500. Direct writes to workspace files (SOUL/INSTRUCTIONS/USER/MEMORY/HEARTBEAT/AGENTS/INTERFACE) are blocked at this layer — use update_workspace instead.

Tool	Purpose
`read_file`	Read file contents from `/data`
`write_file`	Write / append file in `/data`
`list_files`	List / glob files in `/data`

HTTP

Tool	Purpose
`http_request`	HTTP GET / POST / PUT / DELETE / PATCH with `$CRED{name}` substitution

SSRF protection is enforced at the mesh: DNS pinning, RFC1918 / loopback / link-local / CGNAT / 6to4 / Teredo / IPv4-mapped-IPv6 blocking, fail-closed on DNS error, max 5 redirects (re-validated at each hop), cross-origin auth strip.

Browser Automation

Camoufox (stealth Firefox fork) per agent, lazy-spawned on X displays :100..:163 (64 slots) paired with KasmVNC ports 6100..6163. The browser-service container is shared (FastAPI :8500); the Camoufox instance is per-agent. All browser actions are parallel_safe=False per agent_id.

Tool	Purpose
`browser_navigate`	Open URL, extract page text
`browser_warmup`	Pre-spawn the browser for an agent without navigating
`browser_get_elements`	A11y-tree snapshot (200-element cap, iframe nesting cap 3) with element refs (`e1, e2, …`)
`browser_screenshot`	Capture page screenshot (WebP by default)
`browser_click`	Click element by ref or CSS selector
`browser_click_xy`	Click absolute (x, y) coordinates
`browser_type`	Fill input by ref or CSS selector
`browser_hover`	Hover over element by ref or CSS selector
`browser_scroll`	Scroll page or scroll element into view
`browser_wait_for`	Wait for element, navigation, or network idle
`browser_find_text`	Locate visible text on page
`browser_fill_form`	Fill a form (max 50 fields per call)
`browser_press_key`	Press keyboard key (Enter, Escape, Tab, …)
`browser_open_tab`	Open a new tab
`browser_switch_tab`	Switch between open tabs
`browser_go_back`	Navigate back in history
`browser_go_forward`	Navigate forward in history
`browser_reset`	Force-close browser and reconnect fresh
`browser_inspect_requests`	Inspect network requests (200-entry buffer)
`browser_upload_file`	Upload (max 5 files, 50 MB each; 60s stage TTL)
`browser_download`	Download a file
`browser_detect_captcha`	Detect captcha presence and kind
`browser_solve_captcha`	Auto-solve via 2captcha / capsolver (reCAPTCHA v2/v3/enterprise, hCaptcha, Cloudflare Turnstile + interstitial, PerimeterX press-hold, DataDome, JS-challenges)
`browser_request_captcha_help`	Route a captcha to the human operator (behavioral kinds)
`browser_request_browser_login`	Route a login challenge to the human operator

Costs for CAPTCHA solving are tracked in millicents (1/100,000 USD) with per-agent + per-tenant monthly caps and a fleet-wide CAPTCHA_DISABLED kill switch. Solver-provider circuit breaker: 3 failures / 5 min → open 10 min. Session persistence is opt-in (BROWSER_SESSION_PERSISTENCE_ENABLED, default FALSE; snapshot interval 60-3600s, default 300s). Device profiles: desktop-windows (default), desktop-macos, mobile-ios, mobile-android. Mobile profiles spoof UA strings only — the underlying Camoufox / Firefox engine and TLS/JA3 fingerprints remain desktop. Fingerprint burn detection uses a rolling window of 10; ≥50% rejection sets fingerprint_burn=True. There is no auto-rotation — the operator must rotate the profile and reset.

Memory

Tool	Purpose
`memory_search`	Hybrid search across workspace files and the structured memory DB (BM25 + vector with `(0.7vector + 0.3keyword) * decay_score`)
`memory_save`	Save a fact to workspace and structured memory DB

Vector search uses text-embedding-3-small (OpenAI, 1536 dims). Non-OpenAI providers default to "none" and degrade to keyword-only; after 3 consecutive embedding failures the store silently disables vectors for the process lifetime. See the Memory System for full details on the 5-layer architecture.

Web Search

Tool	Purpose
`web_search`	Search via DuckDuckGo HTML, no API key required (1-10 results)

Image Generation

Tool	Purpose
`generate_image`	Generate a PNG via Gemini (default) or OpenAI DALL-E 3; written to `/data/workspace/artifacts/`

Fleet Awareness

Tool	Purpose
`notify_user`	Send a notification to the user via the active channel
`list_agents`	Discover other agents in the fleet
`get_agent_profile`	Get role / status / capabilities of another agent
`read_agent_history`	Read another agent’s conversation logs (subject to ACL)

Workspace

Tool	Purpose
`update_workspace`	Update identity / state files (SOUL.md, INSTRUCTIONS.md, USER.md, MEMORY.md, INTERFACE.md, AGENTS.md, HEARTBEAT.md)

Workspace caps (returned 413 on overflow): SOUL 4K, INSTRUCTIONS 12K, USER 4K, MEMORY 16K, INTERFACE 4K, AGENTS 12K, HEARTBEAT uncapped. PROJECT.md and SYSTEM.md are bootstrap-only and read-only at runtime.

Introspection

Tool	Purpose
`get_system_status`	Query own runtime state: permissions, budget, fleet, cron, health (5-min cache)

Shared State (Blackboard)

All blackboard operations are subject to per-agent blackboard_read / blackboard_write glob patterns. Writes are CAS-based via write_if_version.

Tool	Purpose
`read_blackboard`	Read a blackboard key
`write_blackboard`	Write to a blackboard key (atomic CAS)
`list_blackboard`	Browse blackboard entries by prefix
`watch_blackboard`	Watch for blackboard key changes (pattern-based)
`publish_event`	Publish event to mesh pub/sub
`subscribe_event`	Subscribe to mesh pub/sub events at runtime
`claim_task`	Claim a task from the agent’s lane queue (CAS)
`save_artifact`	Save a deliverable file and register it on the blackboard

Coordination

Tool	Purpose
`hand_off`	Hand a task off to another agent with structured payload (TTL 86400s)
`check_inbox`	Check pending handoffs / messages
`update_status`	Update own task status
`complete_task`	Mark a claimed task complete

Coordination uses the durable V2 task ledger when OPENLEGION_ORCHESTRATION_TASKS_V2=1 (default ON); V1 falls back to blackboard tasks/{agent}/{handoff_id} records.

Scheduling

Tool	Purpose
`set_cron`	Schedule a recurring job
`list_cron`	List scheduled jobs
`remove_cron`	Remove a scheduled job

5-field cron (minute granularity) or every N[s/m/h/d] interval syntax. No 6-field / seconds support. Three modes: message-mode (LLM dispatch), tool-mode (tool_name / tool_params direct invoke — no LLM), and heartbeat-mode (heartbeat=true). Heartbeats default to every 15m (the operator’s is force-locked to every 15m) and have a skip-LLM optimization that activates only when (not manual) + (HEARTBEAT.md is default) + (no recent activity) + (no probes triggered). See Triggering & Automation for details.

Skills Management

Tool	Purpose
`create_skill`	Write a new Python skill at runtime (AST-validated against 23 forbidden imports, 16 forbidden calls, 11 forbidden attrs; `_MAX_SKILL_SIZE=10_000` chars)
`reload_skills`	Hot-reload all skills
`spawn_fleet_agent`	Operator-only. Spawn a new ephemeral fleet agent via the mesh. The operator cannot grant `can_spawn=true` to other agents.

Subagent Spawning

Tool	Purpose
`spawn_subagent`	Spawn a lightweight in-process subagent (no container overhead)
`list_subagents`	List active subagents
`wait_for_subagent`	Wait for a subagent to complete and return its result

Subagents have MAX_DEPTH=2, MAX_CONCURRENT=3 per parent, default TTL 300s (max 600s), DEFAULT_MAX_ITERATIONS=10. Subagents cannot recurse, cannot create skills, and cannot use the browser concurrently (browser module is parallel-unsafe per agent).

Credential Vault

Tool	Purpose
`vault_generate_secret`	Generate a secure random secret; returns a `$CRED{name}` handle only
`vault_list`	List available credentials in the vault
`request_credential`	Request the user provide a credential interactively (the only path for runtime credential capture)

Agents never see raw secret values — only opaque $CRED{name} handles that the mesh substitutes at call time. System-tier credentials (OPENLEGION_SYSTEM_*) are always blocked from agents regardless of allowed_credentials.

Wallet

EVM chains (evm:ethereum, evm:base, evm:arbitrum, evm:polygon, evm:sepolia) and Solana (solana:mainnet, solana:devnet). Per-agent EVM keys derive via BIP-44 (m/44'/60'/{agent_index}'/0/0); per-agent Solana keys via HMAC-SHA512 over a PBKDF2 of the master seed. Private keys never leave the mesh process. The master seed is returned once at POST /api/wallet/init with Cache-Control: no-store; GET /api/wallet/seed returns HTTP 410 Gone afterward.

Tool	Purpose
`wallet_get_address`	Get the agent’s wallet address for a chain
`wallet_get_balance`	Get native / token balance
`wallet_read_contract`	Read from a smart contract
`wallet_transfer`	Transfer native or token (rate-limited, capped)
`wallet_execute`	Sign and submit a protocol transaction

Defaults: LIMIT_PER_TX_USD=10, LIMIT_DAILY_USD=100, RATE_LIMIT_PER_HOUR=10. Agents need can_use_wallet=true — and the operator cannot grant this flag; it must be edited directly in permissions.json.

Operator-Only Tools

The operator agent has additional control-plane tools for fleet management. These are not available to worker agents.

Tool	Purpose
`inspect_agents`	Inspect agents’ configs / state
`inspect_projects`	Inspect project metadata
`manage_project` / `create_project`	Project lifecycle
`add_agents_to_project` / `remove_agents_from_project`	Project membership
`update_project_context` / `set_project_goal`	Project content
`manage_agent` / `create_agent`	Agent lifecycle
`edit_agent`	Edit agent config (soft fields = 5-min Undo TTL; hard fields = 30-min, require `confirm_edit`)
`propose_edit` / `confirm_edit`	Legacy two-step edit flow
`manage_task`	Manage durable tasks
`save_observations`	Persist operator observations
`undo_change`	Revert a recent soft edit
`list_pending` / `cancel_pending_action`	Pending-action queue
`archive_audit_before`	Archive audit log entries
`list_agent_queue`	Inspect another agent’s lane queue
`get_team_outputs` / `summarize_project_progress`	Team reporting
`apply_template`	Apply a fleet template (per-slot, not atomic — mid-loop failures leave earlier-created agents)
`list_templates`	List available templates

Hard / soft edit fields. SOFT (5-min Undo): instructions, soul, heartbeat, heartbeat_schedule, interface, role. HARD (30-min confirmation): model, permissions, budget, thinking.

​Execution

​File Operations

​HTTP

​Browser Automation

​Memory

​Web Search

​Image Generation

​Fleet Awareness

​Workspace

​Introspection

​Shared State (Blackboard)

​Coordination

​Scheduling

​Skills Management

​Subagent Spawning

​Credential Vault

​Wallet

​Operator-Only Tools