Framework Adapters¶

The Almanak agent tools package includes adapters for three popular LLM frameworks. All adapters read from the same ToolCatalog -- they are pure format transforms with no business logic.

almanak/framework/agent_tools/adapters/
├── openai_adapter.py      # OpenAI function calling
├── mcp_adapter.py         # Model Context Protocol
└── langchain_adapter.py   # LangChain / LangGraph

OpenAI Function Calling¶

The default adapter, used by all bundled examples. Converts the catalog to OpenAI's tools format for the Chat Completions API.

from almanak.framework.agent_tools import get_default_catalog

catalog = get_default_catalog()

# Generate OpenAI-compatible tool definitions
tools = catalog.to_openai_tools()
# [{"type": "function", "function": {"name": "get_price", "description": "...", "parameters": {...}}}, ...]

# Pass to OpenAI Chat Completions
response = client.chat.completions.create(
    model="gpt-4o",
    messages=messages,
    tools=tools,
)

Or use the explicit adapter:

from almanak.framework.agent_tools.adapters.openai_adapter import get_openai_tools

tools = get_openai_tools(catalog)

This is the simplest integration path. See examples/agentic/shared/agent_loop.py for a complete agent loop implementation.

MCP (Model Context Protocol)¶

The MCP adapter wraps the tool catalog and executor as an MCP server, compatible with Claude Desktop, Cursor, and any MCP client.

from almanak.framework.agent_tools.adapters.mcp_adapter import AlmanakMCPServer

server = AlmanakMCPServer(executor)

# List available tools (MCP tools/list)
tools = server.tools_list()

# Execute a tool call (MCP tools/call)
result = await server.tools_call("get_price", {"token": "ETH", "chain": "arbitrum"})

MCP Resources¶

The server exposes four read-only resources for agent context:

URI	Description
`almanak://chains`	Supported blockchain networks
`almanak://protocols`	Available DeFi protocols per chain
`almanak://risk-policy/current`	Active agent policy constraints
`almanak://wallet/capabilities`	Wallet address and available tools

# List resources (MCP resources/list)
resources = server.resources_list()

# Read a resource (MCP resources/read)
chains = server.resources_read("almanak://chains")
# {"contents": [{"uri": "almanak://chains", "text": "{\"chains\": [\"ethereum\", \"arbitrum\", ...]}"}]}

Claude Desktop Configuration¶

The entry point is the almanak mcp serve CLI command. Point your Claude Desktop config at it:

{
  "mcpServers": {
    "almanak": {
      "command": "almanak",
      "args": ["mcp", "serve"],
      "env": {
        "ALMANAK_GATEWAY_GRPC_HOST": "localhost",
        "ALMANAK_GATEWAY_GRPC_PORT": "50051",
        "ALMANAK_PRIVATE_KEY": "your-key"
      }
    }
  }
}

almanak mcp serve accepts --schema-only (serve tool schemas without a gateway connection), --max-single-trade-usd / --allowed-chains (policy overrides), and --gateway-host / --gateway-port.

Programmatic embedding

The CLI serves over stdio via almanak.framework.agent_tools.adapters.mcp_server.AlmanakMCPStdioServer (an awaitable .run() loop). The AlmanakMCPServer class shown above is a lower-level request/response helper (tools_list / tools_call / resources_*) for embedding in a custom transport — it does not own the stdio loop itself. Prefer almanak mcp serve (or AlmanakMCPStdioServer) for a ready-to-run stdio server.

LangChain / LangGraph¶

The LangChain adapter converts Almanak tools into StructuredTool instances, compatible with LangChain agents and LangGraph graphs.

Requires: pip install langchain-core

from almanak.framework.agent_tools.adapters.langchain_adapter import get_langchain_tools

tools = get_langchain_tools(catalog, executor)
# Returns list[StructuredTool] -- pass directly to a LangChain agent

Each tool wraps the executor's execute() method with full schema validation and policy enforcement. Both sync and async execution are supported.

LangGraph Example¶

from langgraph.prebuilt import create_react_agent

tools = get_langchain_tools(catalog, executor)
agent = create_react_agent(model, tools)

result = await agent.ainvoke({
    "messages": [{"role": "user", "content": "Buy $10 of ETH on Arbitrum"}]
})

Choosing an Adapter¶

Framework	Adapter	Best For
OpenAI Chat Completions	`catalog.to_openai_tools()`	Simplest path, any OpenAI-compatible API
MCP	`AlmanakMCPServer`	Claude Desktop, Cursor, MCP-native clients
LangChain / LangGraph	`get_langchain_tools()`	LangChain agents, LangGraph graphs, complex orchestration

All adapters enforce the same AgentPolicy -- switching frameworks does not change the safety model.