vsagent Developer Guide | Valstorm Docs

This guide covers the internal mechanics, tool extension patterns, and developer workflows for customizing and extending the Valstorm Agent Runtime (vsagent).

1. Tool Creation Pattern

All tools in vsagent follow the Python type-hinted declaration format with docstrings that the model uses for function calling:

PYTHON

from vsagent.core.tools import tool

@tool
def calculate_growth_rate(initial: float, final: float) -> float:
    """Calculates the percentage growth rate between two values.
    
    Args:
        initial: Starting numerical value.
        final: Ending numerical value.
    """
    if initial == 0:
        return 0.0
    return ((final - initial) / initial) * 100.0

2. In-Memory LSP Diagnostic Pipeline

When patch_file or write_file is executed, the runtime intercepts the write operation and evaluates language-specific diagnostics:

Python (.py): ast.parse() verifies AST syntax, followed by ruff check --concise.
TypeScript/JavaScript (.ts, .tsx, .js): Runs workspace tsc --noEmit to catch type errors.
YAML / JSON: Validates syntax and schema validity in-memory.

If errors are detected, the tool returns the compiler error output directly into the next turn, prompting the agent to self-correct before the developer notices.

3. Subagent Task Delegation

Delegate specialized work to subagents without polluting parent conversation context:

PYTHON

# In parent tool execution
result = await delegate_task(
    profile="researcher",
    goal="Extract all API rate limit thresholds from our vendor documentation files"
)