Tools and Execution

Genbase Modules perform tasks by executing Tools. There are two primary types of Tools, differing significantly in how they are defined and executed:

1. Kit Tools: Code defined within a Kit, run in isolated Docker containers.
2. Internal Tools: Methods defined directly within an Agent's Python class, run within the main Engine process.

1. Kit Tools

These represent reusable, potentially complex pieces of code logic packaged within a Kit.

• Purpose: Encapsulate core operational logic tied to the Kit's capability (e.g., database operations, API calls, file processing). They are designed to be shareable and versioned with the Kit.
• Definition:
  • Written as Python functions in the Kit's tools/ directory.
  • Declared in kit.yaml under profiles or provide, including name, path (e.g., check_connections), and description.
• Metadata: Function signatures/docstrings are parsed into an OpenAI-compatible schema for LLM understanding.
• Execution: Run securely in isolated Docker containers managed by the ToolService.

Secure Execution Environment

When an Agent invokes a Kit Tool:

1. Image Preparation: Genbase finds or builds a Docker image containing the Kit's specified base image and Python dependencies (requirements.txt). Images are cached for efficiency.
2. Container Launch: A temporary container is started from this image.
3. Environment Setup:
   • The Module's environment variables are injected.
   • The Module's Workspace (Git repo) is mounted read-write at /repo.
   • The Kit's tools/ directory is mounted read-only at /tools.
   • Defined ports are mapped.
4. Execution: The specified Python function is executed within the container.
5. Result Retrieval: The return value (or error) is captured and sent back to the Agent.

Diagram: Kit Tool execution flow involving Docker isolation.

2. Internal Tools

These are methods defined directly on the Agent class itself, often decorated or registered specifically to be callable like Tools.

• Purpose: Provide functionality tightly coupled to the Agent's internal logic or state, often for simpler tasks that don't require external dependencies or heavy computation (e.g., modifying agent memory, formatting output, simple utility functions).
• Definition:
  • Implemented as methods within the Agent's Python class (inheriting from BaseAgent).
  • Often marked with a decorator (like the @tool decorator seen in BaseAgent's code) or registered programmatically using the InternalToolManager.
• Metadata: Similar to Kit Tools, metadata (parameters, description) is typically extracted from the method signature and docstring for the LLM.
• Execution: Run directly within the main Genbase Engine process as part of the Agent's execution flow. They have access to the Agent's self instance and any services available to the Agent (like self.utils, self.services).

Execution Flow

Diagram: Internal Tool execution flow (direct method call).

Both types of Tools allow Agents to perform tasks beyond just generating text, but they serve different purposes and have distinct execution models and security implications. The kit.yaml only declares Kit Tools; Internal Tools are discovered from the Agent's code.