08 - Extending the Harness Agent

This document serves as a practical implementation guide for extending the apps/agent-server architecture. Designed around an additive extension model, the system allows new capabilities to be integrated via small configuration files and registration snippets without modifying the core request or execution loops. Below is a reference for existing extension paths, followed by architectural improvements that would strengthen the system long-term.

Adding a local tool is the most straightforward extension path. Create tools/your_tool.py exporting two components:

• A SCHEMA dictionary defining the OpenAI function-calling schema (argument descriptions, data types, and constraints).
• An async def implementation function that executes the tool's logic.

Register the tool in tools/registry.py by importing the module and adding one entry each to the SCHEMAS list and _FUNCTIONS name-to-callable dictionary. Because agent_loop.py and graph.py interact with tools exclusively through the registry, they require zero source modifications.

Injecting Trusted Context: If a tool requires server-supplied context (e.g., authenticated user identity or session state), declare a parameter matching the expected name (following the existing partition_key pattern used by memory-aware tools). The call_tool() method inspects the function's real signature and injects these values automatically. Model-provided arguments with identical names cannot override this; server-supplied context always takes precedence, preserving a critical security boundary against LLM spoofing.

When a capability already exists as a Model Context Protocol (MCP) server—ranging from web search to domain-specific data sources—wiring it up typically requires less effort than writing a custom tool manually. Add an entry to apps/agent-server/mcp_servers.json (not the .example.json companion, which is strictly inert reference documentation). Each entry follows this structure:

{
  "name": "...",
  "command": "...",
  "args": [...],
  "env": {...}
}

Restart the server and verify connectivity via the /health endpoint (mcp_tools_registered count).

Pre-flight Checklist: Always smoke-test the server locally (npx <package> or uvx <package>, depending on distribution) before wiring it into the project. Two pre-configured servers (fetch, secedgar) failed on import against the installed SDK despite installing cleanly; testing prevents assumption-based deployment failures. Consult MCP_SERVERS_CATALOG.md for a researched shortlist across web search, PDF handling, structured planning, and financial data before researching new options from scratch.

Known Constraints:

• Only stdio transport is supported. HTTP or SSE-only MCP servers cannot be wired without building a custom transport layer first (a scoped project if a specific tool demands it).
• Isolation is built-in: a failing server registers zero tools, logs a warning, and allows other servers to start normally. Speculative additions are genuinely low-risk.

Skills represent the lowest-friction extension point in the architecture. Simply drop a Markdown file into apps/agent-server/skills/ containing YAML frontmatter (description: ...) followed by the guidance text you want injected into the system prompt upon match. No registration code is required—the file's existence acts as the wiring.

Skills are matched via keyword overlap against the user's message, with a hard limit of exactly one skill injected per request. If your new skill shares vocabulary with an existing one, fold the guidance into the original file to prevent silent match failures rather than creating overlapping files that will never win the injection slot.

Note: A server restart is required to register new or modified skill files. Unlike AGENT.md (which is re-read fresh on every request), skills are cached at process startup.

Hooks execute at precisely two lifecycle moments: immediately before a tool executes, and immediately after a real (non-blocked) tool call returns. Create hooks/your_hook.py, define the appropriate signature, and register it via register_pre_tool() or register_post_tool(). Add a single import line to hooks/__init__.py to activate it.

Hook Signatures:

• Pre-tool hook: fn(tool_name, arguments) -> dict | None. Returning a dict blocks the actual tool call and returns that dictionary as the result (ideal for policy enforcement, mirroring the existing write-path guard).
• Post-tool hook: fn(tool_name, arguments, result) -> None. Designed purely for side effects (e.g., triggering a background re-index after a successful write, using the knowledge-base auto-sync hook as a template).

All hooks run defensively: a single hook raising an exception is caught, logged, and skipped. Bugs isolate to the hook itself rather than crashing the active request or service.

Model routing and switching are fully managed via configuration passthrough to Ollama. No source code changes are required. For detailed configuration and selection strategies, consult 07_Switching_LLM_Models_Guide.md.

Beyond the additive extension points above, several structural enhancements would meaningfully strengthen the system. These are listed in rough order of leverage:

Every extension point exists because the original architecture deliberately separated "the thing that changes" (tools, skills, hooks, MCP servers, models) from "the thing that doesn't" (request pipeline, graph executor, auth layer).

When building an extension, the strongest validation of your approach is that it requires writing exactly one new file and a few lines of registration. If an extension demands modification to agent_loop.py's core control flow or graph.py's executor itself, pause to evaluate whether the registry/hook/skill pattern can be expanded first. This deliberate separation is what has kept the codebase compact, auditable, and stable across eight build phases in four days.

• Additive-by-design: New capabilities integrate via small, isolated files and registry bindings without touching core orchestration loops.
• Server-enforced security: Trusted context injection uses real Python function signatures, making LLM argument spoofing structurally impossible.
• Hard limits exist: MCP relies exclusively on stdio transport; skills cache at startup and inject exactly one match per request based on keyword overlap.
• Hooks fail gracefully: Both pre- and post-tool hooks run defensively, isolating exceptions from the main execution pipeline.
• Prioritize structural leverage: Route models server-side, unify streaming paths before budgeting changes, and plan shared caching architecture early to avoid scaling debt.