Tools Reference

September 2, 2026 · View on GitHub

← Back to README

This document provides comprehensive documentation for all tools available to LLMs when tool execution is enabled in the Inference Gateway CLI.

Table of Contents

Customising Tool Descriptions

The description string each tool exposes to the LLM (the prose that explains what the tool does) is configurable in .infer/prompts.yaml under the tools key. This lets you tune phrasing for your model without recompiling - useful when a model misinterprets a default description, or when you want to discourage/encourage particular usage patterns.

# .infer/prompts.yaml
tools:
  Bash:
    description: |-
      Execute allowed bash commands securely. Only pre-approved
      commands from the allowed can be executed.
  Read:
    description: |-
      Reads a file from the local filesystem. Always prefer reading
      whole files over chunked reads unless the file is very large.

Rules:

  • Keys use the LLM-visible tool name (e.g. Bash, MultiEdit, A2A_SubmitTask, GetLatestFrame). MCP tools are not customisable here - their descriptions come from the MCP server.
  • Any tool you omit (or any field left empty) falls back to the in-code default in config.DefaultPromptsConfig. You can override one tool without losing the defaults for the rest.
  • Environment variable overrides take precedence over the file: INFER_PROMPTS_TOOLS_<UPPER_SNAKE_NAME>_DESCRIPTION - e.g. INFER_PROMPTS_TOOLS_BASH_DESCRIPTION, INFER_PROMPTS_TOOLS_A2A_SUBMIT_TASK_DESCRIPTION.
  • Parameter descriptions (the per-argument explanations inside the tool schema) are not currently configurable.

File System Tools

Tree Tool

Display directory structure in a tree format, similar to the Unix tree command. Provides a polyfill implementation when the native tree command is unavailable.

Parameters:

  • path (optional): Directory path to display tree structure for (default: current directory)
  • max_depth (optional): Maximum depth to traverse (unlimited by default)
  • show_hidden (optional): Whether to show hidden files and directories (default: false)
  • respect_gitignore (optional): Whether to exclude patterns from .gitignore (default: true)
  • format (optional): Output format - "text" or "json" (default: "text")

Examples:

  • Basic tree: Uses current directory with default settings
  • Tree with depth limit: max_depth: 2 - Shows only 2 levels deep
  • Tree with hidden files: show_hidden: true
  • Tree ignoring gitignore: respect_gitignore: false - Shows all files including those in .gitignore
  • JSON output: format: "json" - Returns structured data

Features:

  • Native Integration: Uses system tree command when available for optimal performance
  • Polyfill Implementation: Falls back to custom implementation when tree is not installed
  • Pattern Exclusion: Supports glob patterns to exclude specific files and directories
  • Depth Control: Limit traversal depth to prevent overwhelming output
  • Hidden File Control: Toggle visibility of hidden files and directories
  • Multiple Formats: Text output for readability, JSON for structured data

Security:

  • Respects configured path exclusions for security
  • Validates directory access permissions
  • Limited by the same security restrictions as other file tools

Read Tool

Read file content from the filesystem with optional line range specification.

Configuration:

tools:
  read:
    enabled: true
    require_approval: false  # Read operations don't require approval by default

Write Tool

Write content to files on the filesystem with security controls and directory creation support.

Parameters:

  • file_path (required): The path to the file to write
  • content (required): The content to write to the file
  • create_dirs (optional): Whether to create parent directories if they don't exist (default: true)
  • overwrite (optional): Whether to overwrite existing files (default: true)
  • format (optional): Output format - "text" or "json" (default: "text")

Features:

  • Directory Creation: Automatically creates parent directories when needed
  • Overwrite Control: Configurable behavior for existing files
  • Security Validation: Respects path exclusions and security restrictions
  • Performance Optimized: Efficient file writing with proper error handling

Security:

  • Approval Required: Write operations require approval by default (secure by default)
  • Path Exclusions: Respects configured excluded paths (e.g., .infer/ directory)
  • Pattern Matching: Supports glob patterns for path exclusions
  • Validation: Validates file paths and content before writing

Examples:

  • Create new file: file_path: "output.txt", content: "Hello, World!"
  • Write to subdirectory: file_path: "logs/app.log", content: "log entry", create_dirs: true
  • Safe overwrite: file_path: "config.json", content: "{...}", overwrite: false

Configuration:

tools:
  write:
    enabled: true
    require_approval: true  # Write operations require approval for security

Edit Tool

Perform exact string replacements in files with security validation and preview support.

Parameters:

  • file_path (required): The path to the file to modify
  • old_string (required): The text to replace (must match exactly)
  • new_string (required): The text to replace it with
  • replace_all (optional): Replace all occurrences of old_string (default: false)

Features:

  • Indentation-Tolerant Matching: Exact first; on a miss, a unique leading-whitespace match is re-indented (strict_whitespace: true disables)
  • Preview Support: Shows diff preview before applying changes
  • Atomic Operations: Either all changes succeed or none are applied
  • Security Validation: Respects path exclusions and file permissions

Security:

  • Read Tool Requirement: Requires Read tool to be used first on the file
  • Stale-Read Detection: Rejects the edit if the file changed on disk since the agent last read it, and asks the model to re-read first
  • Approval Required: Edit operations require approval by default
  • Path Exclusions: Respects configured excluded paths
  • Validation: Validates file paths and prevents editing protected files

Examples:

  • Single replacement: file_path: "config.txt", old_string: "port: 3000", new_string: "port: 8080"
  • Replace all occurrences: file_path: "script.py", old_string: "print", new_string: "logging.info", replace_all: true

Configuration:

tools:
  edit:
    enabled: true
    require_approval: true  # Edit operations require approval for security
    strict_whitespace: false  # When true, disable the indentation-tolerant fallback (byte-exact only)

MultiEdit Tool

Make multiple edits to a single file in atomic operations. All edits succeed or none are applied.

Parameters:

  • file_path (required): The path to the file to modify
  • edits (required): Array of edit operations to perform sequentially
    • old_string: The text to replace (must match exactly)
    • new_string: The text to replace it with
    • replace_all (optional): Replace all occurrences (default: false)

Features:

  • Atomic Operations: All edits succeed or none are applied
  • Sequential Processing: Edits are applied in the order provided
  • Indentation-Tolerant Matching: Each edit matches exactly first, then a unique leading-whitespace fallback (tools.edit.strict_whitespace)
  • Preview Support: Shows comprehensive diff preview
  • Security Validation: Respects all security restrictions

Security:

  • Read Tool Requirement: Requires Read tool to be used first on the file
  • Stale-Read Detection: Rejects the edit if the file changed on disk since the agent last read it, and asks the model to re-read first
  • Approval Required: MultiEdit operations require approval by default
  • Path Exclusions: Respects configured excluded paths
  • Validation: Validates all edits before execution

Example:

{
  "file_path": "config.yaml",
  "edits": [
    {
      "old_string": "port: 3000",
      "new_string": "port: 8080"
    },
    {
      "old_string": "debug: true",
      "new_string": "debug: false"
    }
  ]
}

Delete Tool

Delete files or directories from the filesystem with security controls. Supports wildcard patterns for batch operations.

Parameters:

  • path (required): The path to the file or directory to delete
  • recursive (optional): Whether to delete directories recursively (default: false)
  • force (optional): Whether to force deletion (ignore non-existent files, default: false)

Features:

  • Wildcard Support: Delete multiple files using patterns like *.txt or temp/*
  • Recursive Deletion: Remove directories and their contents
  • Safety Controls: Respects configured path exclusions and security restrictions
  • Validation: Validates file paths and permissions before deletion

Security:

  • Approval Required: Delete operations require approval by default
  • Path Exclusions: Respects configured excluded paths for security
  • Pattern Matching: Supports glob patterns for path exclusions
  • Validation: Validates file paths and prevents deletion of protected directories

Examples:

  • Delete single file: path: "temp.txt"
  • Delete directory recursively: path: "temp/", recursive: true
  • Delete with wildcard: path: "*.log"
  • Force delete: path: "missing.txt", force: true

Configuration:

tools:
  delete:
    enabled: true
    require_approval: true  # Delete operations require approval for security

Grep Tool

A powerful search tool with configurable backend (ripgrep or Go implementation).

Parameters:

  • pattern (required): The regular expression pattern to search for
  • path (optional): File or directory to search in (default: current directory)
  • output_mode (optional): Output mode - "content", "files_with_matches", or "count" (default: "files_with_matches")
  • -i (optional): Case insensitive search
  • -n (optional): Show line numbers in output
  • -A (optional): Number of lines to show after each match
  • -B (optional): Number of lines to show before each match
  • -C (optional): Number of lines to show before and after each match
  • glob (optional): Glob pattern to filter files (e.g., ".js", ".{ts,tsx}")
  • type (optional): File type to search (e.g., "js", "py", "rust")
  • multiline (optional): Enable multiline mode where patterns can span lines
  • head_limit (optional): Limit output to first N results

Features:

  • Dual Backend: Uses ripgrep when available for optimal performance, falls back to Go implementation
  • Full Regex Support: Supports complete regex syntax
  • Multiple Output Modes: Content matching, file lists, or count results
  • Context Lines: Show lines before and after matches
  • File Filtering: Filter by glob patterns or file types
  • Multiline Matching: Patterns can span multiple lines
  • Automatic Exclusions: Automatically excludes common directories and files (.git, node_modules, .infer, etc.)
  • Gitignore Support: Respects .gitignore patterns in your repository
  • User-Configurable Exclusions: Additional exclusion patterns can be configured by users (not by the LLM)

Security & Exclusions:

  • Path Exclusions: Respects configured excluded paths and patterns
  • Automatic Exclusions: The tool automatically excludes:
    • Version control directories (.git, .svn, etc.)
    • Dependency directories (node_modules, vendor, etc.)
    • Build artifacts (dist, build, target, etc.)
    • Cache and temp files (.cache, *.tmp, *.log, etc.)
    • Security-sensitive files (.env, secrets, etc.)
  • Gitignore Integration: Automatically reads and respects .gitignore patterns
  • Validation: Validates search patterns and file access
  • Performance Limits: Configurable result limits to prevent overwhelming output

Examples:

  • Basic search: pattern: "error", output_mode: "content"
  • Case insensitive: pattern: "TODO", -i: true, output_mode: "content"
  • With context: pattern: "function", -C: 3, output_mode: "content"
  • File filtering: pattern: "interface", glob: "*.go", output_mode: "files_with_matches"
  • Count results: pattern: "log.*Error", output_mode: "count"

Configuration:

tools:
  grep:
    enabled: true
    backend: auto  # "auto", "ripgrep", or "go"
    require_approval: false

Command Execution

Bash Tool

Execute bash commands that match a per-mode allow-list. The model is default-deny: anything not matched is denied - it prompts for approval in chat, or is rejected with an actionable reason in headless agent mode.

Configuration:

tools:
  bash:
    enabled: true
    mode:
      all:        # baseline applied in EVERY mode (read-only / non-mutating)
        allow:
          - ls( .*)?
          - git status( .*)?
          - gh (issue|pr) (list|view)( .*)?
      plan:       # read-only planning mode adds nothing
        allow: []
      standard:   # interactive default: baseline only (same as plan)
        allow: []
      auto:       # headless `infer headless`: full autonomy (commit, push, etc.)
        allow:
          - .*

The effective allow-list for a mode is mode.all.allow unioned with that mode's own list. Each entry is a regex matched against the whole command (\A(?:entry)\z), so a bare token matches only itself (gh allows gh, never gh issue list) - use ( .*)? to accept arguments. The single sentinel .* means unrestricted (any single command, guard skipped); it is the default for auto mode, which is how an autonomous infer headless commits and pushes. Tighten mode.auto.allow to a curated list for CI with secrets so the guard re-applies.

Clean-command guard (every non-.* mode):

A command is rejected before matching, regardless of the allow-list, when it:

  • Pipes or chains (|, |&, &&, ||, ;, &, newline) - only a single command is auto-approved, so ls | head is rejected even if both ls and head are allowed. Operators inside quotes (a jq '… | …' or --title "a && b") do not count.
  • Writes to a file (>, >>, &>file, >&file) - echo secret > /etc/passwd is rejected; this cannot be unlocked by an allow entry.
  • Uses command substitution ($(...), backticks, <(...), >(...)).
  • Runs a dangerous find action (find ... -exec/-delete/…).
  • Leaks a variable: a printing/publishing command (echo, printf, gh issue/pr create|comment|edit) may not expand $VAR - echo $AWS_SECRET_ACCESS_KEY is rejected, while ls $DIR (a non-printing use) is allowed. A single-quoted or backslash-escaped $ is literal.

Benign redirections that only discard or merge streams (2>&1, >/dev/null, 2>/dev/null) are stripped before matching and remain allowed. A rejected command returns explanatory feedback naming the reason, and (in chat) still goes through the normal approval prompt.

Web Tools

WebSearch Tool

Search the web using DuckDuckGo or Google search engines to find information.

Configuration:

tools:
  web_search:
    enabled: true
    default_engine: duckduckgo
    max_results: 10
    engines:
      - duckduckgo
      - google
    timeout: 10

WebFetch Tool

Fetch content from allowed URLs or GitHub references using the format example.com.

Configuration:

tools:
  web_fetch:
    enabled: true
    allowed_domains:
      - golang.org
      - github.com
    safety:
      max_size: 8192  # 8KB
      timeout: 30
    cache:
      enabled: true
      ttl: 3600  # 1 hour

Hosts of configured A2A agents (each agent's url and artifacts_url, on any port) are always fetchable when A2A is enabled, regardless of allowed_domains - registering an agent is the trust decision, and the A2A tools instruct the model to download artifact URLs with WebFetch.

Browser Tools

Raw browser automation driven through Playwright (CDP under the hood). All four tools share one browser session that launches lazily on first use and persists across calls, so navigation state carries over. The session drives the user's installed browser (the configured browser.channel, default chrome), attaches to an already-running browser when browser.cdp_endpoint is set, or falls back to Playwright's bundled Chromium.

Configured in browser_use.yaml (global enabled flag, per-tool enable flags, and shared rate limiting - same shape as computer_use.yaml). Disabled by default; enable with INFER_BROWSER_USE_ENABLED=true or by editing the file.

  • BrowserNavigate - open a URL; returns the final URL and page title.
  • BrowserClick - click an element by CSS or Playwright selector (e.g. text=Sign in).
  • BrowserType - fill an input element; optional press_enter to submit.
  • BrowserRead - read the page (or one element's) visible text plus URL/title. Also returns browser-initiated events: console messages, auto-dismissed dialogs, and calls page scripts make to window.inferNotify(...) - the browser-to-CLI channel.

Media Tools

ImageGeneration Tool

Generate an image from a text prompt and save it as a PNG under ~/.infer/projects/<project-slug>/artifacts/. The chat model calls the tool when the user asks for an image; the tool sends the prompt as a plain one-off request to /v1/images/generations using the configured image model - no system prompt, no tools, independent of the model selected for the chat session. Image models never appear in the /model selector; they are only reachable through this tool.

Parameters:

  • prompt (required): Text description of the desired image
  • quality (optional): low (default), medium, or high
  • size (optional): 1024x1024 (default), 1536x1024, or 1024x1536

Configuration:

tools:
  image_generation:
    enabled: true
    model: openai/gpt-image-2
    require_approval: false

ImageEdit Tool

Edit an existing image and save the result as a PNG under ~/.infer/projects/<project-slug>/artifacts/. The chat model calls the tool when the user asks to edit an image; the tool reads the input image from a local file path and sends a plain one-off request to /v1/images/edits using the configured image model - no system prompt, no tools, independent of the model selected for the chat session.

Parameters:

  • image (required): Local file path of the image to edit
  • prompt (required): Text description of the desired edit
  • quality (optional): auto (default), low, medium, high, or standard
  • size (optional): 1024x1024 (default), 1536x1024, or 1024x1536

Configuration:

tools:
  image_edit:
    enabled: true
    model: openai/gpt-image-2
    require_approval: false

ImageVariation Tool

Create a variation of an existing image and save the result as a PNG under ~/.infer/projects/<project-slug>/artifacts/. The chat model calls the tool when the user asks for a variation; the tool reads the input image from a local file path and sends a plain one-off request to /v1/images/variations using the configured image model - no system prompt, no tools, independent of the model selected for the chat session.

Parameters:

  • image (required): Local file path of the image to base the variation on
  • size (optional): 1024x1024 (default), 1536x1024, or 1024x1536

Configuration:

tools:
  image_variation:
    enabled: true
    model: openai/gpt-image-2
    require_approval: false

TextToSpeech Tool

Synthesize speech from text and save it as a WAV file. The chat model calls the tool when the user asks to say something aloud or to clone a voice. Two engines are available: gateway (default) sends the request through the gateway's Audio API (/v1/audio/speech) - the built-in local/qwen3-tts model works with the auto-started local gateway, and provider-hosted models work too; qwen3-tts shells out to llama.cpp's llama-tts binary running Qwen3-TTS GGUF models, fully local. Disabled by default: while text_to_speech.enabled is false the tool definition is not sent to the LLM at all. See text-to-speech for setup, engine choice and voice cloning.

Parameters:

  • text (required): The text to speak
  • voice_sample (optional): File name (inside the working directory) of a WAV of the target speaker (~10-30s of clean speech) to clone
  • output_path (optional): File name for the generated WAV, placed inside text_to_speech.output_dir; defaults to a timestamped file

Configuration:

text_to_speech:
  enabled: true
  engine: gateway # gateway (default) | qwen3-tts (local)
  # gateway engine only ("" = local/qwen3-tts):
  # model: openai/gpt-4o-mini-tts
  # voice: alloy
  require_approval: true # optional; unset = no approval, like the image tools

Vision Tools

Computer Tool

Computer is the action-based desktop tool, enabled by computer_use.enabled.

  • accessibility - preferred first observation. Returns compact {role,label,state,bbox} elements for the frontmost application or another target. Bounding boxes use the same frame coordinate space as screenshots and pointer actions. Read-only; no screenshot or vision annotator is invoked.
  • press - performs the accessibility press action on the first element with an exact label, without moving the cursor or taking a screenshot.
  • screenshot - captures a fresh screen image or a native-resolution region. Use this when the accessibility result says the tree is empty, unavailable, unsupported, or insufficient.
  • cursor, move, click, double_click, triple_click, scroll, type, and key - inspect or operate the pointer and keyboard.

The accessibility and press actions accept an optional target: frontmost (default), dock, menubar, pid:<number>, app:<name>, or a bare application name. press also requires the exact label returned by accessibility.

Under computer_use.approval: destructive, accessibility, screenshot, and cursor bypass approval; press and the input actions require approval.

GetLatestFrame Tool

Fetch the most recent frame from a named frame source: the built-in screen source (computer-use screenshot streaming) or any directory source configured under vision.sources (e.g. camera frames written to disk). Enabled whenever at least one frame source is registered.

Parameters:

  • source (optional): Frame source name. Defaults to the only registered source, or screen when several exist.
  • format (optional): regular (raw image attached) or annotated (scene summary + numbered elements with bounding boxes, produced by the configured vision.annotator, replacing the image). When omitted: annotated if an annotator is configured, otherwise regular.

For the screen source, annotated output includes element centers usable directly with MouseClick. Annotated frames carry no base64 - the text replaces the image, so text-only models can use the tool directly; vision models can always request format: regular.

ImageDecode Tool

Describe an arbitrary local image file or http(s) URL through the vision annotator, optionally answering a specific question about it. Read-only, no approval required. Enabled when vision.annotator is configured.

Parameters:

  • image (required): Local file path or http(s) URL of the image
  • prompt (optional): A question to answer about the image

Configuration (see Configuration Reference):

vision:
  annotator:
    enabled: true
    model: anthropic/claude-haiku-4-5-20251001 # any vision model served by your gateway

Accessibility Provider

The macOS provider uses PureGo to call CoreFoundation, CoreGraphics, and AXUIElement directly; it has no cgo, Swift, or Objective-C source. Native calls run in a short-lived helper process using JSON over standard I/O. A helper crash, timeout, missing Accessibility permission, or unavailable tree returns screenshot fallback guidance to the agent instead of terminating the CLI. Grant the infer process permission in System Settings > Privacy & Security > Accessibility.

Linux AT-SPI and Windows UIA providers can implement the same provider contract later. Until then, those platforms report unsupported; use screenshot for accessibility actions while the other Computer actions continue to work.

Workflow Tools

TodoWrite Tool

Create and manage structured task lists for LLM-assisted development workflows.

Parameters:

  • todos (required): Array of todo items with status tracking
    • id (required): Unique identifier for the task
    • content (required): Task description
    • status (required): Task status - "pending", "in_progress", or "completed"

Features:

  • Structured Task Management: Organized task tracking with status
  • Real-time Updates: Mark tasks as in_progress/completed during execution
  • Progress Tracking: Visual representation of task completion
  • LLM Integration: Designed for LLM-assisted development workflows

Security:

  • No File System Access: Pure memory-based operation
  • Validation: Validates todo structure and status values
  • Size Limits: Configurable limits on todo list size

Example:

{
  "todos": [
    {
      "id": "1",
      "content": "Update README with new tool documentation",
      "status": "in_progress"
    },
    {
      "id": "2",
      "content": "Add test cases for new features",
      "status": "pending"
    }
  ]
}

Configuration:

tools:
  todo_write:
    enabled: true
    require_approval: false

RequestPlanApproval Tool

Submits a finalized plan for user approval and persists it as a Markdown file under <configDir>/plans/. Available only when the agent is in Plan Mode (toggle via Shift+Tab in the chat TUI).

📖 For the full plan-mode workflow, see Plan Mode Guide.

How it works:

  • The plan is written atomically to <configDir>/plans/<YYYY-MM-DD-HHMMSS>-<slug>.md (e.g. ~/.infer/plans/2026-04-27-103015-add-login-flow.md).
  • The chat TUI shows the rendered plan with Accept (auto-accept mode), Reject, and Approve Each Step (standard mode) options.
  • On accept, the agent switches out of plan mode and executes the plan.
  • On reject, the file remains on disk as an audit trail; the user can reply with feedback and the agent re-iterates.
  • The LLM is instructed to ask clarifying questions in normal assistant turns first, and only call this tool when the plan is complete.

Parameters:

  • title (required): A short human-readable phrase (≤ 60 chars, no slashes or ..). Becomes the H1 heading of the saved file and the basis of the filename slug.
  • plan (required): The full plan as Markdown. Use H2 sections in this order - ## Context, ## Files to Modify, ## Current Code, ## Changes, ## Performance Impact, ## Critical Files, ## Edge Cases, ## Verification. Omit any section that is not applicable.

Example:

{
  "title": "Add login flow",
  "plan": "## Context\n\nUsers can't sign in...\n\n## Files to Modify\n\n- internal/auth/login.go - add handler\n\n## Verification\n\nRun `task test`."
}

Configuration:

The tool is auto-registered and always enabled in plan mode. No config knobs.

RequestApproval Tool

Asks the user to override a tool call the LLM judge rejected (Auto+Judge mode or tools.safety.approval_behaviour: judge). Every judge rejection result hints at this tool; see Judge Mode.

How it works:

  • Only calls the judge actually rejected can be escalated, and each one only once.
  • The chat TUI shows the regular approval box for the rejected call, with the judge's reason and the model's justification above it.
  • Approve arms a one-shot bypass: the model re-issues the identical call and it runs without a judge call. Reject returns the decision to the model as a tool result; the turn continues.
  • Headless runs have no approver, so the tool returns status: no_approver and the model is told not to retry.

Parameters:

  • tool (required): Name of the rejected tool.
  • arguments (required): The exact arguments of the rejected call ({} if none).
  • what (required): What permission is needed, one sentence.
  • why (required): Why the action serves the user's request.

Example:

{
  "tool": "Bash",
  "arguments": { "command": "git push origin feature" },
  "what": "push the feature branch",
  "why": "the user asked me to ship the change"
}

Configuration:

Auto-registered and always advertised. The description is overridable in prompts.yaml under tools.RequestApproval.

Schedule Tool

Create recurring or one-off tasks that the agent runs on a cron schedule and delivers back through the messaging channel that triggered the current session (e.g. Telegram). Useful for "send me X every morning" or "remind me at 6pm today to call mum" - initiated from a chat with the bot.

📖 For an end-to-end walkthrough, see Scheduling Guide.

How it works:

  • Each scheduled job is persisted as a YAML file under ~/.infer/schedules/.
  • The infer daemon process hosts the scheduler and polls storage every 2s, so newly created jobs fire without a restart.
  • Each fire spawns a brand-new infer headless session - no context carries between runs. Make prompts specific and self-contained. A run record (session_id, status, error, timestamps) is persisted per fire, so job output is readable from storage.
  • Channel + recipient are derived automatically from the current session ID - the LLM never passes them. From a channel-driven session the job delivers its output back to that channel; from any other session the job is record-only.
  • One-off jobs (run_once: true) are deleted automatically after their first fire.

Disabled by default. Enable in config under tools.schedule.enabled: true.

Parameters:

  • operation (required): One of create, list, get, update, delete.
  • job_id: Required for get, update, delete.
  • cron_expression: Required for create. Standard 5-field crontab or @every <duration>.
  • prompt: Required for create. The task to give the agent on each fire.
  • run_once (optional, default false): When true, the job is deleted after its first fire.
  • name, description, model: Optional metadata; model overrides agent.model for that job.

The LLM is instructed to always confirm with the user whether they want a one-off or recurring job before creating one - there is no safe default for that decision.

Example - recurring:

{
  "operation": "create",
  "cron_expression": "0 8 * * *",
  "prompt": "Find an inspiring quote for today and respond with the quote and its author. Keep it under 3 sentences.",
  "name": "Daily morning quote"
}

Example - one-off reminder:

{
  "operation": "create",
  "cron_expression": "0 18 26 4 *",
  "prompt": "Remind me to call mum.",
  "run_once": true,
  "name": "Call mum reminder"
}

Example - list:

{ "operation": "list" }

Example - delete:

{ "operation": "delete", "job_id": "0a1b2c3d-..." }

Configuration:

tools:
  schedule:
    enabled: false              # disabled by default
    require_approval: true      # require approval by default
    storage_dir: ""             # default: ~/.infer/schedules
    max_jobs: 100

Security:

  • Approval required by default - the LLM cannot create/modify schedules without user confirmation.
  • Channel must be configured for delivery - a channel-driven session that references a channel not enabled in channels.<name>.enabled errors out instead of silently skipping delivery.
  • Daemon-bound execution - jobs only fire while infer daemon is running.

Agent-to-Agent Communication

The A2A (Agent-to-Agent) tools enable communication between the CLI client and specialized A2A server agents, allowing for task delegation, distributed processing, and agent coordination.

📖 For detailed configuration instructions, see A2A Agents Configuration Guide

A2A_SubmitTask Tool

Submit tasks to specialized A2A agents for distributed processing.

Parameters:

  • agent_url (required): URL of the A2A agent server
  • task_description (required): Description of the task to perform
  • metadata (optional): Additional task metadata as key-value pairs

Features:

  • Task Delegation: Submit complex tasks to specialized agents
  • Streaming Responses: Real-time task execution updates
  • Metadata Support: Include contextual information with tasks
  • Task Tracking: Automatic tracking of submitted tasks with IDs
  • Error Handling: Comprehensive error reporting and retry logic

Examples:

  • Code analysis: agent_url: "http://security-agent:8080", task_description: "Analyze codebase for security vulnerabilities"
  • Documentation: agent_url: "http://docs-agent:8080", task_description: "Generate API documentation"
  • Testing: agent_url: "http://test-agent:8080", task_description: "Create unit tests for UserService class"

A2A_QueryAgent Tool

Retrieve agent capabilities and metadata for discovery and validation.

Parameters:

  • agent_url (required): URL of the A2A agent to query

Features:

  • Agent Discovery: Query agent capabilities and supported task types
  • Health Checks: Verify agent availability and status
  • Metadata Retrieval: Get agent configuration and feature information
  • Connection Validation: Test connectivity before task submission

Examples:

  • Capability check: agent_url: "http://agent:8080" - Returns agent card with available features
  • Health status: Query agent before submitting critical tasks

A2A_QueryTask Tool

Query the status and results of previously submitted tasks.

Parameters:

  • agent_url (required): URL of the A2A agent server
  • context_id (required): Context ID for the task
  • task_id (required): ID of the task to query

Features:

  • Status Monitoring: Check task completion status and progress
  • Result Retrieval: Access task outputs and generated content
  • Error Diagnostics: Get detailed error information for failed tasks
  • Artifact Discovery: List available artifacts from completed tasks

Examples:

  • Status check: agent_url: "http://agent:8080", context_id: "ctx-123", task_id: "task-456"
  • Result access: Retrieve task outputs and completion details

A2A Workflow Example

1. Query agent capabilities:        A2A_QueryAgent
2. Submit task for processing:      A2A_SubmitTask
3. Monitor task progress:           A2A_QueryTask

A2A Configuration

A2A tools are configured in the tools section:

a2a:
  enabled: true
  tools:
    submit_task:
      enabled: true
      require_approval: true
    query_agent:
      enabled: true
      require_approval: false
    query_task:
      enabled: true
      require_approval: false

Note: Artifact downloads from A2A tasks are handled via the WebFetch tool with download=true. Files are automatically saved to <configDir>/tmp with the filename extracted from the download URL.

A2A Use Cases

  • Code Analysis: Submit codebases to security or quality analysis agents
  • Documentation Generation: Generate API docs, README files, or technical documentation
  • Testing: Create comprehensive test suites with specialized testing agents
  • Data Processing: Process large datasets with specialized data analysis agents
  • Content Creation: Generate content with specialized writing or design agents

For detailed A2A documentation and examples, see A2A Agents Configuration Guide.

← Back to README