Agent API

The Agent module provides a tool-calling interface that lets LLMs interact with HyperBinder directly.

Architecture

flowchart LR
    Session["AgentSession\nstate owner"] --> Registry["ToolRegistry\n10 tools"]
    Registry --> Loop["AgentLoop\nturn executor"]
    Session --> HB["HyperBinder\nbackend"]
    Loop --> Adapters["Adapters\nOpenAI / Anthropic / MCP"]

Quick Reference

Component	Description	Link
AgentSession	Session state: collections, intersections, registry	Reference
Tools & Types	ToolDefinition, ToolCall, ToolResult, ContextBlock	Reference
Built-in Tools	10 tools: ingest, mutate, search, select, aggregate, join, navigate, explore, connect, manage	Reference
ToolRegistry	Register, list, and invoke tools	Reference
AgentLoop	Turn lifecycle: render → execute → re-render	Reference
Adapters	OpenAI, Anthropic, MCP format translation	Reference
Sandbox	Code execution with AST validation and subprocess isolation	Reference
Procedural Memory	Error-to-success pattern learning across sessions	Reference

Common Imports

# Session
from hybi.agent import AgentSession, CollectionMeta, IntersectionMeta

# Core types
from hybi.agent import ToolDefinition, ToolParameter, ToolCall, ToolResult, ContextBlock

# Loop
from hybi.agent import AgentLoop, TurnInput, TurnResult

# Registry
from hybi.agent import ToolRegistry

# Adapters
from hybi.agent import OpenAIAdapter, AnthropicAdapter, MCPAdapter, FrameworkAdapter

Basic Usage

from hybi import HyperBinder
from hybi.agent import AgentSession, AgentLoop, TurnInput, OpenAIAdapter

# 1. Create session (auto-registers all 10 built-in tools)
hb = HyperBinder()
session = AgentSession.create(hb)

# 2. Set up adapter for your LLM
adapter = OpenAIAdapter()
tools_json = adapter.export_tools(session.tool_registry.list_tools())

# 3. Process a turn with tool calls from the LLM
loop = AgentLoop(session)
turn = TurnInput(role="assistant", content="", tool_calls=parsed_calls)
result = await loop.process_turn(turn)

# 4. Format results back for the LLM
for call, tr in zip(parsed_calls, result.tool_results):
    message = adapter.format_tool_result(call, tr)