Tool Registry

The ToolRegistry holds all available tools and dispatches invocations. It validates required parameters before calling handlers and returns clean error results on failure.

flowchart LR
    Register["register(tool)"] --> Registry["ToolRegistry"]
    Registry --> Validate["Validate<br/>required params"]
    Validate --> PreHook["Pre-hooks<br/>(auth, logging)"]
    PreHook --> Handler["Tool handler"]
    Handler --> PostHook["Post-hooks"]
    PostHook --> Result["ToolResult"]

Usage

from hybi.agent import AgentSession, ToolDefinition, ToolParameter, ToolResult, ToolCall

session = AgentSession.create(hb)
registry = session.tool_registry

# List all tools
all_tools = registry.list_tools()

# Filter by category
shape_tools = registry.list_tools(category="shape")
query_tools = registry.list_tools(category="query")

# Check tool count and membership
len(registry)            # 10
"search" in registry     # True

# Look up a tool by name
tool = registry.get("search")

# Invoke a tool call
call = ToolCall(id="call_1", name="search", arguments={"query": "kinase"})
result = await registry.invoke(call, session)

Registering Custom Tools

async def my_handler(session, *, query: str) -> ToolResult:
    return ToolResult(success=True, data={"answer": query})

custom_tool = ToolDefinition(
    name="my_tool",
    description="A custom tool",
    parameters=[ToolParameter(name="query", type="string", description="Input")],
    category="external",
    handler=my_handler,
)

registry.register(custom_tool)

Exporting Schemas

# Raw JSON-serializable schemas (adapters translate further)
schemas = registry.export_schemas()

---

ToolRegistry

Hooks

Pre- and post-invocation hooks for validation, logging, or middleware:

async def auth_hook(call, session):
    if call.name == "manage" and not session.is_admin:
        raise ValueError("Unauthorized")

registry.register_pre_hook(auth_hook)

# Post-hooks receive (call, session, result)
async def log_hook(call, session, result):
    print(f"{call.name} -> {result.success}")

registry.register_post_hook(log_hook)

A pre-hook that raises blocks the tool call and returns a failed ToolResult.

---

ToolRegistry

hybi.agent.registry.ToolRegistry

Registry of all available tools.

Tools are registered by name and looked up during invocation. The registry also supports filtering by category and exporting tool schemas for framework adapters.

Supports pre- and post-invocation hooks for middleware patterns (logging, gating, meta-reasoning capture, etc.).

tool_names property

register(tool)

Register a tool definition.

register_many(tools)

Register multiple tool definitions.

get(name)

Look up a tool by name.

list_tools(category=None)

List all registered tools, optionally filtered by category.

invoke(call, session) async

Invoke a tool by dispatching to its handler.

Runs pre-hooks before execution and post-hooks after.

Parameters:

Name	Type	Description	Default
call	ToolCall	Parsed tool call from the LLM.	required
session	AgentSession	The active agent session (passed to the handler).	required

Returns:

Type	Description
ToolResult	ToolResult from the handler, or an error result if the tool
ToolResult	is not found or the handler raises.

export_schemas()

Export all tool definitions as JSON-serializable dicts.

This is the raw schema; framework adapters translate it further into provider-specific formats.

register_pre_hook(hook)

Register a pre-invocation hook.

Hook signature: async (call, session) -> Optional[ToolCall] Return None to block the call (invoke returns a blocked result). Return a ToolCall (original or modified) to proceed.

register_post_hook(hook)

Register a post-invocation hook.

Hook signature: async (call, result, session) -> Optional[ToolResult] Return None to pass through the original result unchanged. Return a ToolResult to replace it.

remove_hook(hook, kind=None)

Remove a previously registered pre- or post-hook.

Parameters:

Name	Type	Description	Default
hook	Callable	The hook callable to remove.	required
kind	Optional[str]	'pre', 'post', or None (scans both).	None

Returns:

Type	Description
bool	True if the hook was found and removed, False otherwise.