Adapters

Framework adapters translate between the toolkit's framework-agnostic types and provider-specific formats. Each adapter implements four operations: export tool schemas, parse tool calls, format results, and render context blocks.

Adapter Pattern

flowchart LR
    TD["ToolDefinition"] -->|export_tools| P["Provider JSON"]
    P -->|parse_tool_call| TC["ToolCall"]
    TR["ToolResult"] -->|format_tool_result| PM["Provider Message"]
    CB["ContextBlock[]"] -->|render_context| S["Prompt String"]

All adapters share the FrameworkAdapter base class. You only interact with adapters at the edges—between your LLM client and the AgentLoop.

---

OpenAI

Works with OpenAI and compatible APIs (Azure OpenAI, Ollama, vLLM).

from openai import OpenAI
from hybi.agent import AgentSession, AgentLoop, TurnInput, OpenAIAdapter

session = AgentSession.create(hb)
loop = AgentLoop(session)
adapter = OpenAIAdapter()
client = OpenAI()

# Export tools for the OpenAI API
tools = adapter.export_tools(session.tool_registry.list_tools())

# Call the LLM
response = client.chat.completions.create(
    model="gpt-4o",
    messages=messages,
    tools=tools,
)

# Parse tool calls from the response
if response.choices[0].message.tool_calls:
    calls = [adapter.parse_tool_call(tc.model_dump()) for tc in response.choices[0].message.tool_calls]

    # Execute via the loop
    turn = TurnInput(role="assistant", content="", tool_calls=calls)
    result = await loop.process_turn(turn)

    # Format results back for OpenAI
    for call, tr in zip(calls, result.tool_results):
        messages.append(adapter.format_tool_result(call, tr))

hybi.agent.adapters.openai.OpenAIAdapter

Bases: FrameworkAdapter

Adapter for OpenAI's function calling format.

export_tools(tools)

Convert to OpenAI function tool format.

parse_tool_call(raw)

Parse an OpenAI tool call response.

Expected format

{"id": "call_xxx", "function": {"name": "...", "arguments": "..."}}

format_tool_result(call, result)

Format result for OpenAI's tool message format.

render_context(blocks)

Render as system message content, highest priority first.

---

Anthropic

Works with the Anthropic Messages API.

import anthropic
from hybi.agent import AgentSession, AgentLoop, TurnInput, AnthropicAdapter

session = AgentSession.create(hb)
loop = AgentLoop(session)
adapter = AnthropicAdapter()
client = anthropic.Anthropic()

# Export tools for the Anthropic API
tools = adapter.export_tools(session.tool_registry.list_tools())

# Call the LLM
response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=4096,
    tools=tools,
    messages=messages,
)

# Parse tool_use blocks
tool_use_blocks = [b for b in response.content if b.type == "tool_use"]
if tool_use_blocks:
    calls = [adapter.parse_tool_call(b.model_dump()) for b in tool_use_blocks]

    turn = TurnInput(role="assistant", content="", tool_calls=calls)
    result = await loop.process_turn(turn)

    # Format results back for Anthropic
    tool_results = [adapter.format_tool_result(c, r) for c, r in zip(calls, result.tool_results)]
    messages.append({"role": "user", "content": tool_results})

Context rendering

AnthropicAdapter.render_context wraps each block in <world_model> XML tags. The other adapters join blocks with double newlines.

hybi.agent.adapters.anthropic.AnthropicAdapter

Bases: FrameworkAdapter

Adapter for Anthropic's tool use format.

export_tools(tools)

Convert to Anthropic tool use format.

parse_tool_call(raw)

Parse an Anthropic tool use content block.

Expected format

{"type": "tool_use", "id": "toolu_xxx", "name": "...", "input": {...}}

format_tool_result(call, result)

Format result for Anthropic's tool_result content block.

render_context(blocks)

Render as system prompt text blocks, highest priority first.

---

MCP

Works with the Model Context Protocol.

from hybi.agent import AgentSession, MCPAdapter

session = AgentSession.create(hb)
adapter = MCPAdapter()

# Export tools as MCP tool definitions
tools = adapter.export_tools(session.tool_registry.list_tools())
# Each tool: {"name": "...", "description": "...", "inputSchema": {...}}

# Parse an MCP tool call
call = adapter.parse_tool_call({"name": "search", "arguments": {"query": "kinase"}})

# Format a result for MCP
result_msg = adapter.format_tool_result(call, result)
# {"content": [{"type": "text", "text": "..."}], "isError": false}

hybi.agent.adapters.mcp.MCPAdapter

Bases: FrameworkAdapter

Adapter for the Model Context Protocol.

export_tools(tools)

Convert to MCP tool definitions.

parse_tool_call(raw)

Parse an MCP tool call.

Expected format

{"name": "...", "arguments": {...}}

format_tool_result(call, result)

Format result for MCP tool result protocol.

render_context(blocks)

Render as MCP resource content, highest priority first.

---

FrameworkAdapter (Base)

Abstract base class. Implement all four methods to add support for a new LLM provider.

from hybi.agent import FrameworkAdapter

class MyAdapter(FrameworkAdapter):
    def export_tools(self, tools):
        ...
    def parse_tool_call(self, raw):
        ...
    def format_tool_result(self, call, result):
        ...
    def render_context(self, blocks):
        ...

hybi.agent.adapters.base.FrameworkAdapter

Bases: ABC

Abstract base for LLM framework adapters.

Subclasses implement the translation between the SDK's framework-agnostic types and provider-specific formats.

export_tools(tools) abstractmethod

Convert SDK tool definitions to provider-specific format.

Parameters:

Name	Type	Description	Default
tools	List[ToolDefinition]	List of ToolDefinition objects.	required

Returns:

Type	Description
List[Dict]	List of dicts in the provider's expected format.

parse_tool_call(raw) abstractmethod

Parse a provider-specific tool call into a ToolCall.

Parameters:

Name	Type	Description	Default
raw	Dict	Raw tool call dict from the LLM response.	required

Returns:

Type	Description
ToolCall	Parsed ToolCall object.

format_tool_result(call, result) abstractmethod

Format a ToolResult for the provider's expected response format.

Parameters:

Name	Type	Description	Default
call	ToolCall	The original tool call.	required
result	ToolResult	The execution result.	required

Returns:

Type	Description
Dict	Dict in the provider's tool result format.

render_context(blocks) abstractmethod

Render context blocks for injection into the LLM prompt.

Parameters:

Name	Type	Description	Default
blocks	List[ContextBlock]	Sorted list of ContextBlock objects.	required

Returns:

Type	Description
str	Formatted string for the provider's system/context format.