Tool Execution

Last updated: April 11, 2026

Assistant Tool Execution

The assistant module features a dynamic, extensible tool execution framework. Tools are external capabilities that agents can invoke to interact with the world.

Tool Definition

Tools are defined as a pair of files in the prompts/tools/ directory:

  1. Markdown (.md): Defines the tool's purpose, input parameters (JSON schema), and access roles.
  2. Shell Script (.sh): The actual implementation of the tool.

Tool Categories

  • Shared: Common tools available across most agent sessions (e.g., websearch, notify_user).
  • PM (Project Management): Tools used by the AntFarm Queen for orchestration (pm_*).
  • BM (Business Management): Tools for business operations used by the Business Hive (bm_*).
  • Agent-Specific: Tools restricted to specific personas (e.g., nikki_lights, sasha_proxmox).

Execution Lifecycle

The Planner (in assistant/planner.go) manages the tool execution lifecycle within the ReAct loop:

  1. Inference: The LLM requests a tool call in its response.
  2. Parsing: The planner parses the JSON tool call from the text.
  3. Validation:
    • RBAC Check: Ensures the user's role and the session's agent have permission to use the tool.
    • Syntax Check: Validates the arguments against the tool's JSON schema.
  4. Execution: The planner executes the tool's shell script with the provided arguments.
  5. Output Capture: The script's stdout/stderr is captured and formatted as a ToolResult.
  6. Observation: The ToolResult is appended to the session's history as an "Observation" for the LLM.

Key Files & Functions

  • assistant/assistant.go: Loads and filters tools during NewChatSession.
  • assistant/planner.go: Contains the ExecuteTool function which handles the actual shell invocation.
  • prompts/tools/: The root directory for all tool definitions.

Tool Execution Flow Chart

flowchart TD
    LLM[LLM Response] --> Parse{Parse Tool Call?}
    Parse -- Yes --> Validate[RBAC & Schema Check]
    Parse -- No --> Respond[Return Final Answer]
    Validate -- Valid --> Exec[Execute .sh Script]
    Validate -- Invalid --> Error[Return Error Observation]
    Exec --> Result[Capture Stdout/Stderr]
    Result --> History[Add to Session History]
    History --> LLM
    Error --> History

Guidance for AI Agents

  • Argument Precision: Ensure tool arguments strictly follow the JSON schema defined in the tool's .md file.
  • Handle Errors: If a tool returns an error, analyze it and try a different approach or fix the arguments.
  • Dynamic Discovery: Use the list_available_tools tool to discover what you can do in the current session.

Cross-References