Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
"""Base class for agent tools."""
from abc import ABC, abstractmethod
from dataclasses import dataclass
from typing import Any
from vikingbot.config.schema import SessionKey
from vikingbot.sandbox.manager import SandboxManager
# Task-relative storage for complete tool results; these files are not deliverables.
TOOL_RESULT_DIRECTORY = ".tool-results"
@dataclass(frozen=True)
class MultimodalToolResult:
"""A tool result with model-facing content and a text-only representation."""
text: str
content: list[dict[str, Any]]
def __str__(self) -> str:
return self.text
@dataclass
class ToolContext:
"""Context passed to tools during execution, containing runtime information.
This class encapsulates all the runtime context that a tool might need during
execution, including session identification, sandbox access, and sender information.
Attributes:
session_key: Unique identifier for the current session, typically in the format
'channel:chat_id'.
sandbox_manager: Optional manager for sandbox operations like file access and
command execution. If provided, tools can perform sandboxed operations.
workspace_id: Computed workspace identifier derived from the sandbox_manager
and session_key. This determines the sandbox directory for the session.
sender_id: Optional identifier for the message sender, used for tracking
and permission checks.
actor_peer_id: Authenticated OpenViking peer identity for memory and file tools.
memory_peer_ids: Optional list of peer IDs for memory retrieval inside
the current OpenViking user scope.
memory_owner_user_ids: Optional list of explicit OpenViking user IDs
for trusted-mode owner-user memory lookup.
openviking_connection: Optional request-scoped OpenViking identity. Studio
requests use this so tools call OpenViking with the same connection
selected in the browser.
channel_metadata: Channel-specific metadata from the inbound message. Tools
that publish outbound messages can reuse this to preserve delivery context.
Example:
>>> context = ToolContext(
... session_key=SessionKey(channel="telegram", chat_id="12345"),
... sandbox_manager=sandbox_mgr,
... sender_id="user_123"
... )
"""
session_key: SessionKey = None
sandbox_manager: SandboxManager | None = None
workspace_id: str | None = None
sender_id: str | None = None
actor_peer_id: str | None = None
memory_peer_ids: list[str] | None = None
memory_owner_user_ids: list[str] | None = None
memory_user_ids: list[str] | None = None # Deprecated alias for memory_owner_user_ids.
openviking_connection: dict[str, Any] | None = None
channel_metadata: dict[str, Any] | None = None
skill_runtime: Any | None = None
def __post_init__(self) -> None:
if self.memory_owner_user_ids is None and self.memory_user_ids is not None:
self.memory_owner_user_ids = self.memory_user_ids
elif self.memory_user_ids is None and self.memory_owner_user_ids is not None:
self.memory_user_ids = self.memory_owner_user_ids
if self.channel_metadata is None:
self.channel_metadata = {}
if (
self.workspace_id is None
and self.sandbox_manager is not None
and self.session_key
and hasattr(self.sandbox_manager, "to_workspace_id")
):
self.workspace_id = self.sandbox_manager.to_workspace_id(self.session_key)
class Tool(ABC):
"""
Abstract base class for agent tools.
Tools are capabilities that the agent can use to interact with the environment,
such as reading files, executing commands, searching the web, etc. Each tool
defines its own name, description, parameters schema, and execution logic.
To create a new tool, subclass Tool and implement the required abstract
properties and methods:
- name: The unique identifier for the tool
- description: Human-readable explanation of what the tool does
- parameters: JSON Schema defining the tool's input parameters
- execute(): The actual implementation of the tool's functionality
Attributes:
_TYPE_MAP: Internal mapping of JSON schema types to Python types for
parameter validation.
Example:
>>> class GreetingTool(Tool):
... @property
... def name(self) -> str:
... return "greet"
...
... @property
... def description(self) -> str:
... return "Sends a greeting message"
...
... @property
... def parameters(self) -> dict[str, Any]:
... return {
... "type": "object",
... "properties": {
... "name": {"type": "string", "description": "Name to greet"}
... },
... "required": ["name"]
... }
...
... async def execute(self, context: ToolContext, name: str) -> str:
... return f"Hello, {name}!"
"""
_TYPE_MAP = {
"string": str,
"integer": int,
"number": (int, float),
"boolean": bool,
"array": list,
"object": dict,
}
@property
@abstractmethod
def name(self) -> str:
"""Tool name used in function calls."""
pass
@property
@abstractmethod
def description(self) -> str:
"""Description of what the tool does."""
pass
@property
@abstractmethod
def parameters(self) -> dict[str, Any]:
"""JSON Schema for tool parameters."""
pass
@property
def resource_inputs(self) -> dict[str, str]:
"""Parameters that consume a local file or directory.
The remote Skill runtime only rewrites explicitly declared parameters;
it never guesses from parameter names. Keys may be top-level parameter
names or JSON-Pointer-like paths with ``*`` list/dict wildcards.
"""
return {}
@property
def preserve_complete_result(self) -> bool:
"""Whether the model must receive this tool's result without preview truncation."""
return False
@abstractmethod
async def execute(self, tool_context: ToolContext, **kwargs: Any) -> str | MultimodalToolResult:
"""
Execute the tool with given parameters.
Args:
tool_context: Runtime context containing session key, sandbox manager, etc.
**kwargs: Tool-specific parameters.
Returns:
Text result, optionally with model-facing multimodal content.
"""
pass
def validate_params(self, params: dict[str, Any]) -> list[str]:
"""
Validate tool parameters against the tool's JSON schema.
This method validates that the provided parameters match the tool's
defined schema, including type checking, required field validation,
enum validation, and range constraints.
Args:
params: Dictionary of parameter names to values to validate.
Returns:
List of error messages. An empty list indicates the parameters
are valid.
Raises:
ValueError: If the tool's parameter schema is not an object type.
Example:
>>> tool = MyTool()
>>> errors = tool.validate_params({"name": "test", "count": 5})
>>> if errors:
... print("Validation failed:", errors)
... else:
... print("Parameters are valid")
"""
schema = self.parameters or {}
if schema.get("type", "object") != "object":
raise ValueError(f"Schema must be object type, got {schema.get('type')!r}")
return self._validate(params, {**schema, "type": "object"}, "")
def _validate(self, val: Any, schema: dict[str, Any], path: str) -> list[str]:
"""
Recursively validate a value against a JSON schema.
This internal method performs recursive validation of values against
JSON schema definitions, supporting all common JSON schema features
including type checking, enums, ranges, string length, object properties,
and array items.
Args:
val: The value to validate.
schema: The JSON schema to validate against.
path: The current path in the data structure (for error messages).
Returns:
List of validation error messages. Empty list if validation passes.
Note:
This is an internal method used by validate_params(). It should
not be called directly from outside the class.
"""
t, label = schema.get("type"), path or "parameter"
if t in self._TYPE_MAP and not isinstance(val, self._TYPE_MAP[t]):
return [f"{label} should be {t}"]
errors = []
if "enum" in schema and val not in schema["enum"]:
errors.append(f"{label} must be one of {schema['enum']}")
if t in ("integer", "number"):
if "minimum" in schema and val < schema["minimum"]:
errors.append(f"{label} must be >= {schema['minimum']}")
if "maximum" in schema and val > schema["maximum"]:
errors.append(f"{label} must be <= {schema['maximum']}")
if t == "string":
if "minLength" in schema and len(val) < schema["minLength"]:
errors.append(f"{label} must be at least {schema['minLength']} chars")
if "maxLength" in schema and len(val) > schema["maxLength"]:
errors.append(f"{label} must be at most {schema['maxLength']} chars")
if t == "object":
props = schema.get("properties", {})
for k in schema.get("required", []):
if k not in val:
errors.append(f"missing required {path + '.' + k if path else k}")
for k, v in val.items():
if k in props:
errors.extend(self._validate(v, props[k], path + "." + k if path else k))
if t == "array" and "items" in schema:
for i, item in enumerate(val):
errors.extend(
self._validate(item, schema["items"], f"{path}[{i}]" if path else f"[{i}]")
)
return errors
def to_schema(self) -> dict[str, Any]:
"""
Convert tool to OpenAI function schema format.
This method transforms the tool's definition into the format expected by
OpenAI's function calling API, which can be used with chat completions.
Returns:
Dictionary containing the function schema in OpenAI format with:
- type: Always "function"
- function: Object containing name, description, and parameters
Example:
>>> tool = MyTool()
>>> schema = tool.to_schema()
>>> print(schema)
{
'type': 'function',
'function': {
'name': 'my_tool',
'description': 'Does something useful',
'parameters': {'type': 'object', 'properties': {...}}
}
}
"""
return {
"type": "function",
"function": {
"name": self.name,
"description": self.description,
"parameters": self.parameters,
},
}