Tools & Types

Core type definitions used across the agent toolkit. These are framework-agnostic—they work the same regardless of which LLM provider you use.

flowchart LR
    Def["ToolDefinition<br/>(name, params, handler)"] --> Registry
    Registry["ToolRegistry"] --> Call["ToolCall<br/>(id, name, args)"]
    Call --> Handler["handler()"]
    Handler --> Result["ToolResult<br/>(success, data/error)"]
    Result --> Context["ContextBlock<br/>(rendered for LLM)"]

Overview

Type	Purpose
ToolDefinition	Schema for a single tool (name, parameters, handler)
ToolParameter	One parameter in a tool definition
ToolCall	A parsed tool invocation from the LLM
ToolResult	The result of executing a tool
ContextBlock	A structured block of context rendered for the LLM

---

ToolDefinition

A framework-agnostic tool schema. Adapters translate these to provider-specific formats (OpenAI functions, Anthropic tool_use, MCP).

from hybi.agent import ToolDefinition, ToolParameter, ToolResult

async def my_handler(session, *, query: str, limit: int = 5) -> ToolResult:
    results = do_something(query, limit)
    return ToolResult(success=True, data=results)

tool = ToolDefinition(
    name="my_tool",
    description="Does something useful",
    parameters=[
        ToolParameter(name="query", type="string", description="Search query"),
        ToolParameter(name="limit", type="number", description="Max results", required=False),
    ],
    category="external",
    handler=my_handler,
)

Registering a Custom Tool

from hybi.agent import AgentSession

session = AgentSession.create(hb, tools=[tool])
# or add later:
session.tool_registry.register(tool)

hybi.agent.tools.ToolDefinition dataclass

Framework-agnostic tool schema.

The single type that all tools are defined as, regardless of which LLM framework invokes them. The handler is an async callable that receives the AgentSession and keyword arguments from the tool call.

---

ToolParameter

A single parameter in a tool definition.

hybi.agent.tools.ToolParameter dataclass

A single parameter in a tool definition.

---

ToolCall

A parsed tool invocation from the LLM. Adapters convert provider-specific formats into ToolCall objects.

from hybi.agent import ToolCall

call = ToolCall(
    id="call_abc123",
    name="search",
    arguments={"query": "kinase inhibitors", "top_k": 5},
)

hybi.agent.tools.ToolCall dataclass

A parsed tool invocation from the LLM.

---

ToolResult

Result of executing a tool.

from hybi.agent import ToolResult

# Success
result = ToolResult(success=True, data={"rows": [...]})

# Failure
result = ToolResult(success=False, error="Collection 'foo' not found")

hybi.agent.tools.ToolResult dataclass

Result of executing a tool.

Simplified from agent/tools.py — no observations or context_updates. Tool handlers call hb.ingest() directly for mutations. Session's collections dict is the state tracker.

---

ContextBlock

A structured block of context rendered for the LLM. Priority determines rendering order when the token budget is tight—higher priority blocks are rendered first.

from hybi.agent import ContextBlock

block = ContextBlock(
    category="schema",
    priority=10.0,
    content="drugs: catalog [name, mechanism, indication] (150 rows)",
    source="session",
)

hybi.agent.tools.ContextBlock dataclass

A structured block of context rendered for the LLM.

Priority determines rendering order when token budget is tight. Higher priority blocks are rendered first.