docs(integrations): add 10-line recipes for LlamaIndex/CrewAI/AutoGen/LangGraph #62
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,209 @@ | ||
| --- | ||
| description: "Connect LlamaIndex, CrewAI, AutoGen, and LangGraph to Hebb Mind in ~10 lines — write and recall long-term agent memory over the MCP server or REST API." | ||
| --- | ||
|
|
||
| # Use Hebb Mind from a Python Agent Framework | ||
|
|
||
| Hebb Mind ships two surfaces any Python agent framework can talk to today — no | ||
| native adapter package required: | ||
|
|
||
| - **MCP stdio server** (`hebb-mcp`) exposing `write_memory` / `search_memory` / | ||
| `consolidate` / `ingest_conversation` (see [MCP Integration](./mcp-integration.md)). | ||
| - **REST API** at `http://localhost:8321` — `POST /api/v1/search` with | ||
| `{"query": ..., "top_k": ...}` and `POST /api/v1/memories`. | ||
|
|
||
| Each snippet below wraps one of these surfaces for a popular framework. They are | ||
| copy-paste runnable against a locally running Hebb Mind service. | ||
|
Comment on lines
+15
to
+16
There was a problem hiding this comment. 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win 🧩 Analysis chain🏁 Script executed: #!/bin/bash
set -euo pipefail
echo "== files =="
git ls-files 'repo_pages/guide/framework-integrations.md' 'repo_pages/zh/guide/framework-integrations.md' || true
echo "== line counts =="
for f in repo_pages/guide/framework-integrations.md repo_pages/zh/guide/framework-integrations.md; do
if [ -f "$f" ]; then
wc -l "$f"
fi
done
echo "== relevant snippets =="
for f in repo_pages/guide/framework-integrations.md repo_pages/zh/guide/framework-integrations.md; do
if [ -f "$f" ]; then
echo "--- $f lines 1-130 ---"
sed -n '1,130p' "$f" | nl -ba -v1
fi
done
echo "== search env/keys/openai in repo_pages guide =="
rg -n "OPENAI_API_KEY|api_key|api-key|OPENAI|openai|model credential|credential|copy-paste|runnable|http://localhost:8321" repo_pages/guide/framework-integrations.md repo_pages/zh/guide/framework-integrations.md || true
echo "== inspect framework/integration sections around OpenAI-backed recipes =="
for f in repo_pages/guide/framework-integrations.md repo_pages/zh/guide/framework-integrations.md; do
if [ -f "$f" ]; then
echo "--- $f lines 1-230 ---"
sed -n '1,230p' "$f" | nl -ba -v1
fi
doneRepository: afx-team/hebb-mind Length of output: 2486 🏁 Script executed: #!/bin/bash
set -euo pipefail
echo "== try LFS skip/smudge workarounds =="
git config --local lfs.fetchexclude "$(git ls-files | rg '(^|/)eval/data/' || true | tr '\n' ',' | sed 's#,$##')" 2>/dev/null || true
git lfs install --force 2>/dev/null || true
git fetch origin --depth 1 --no-tags 2>/dev/null || true
git checkout --force --no-lazy-remote -- .repo_pages 2>/dev/null || true
echo "== files =="
git ls-files 'repo_pages/guide/framework-integrations.md' 'repo_pages/zh/guide/framework-integrations.md' || true
echo "== line counts =="
for f in repo_pages/guide/framework-integrations.md repo_pages/zh/guide/framework-integrations.md; do
if [ -f "$f" ]; then
wc -l "$f"
fi
done
echo "== credential/openai mentions =="
rg -n "OPENAI_API_KEY|api_key|api-key|OPENAI|openai|model credential|credential|copy-paste|runnable|http://localhost:8321" repo_pages/guide/framework-integrations.md repo_pages/zh/guide/framework-integrations.md || true
echo "== first 230 lines =="
for f in repo_pages/guide/framework-integrations.md repo_pages/zh/guide/framework-integrations.md; do
if [ -f "$f" ]; then
echo "--- $f ---"
sed -n '1,230p' "$f" | nl -ba -v1
fi
doneRepository: afx-team/hebb-mind Length of output: 2486 🏁 Script executed: #!/bin/bash
set -euo pipefail
echo "== local git lfs config =="
git config --local --list 2>/dev/null | rg 'lfs\.' || true
echo "== current tree blobs/objects for target files if tracked =="
git ls-tree -r HEAD -- 'repo_pages/guide/framework-integrations.md' 'repo_pages/zh/guide/framework-integrations.md' || true
echo "== try read via object db if present =="
for blob in $(git ls-tree -r HEAD -- 'repo_pages/guide/framework-integrations.md' 'repo_pages/zh/guide/framework-integrations.md' | awk '{print $3}'); do
if [ -n "${blob:-}" ] && [ -f ".git/objects/${blob:0:2}/${blob:2}" ]; then
echo "--- blob ${blob:0:2}/${blob:2} ---"
git cat-file -p "$blob" | sed -n '1,260p'
else
echo "missing blob ${blob:0:2}/${blob:2}"
fi
done
echo "== try read via show if available =="
for path in repo_pages/guide/framework-integrations.md repo_pages/zh/guide/framework-integrations.md; do
if git cat-file -e "$path" 2>/dev/null; then
echo "--- $path ---"
git show "$path" | sed -n '1,260p'
else
echo "$path not present in HEAD"
fi
doneRepository: afx-team/hebb-mind Length of output: 2486 🌐 Web query:
💡 Result: In the Hebb Mind framework, the OPENAI_API_KEY is used to enable advanced "agentic" features, specifically consolidation, conflict resolution, importance scoring, and automatic tag extraction [1][2]. Hebb Mind operates with zero external services by default, meaning ingest, vector search, CRUD operations, and the Web Console do not require an API key [1][3][4]. When you choose to use a hosted LLM provider (like OpenAI) for the advanced features mentioned above, you must configure the framework using the following CLI commands [5][2]: 1. Set the LLM model (e.g., GPT-4o): hebb config set llm_model openai/gpt-4o 2. Set your API key: hebb config set llm_api_key sk-your-openai-key If you are using a local model or a proxy server, you do not need to provide an llm_api_key [5][1][2]. The framework utilizes LiteLLM to support various providers, and for non-OpenAI endpoints, you may also need to configure the llm_base_url [6][1]. You can verify that the configuration is successful and the LLM is loaded by running the command hebb doctor [2]. Citations:
Document the model credential requirement for the runnable examples. The guide claims copy-paste runnable snippets but does not mention the provider/model credential prerequisites ( 📍 Affects 2 files
🤖 Prompt for AI Agents |
||
|
|
||
| ::: tip Start the service first | ||
| Every snippet assumes the Hebb Mind background service is reachable on | ||
| `http://localhost:8321`. If you haven't installed it yet: | ||
|
|
||
| ```bash | ||
| pipx install hebb-mind | ||
| hebb setup # first time only — downloads a small embedding model | ||
| hebb service install # registers the OS background service (no admin needed) | ||
| ``` | ||
|
|
||
| Verify with `curl -X POST http://localhost:8321/api/v1/search -H 'Content-Type: application/json' -d '{"query":"ping","top_k":1}'`. | ||
| ::: | ||
|
|
||
| ::: tip Use the absolute path to `hebb-mcp` | ||
| The MCP snippets show `command="hebb-mcp"` for brevity. If your framework's MCP | ||
| client doesn't inherit your shell `PATH`, run `which hebb-mcp` and pass the | ||
| **absolute path** instead — otherwise the server silently fails to start. | ||
| ::: | ||
|
|
||
| --- | ||
|
|
||
| ## LlamaIndex | ||
|
|
||
| LlamaIndex talks to MCP servers through `llama-index-tools-mcp`. We start the | ||
| `hebb-mcp` stdio server, load its tools, and hand them to an agent that can now | ||
| write and recall memories. | ||
|
|
||
| ```bash | ||
| pip install llama-index llama-index-tools-mcp llama-index-llms-openai | ||
| ``` | ||
|
|
||
| ```python | ||
| import asyncio | ||
| from llama_index.tools.mcp import McpToolSpec, BasicMCPClient | ||
|
|
||
| async def main(): | ||
| # 1. Connect to the hebb-mcp stdio server (use `which hebb-mcp` for the absolute path) | ||
| client = BasicMCPClient(command_or_url="hebb-mcp") | ||
| tools = await McpToolSpec(client).to_tool_list_async() # -> [write_memory, search_memory, ...] | ||
| search = next(t for t in tools if t.metadata.name == "search_memory") | ||
|
|
||
| # 2. Write a memory, then recall it through the loaded tool | ||
| write = next(t for t in tools if t.metadata.name == "write_memory") | ||
| print(await write.acall(content="User prefers dark mode and compact layout", | ||
| tags=["preference", "ui"], importance=7.5)) | ||
| print(await search.acall(query="UI preferences", top_k=5)) | ||
|
|
||
| asyncio.run(main()) | ||
|
Comment on lines
+41
to
+65
There was a problem hiding this comment. 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win 🧩 Analysis chain🏁 Script executed: #!/bin/bash
set -euo pipefail
# Locate and inspect the referenced guide excerpts and nearby context.
for f in repo_pages/guide/framework-integrations.md repo_pages/zh/guide/framework-integrations.md; do
echo "===== $f ====="
sed -n '1,110p' "$f" | cat -n
echo
done
echo "===== references to FunctionAgent/FastAgent/Agent / agent context ====="
rg -n "FunctionAgent|FastAgent|Agent|agent|llamaindex_mcp|McpToolSpec|BasicMCPClient" repo_pages/guide/framework-integrations.md repo_pages/zh/guide/framework-integrations.md 2>/dev/null || trueRepository: afx-team/hebb-mind Length of output: 2486 🌐 Web query:
💡 Result: LlamaIndex provides support for Model Context Protocol (MCP) servers through the llama-index-tools-mcp package [1][2]. The key components for integrating these tools into LlamaIndex agents are BasicMCPClient and McpToolSpec [1][2]. BasicMCPClient The BasicMCPClient is responsible for connecting to and interacting with an MCP server [2][3]. It supports various transport methods, including SSE (Server-Sent Events), HTTP, and local stdio processes [4][5]. Once connected, it provides low-level access to the server's capabilities, including: - list_tools and call_tool [6][5] - list_resources and read_resource [6][5] - list_prompts and get_prompt [5] McpToolSpec McpToolSpec acts as a bridge that converts tools from an MCP client into LlamaIndex's FunctionTool objects, making them compatible with LlamaIndex agents [6][2]. Key parameters for McpToolSpec include [6]: - client: The BasicMCPClient instance (required) [6]. - allowed_tools: An optional list of specific tool names to include [6][2]. - include_resources: A boolean flag to determine whether to include resources in the tool list [6][2]. - global_partial_params and partial_params_by_tool: Dictionaries for applying partial parameters to tools [6]. Typical Workflow To use MCP tools with an agent, you generally follow these steps [1][2]: 1. Connect to the MCP server using BasicMCPClient [1][5]. 2. Create an McpToolSpec instance using the client [1][5]. 3. Convert the MCP tools into a format usable by LlamaIndex using to_tool_list (synchronous) or to_tool_list_async (asynchronous) [2][3]. 4. Pass the resulting list of tools to an agent, such as a FunctionAgent [1][2]. Example Code Snippet from llama_index.tools.mcp import BasicMCPClient, McpToolSpec from llama_index.core.agent.workflow import FunctionAgent from llama_index.llms.openai import OpenAI # Connect to the MCP server mcp_client = BasicMCPClient("http://127.0.0.1:8000/sse") # Create the tool spec mcp_tool_spec = McpToolSpec(client=mcp_client) # Convert to LlamaIndex tools tools = await mcp_tool_spec.to_tool_list_async # Use in an agent agent = FunctionAgent( llm=OpenAI(model="gpt-4o"), tools=tools,) Alternatively, for a simpler setup, you can use the helper function get_tools_from_mcp_url (or its async version aget_tools_from_mcp_url) to fetch tools directly from an MCP URL [2][3]. Citations:
Use a LlamaIndex agent for the MCP tool examples. 📍 Affects 2 files
🤖 Prompt for AI Agents |
||
| ``` | ||
|
|
||
| Prefer REST? `POST /api/v1/search` returns `{"results": [{"memory": {...}, "score": ...}]}` — | ||
| wrap it in a custom `BaseRetriever` and plug into any `RetrieverQueryEngine`. | ||
|
|
||
| --- | ||
|
|
||
| ## CrewAI | ||
|
|
||
| CrewAI loads MCP tools via `crewai-tools`' `MCPServerAdapter`. We spin up the | ||
| `hebb-mcp` stdio server, expose its tools, and assign them to an agent. | ||
|
|
||
| ```bash | ||
| pip install crewai crewai-tools | ||
| ``` | ||
|
|
||
| ```python | ||
| from crewai import Agent, Task, Crew | ||
| from crewai.tools import MCPServerAdapter | ||
|
|
||
| # 1. Start the hebb-mcp stdio server and load its tools | ||
| with MCPServerAdapter({"command": "hebb-mcp"}) as tools: # -> [write_memory, search_memory, ...] | ||
|
Comment on lines
+78
to
+87
There was a problem hiding this comment. 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win 🧩 Analysis chain🏁 Script executed: #!/bin/bash
set -euo pipefail
echo "== candidate files =="
git ls-files | rg '^repo_pages/(guide/|zh/guide/)framework-integrations\.md$' || true
echo "== current snippets =="
for f in repo_pages/guide/framework-integrations.md repo_pages/zh/guide/framework-integrations.md; do
if [ -f "$f" ]; then
echo "--- $f ---"
nl -ba "$f" | sed -n '60,105p'
fi
done
echo "== nearby package mentions =="
rg -n "crewai-tools|crewai_tools|crewai\.tools|MCPServerAdapter|StdioServerParameters|package:.*crewai|crewai/mcp|hebb-mcp" repo_pages -S || trueRepository: afx-team/hebb-mind Length of output: 2486 🌐 Web query:
💡 Result: In CrewAI, the Citations:
🌐 Web query:
💡 Result: The MCPServerAdapter is a class provided by the crewai-tools library designed to manage the lifecycle of Model Context Protocol (MCP) servers and integrate their tools into CrewAI agents [1][2]. Key documentation and usage details include: Lifecycle Management The recommended way to use MCPServerAdapter is as a Python context manager (using the with statement), which automatically handles starting and stopping the connection [2][3]. Example: with MCPServerAdapter(server_params) as tools: # tools is available here... Manual Management: For complex scenarios, you can manually manage the connection using the start and stop methods [2][3]. It is critical to call stop within a try...finally block to ensure that connections are closed and resources are properly released [3][4][5]. Configuration and Transports MCPServerAdapter supports several transport mechanisms [2]: - Stdio: For local MCP servers [3]. - Server-Sent Events (SSE): For remote servers [2][5]. - Streamable HTTPS: For remote servers, allowing for flexible or potentially bi-directional communication [2][6][7]. Optional Configuration: You can specify a connect_timeout parameter (default is 30 seconds) to customize how long the adapter waits to establish a connection [2]. Advanced Features - Multiple Servers: You can connect to multiple MCP servers simultaneously by passing a list of server parameter dictionaries to the adapter, which then aggregates the tools from all sources [8][9]. - Tool Filtering: You can filter the available tools either by passing a list of specific tool names to the constructor or by using dictionary-style indexing on the adapter [1][2]. Citations:
🌐 Web query:
💡 Result: The MCPServerAdapter class in crewAI-tools, defined in crewai_tools/adapters/mcp_adapter.py, acts as a bridge between CrewAI and external MCP (Model Context Protocol) servers [1][2]. Its init method is designed to initialize the connection to these servers by accepting specific configuration parameters [1]. The constructor is defined as follows: def init( self, serverparams: StdioServerParameters | dict[str, Any],):... The serverparams argument accepts either an instance of StdioServerParameters (from the mcp library) for STDIO-based servers or a dictionary (e.g., {"url": "http://localhost:8000/sse"}) for SSE-based servers [1][3][4]. Key implementation details of the init method include: 1. Dependency Check: It verifies if the mcp package is available; if not, it prompts the user to install it using uv [1]. 2. Initialization: It stores the provided server parameters, initializes an underlying MCP adapter with the specified configuration, and automatically calls self.start to establish the connection and discover available tools [1]. 3. Cleanup Handling: The adapter is designed to be used either as a context manager (using the with statement) or manually, in which case it is recommended to wrap usage in a try...finally block to ensure that self.stop is explicitly called to terminate the server process and release resources [1][3][5]. The StdioServerParameters class itself is used to define the command, arguments, and environment variables required to launch a local MCP server process [3]. Citations:
🌐 Web query:
💡 Result: To use Model Context Protocol (MCP) servers with CrewAI, including those utilizing Stdio (Standard Input/Output) transport, you must install the necessary extra dependencies. Installation To enable MCP support in crewai-tools, run the following command in your terminal [1][2][3]: pip install crewai-tools[mcp] Alternatively, if you are using uv, you can run: uv add crewai-tools --extra mcp Additionally, it is recommended to install the mcp library itself for basic integration [4][5]: uv add mcp Usage Overview There are two primary ways to integrate MCP servers into your CrewAI workflow: 1. DSL Integration (Recommended for most use cases) You can define MCP servers directly within your Agent configuration using the mcps field. CrewAI handles the connection lifecycle automatically [6]. from crewai import Agent from crewai.mcp import MCPServerStdio # Example using DSL agent = Agent( role="Research Analyst", mcps=[ MCPServerStdio( command="python", args=["path/to/server.py"], env={"API_KEY": "your_key"}) ]) 2. MCPServerAdapter (Advanced control) For scenarios requiring manual connection management, use the MCPServerAdapter class. It is highly recommended to use a context manager (with statement) to ensure the server process is properly started and stopped [7][8][6]. from mcp import StdioServerParameters from crewai_tools import MCPServerAdapter stdio_params = StdioServerParameters( command="uvx", args=["--quiet", "server-name@0.1.0"], env={"VAR": "value"}) with MCPServerAdapter(server_params=stdio_params) as mcp_server: tools = mcp_server.tools # Use tools in your agent... If you manage the connection manually without a context manager, you must call mcp_server_adapter.stop to release resources [7][8][9]. Citations:
Correct the CrewAI MCP setup in both guides.
📍 Affects 2 files
🤖 Prompt for AI Agents |
||
| recall = next(t for t in tools if t.name == "search_memory") | ||
|
|
||
| # 2. Give an agent the recall tool and run a one-step task | ||
| agent = Agent(role="Memory Assistant", goal="Recall stored user preferences", | ||
| backstory="A helpful agent backed by Hebb Mind long-term memory.", | ||
| tools=[recall], llm="gpt-4o-mini") | ||
| crew = Crew(agents=[agent], tasks=[Task(description="What UI does the user prefer?", | ||
| expected_output="A short sentence.", agent=agent)]) | ||
| print(crew.kickoff()) | ||
| ``` | ||
|
|
||
| Prefer REST? Hit `POST /api/v1/memories` / `POST /api/v1/search` with `requests` | ||
| inside a `crewai.tools.BaseTool` subclass. | ||
|
|
||
| --- | ||
|
|
||
| ## AutoGen | ||
|
|
||
| AutoGen **0.4+** (the `autogen-agentchat` / `autogen-ext[mcp]` packages) loads | ||
| MCP tools with `mcp_server_tools`. We connect to `hebb-mcp` over stdio and give | ||
| the tools to a `ToolUseAssistant`. | ||
|
Comment on lines
+106
to
+108
There was a problem hiding this comment. 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win 🧩 Analysis chain🏁 Script executed: #!/bin/bash
set -euo pipefail
echo "== candidate files =="
git ls-files 'repo_pages/**/guide/framework-integrations.md' 'repo_pages/**/guide/framework-integrations.md' | sed 's#^\./##'
echo "== English target lines =="
cat -n repo_pages/guide/framework-integrations.md | sed -n '80,130p'
echo "== Chinese target lines =="
cat -n repo_pages/zh/guide/framework-integrations.md | sed -n '75,115p'
echo "== ToolUseAssistant and AssistantAgent mentions =="
rg -n "ToolUseAssistant|AssistantAgent|mcp_server_tools" repo_pages || true
echo "== repository examples/tests snippets for AutoGen MCP if present =="
git ls-files | rg -i "autogen|AutoGen|agentchat|mcp" | head -100 || trueRepository: afx-team/hebb-mind Length of output: 2486 🌐 Web query:
💡 Result: In AutoGen, the integration of Model Context Protocol (MCP) servers is facilitated through the autogen-ext[mcp] extension package [1][2]. This extension allows AutoGen agents to utilize tools hosted on MCP servers seamlessly [3][1]. Key components and usage patterns include: mcp_server_tools This is a factory function used to connect to an MCP server and retrieve a list of available tool adapters [1]. It supports various server connection types, including StdioServerParams (for command-line based servers), SseServerParams, and StreamableHttpServerParams (for network-based servers) [3][1]. Once retrieved, these tool adapters can be passed directly into an AssistantAgent's tools parameter [3][4][1]. Usage with AssistantAgent To enable an assistant to use MCP tools, you instantiate an AssistantAgent and provide the list generated by mcp_server_tools to the tools argument [3][4]. For example: from autogen_ext.tools.mcp import StdioServerParams, mcp_server_tools from autogen_agentchat.agents import AssistantAgent server_params = StdioServerParams(command="uvx", args=["mcp-server-fetch"]) tools = await mcp_server_tools(server_params) agent = AssistantAgent(name="fetcher", model_client=model_client, tools=tools) McpWorkbench Alternatively, for more complex scenarios or when managing multiple MCP servers, the McpWorkbench class can be used [5][6]. It acts as a manager for MCP sessions and can be passed to an AssistantAgent via the workbench argument, allowing the agent to interact with multiple MCP servers as a unified workbench [5][6]. Important Considerations - Installation: You must install the required extension using pip install -U "autogen-ext[mcp]" [1]. - Security: Always exercise caution and only connect to trusted MCP servers, as they may execute commands in your local environment or have access to sensitive information [1][6]. - Session Management: For scenarios where state must be preserved across multiple tool calls (e.g., browser sessions), you can create and share an MCP client session across tool adapters [4]. Citations:
🌐 Web query:
💡 Result: In the AutoGen framework, specifically within its core agent architecture, ToolUseAgent is a specialized agent designed to handle tool-based task execution [1][2]. Key aspects of the ToolUseAgent and tool usage in AutoGen include: Functionality The ToolUseAgent is responsible for coordinating the interaction between an LLM and defined tools [1]. When it receives a task, it utilizes its configured model client to generate a list of function calls based on the available tools [1][2]. It then executes these tools and, depending on the configuration, may generate a reflection on the execution results before returning a final response to the user [1][2]. Evolution in AutoGen The implementation of tool use has evolved significantly across AutoGen versions: - In earlier versions (e.g., AutoGen v0.2), tool use often required registering tools across multiple agents (e.g., one agent to call the tool and another to execute it) or using a UserProxyAgent to perform execution [3][4]. - In more recent versions (e.g., AutoGen v0.4+ and AgentChat), the process has been simplified [5]. The AssistantAgent has been enhanced to automatically call and execute tools, reducing the need for separate executor agents [6][5]. Configuration and Control - Tool Schema: Tools are defined as schemas that the model uses to understand what actions it can perform [1][7]. The AssistantAgent can automatically convert Python functions into tools, generating the necessary schema from function signatures and docstrings [6]. - Reflection: Developers can configure agents to reflect on tool outputs by setting parameters like reflect_on_tool_use=True, which instructs the model to summarize or process tool results rather than just returning the raw output [6][5]. - Intervention: Because the ToolUseAgent (or AssistantAgent) controls the execution flow, developers can implement intervention handlers to intercept tool calls—for example, to prompt a human user for approval before a tool is actually executed [7]. In summary, while ToolUseAgent serves as a foundational component for structured tool-based interaction in the core framework [1][2], modern high-level usage often leverages the AssistantAgent's built-in capabilities to streamline the execution of tools [6][5]. Citations:
🌐 Web query:
💡 Result: In AutoGen, the Citations:
Use
📍 Affects 2 files
🤖 Prompt for AI Agents |
||
|
|
||
| ```bash | ||
| pip install "autogen-agentchat==0.4.*" "autogen-ext[openai,mcp]" | ||
| ``` | ||
|
|
||
| ```python | ||
| import asyncio | ||
| from autogen_agentchat.agents import AssistantAgent | ||
| from autogen_ext.models.openai import OpenAIChatCompletionClient | ||
| from autogen_ext.tools.mcp import StdioServerParams, mcp_server_tools | ||
|
|
||
| async def main(): | ||
| # 1. Discover the hebb-mcp tools over stdio | ||
| params = StdioServerParams(command="hebb-mcp", args=[], read_transport="stdio", write_transport="stdio") | ||
| tools = await mcp_server_tools(params) # -> [write_memory, search_memory, ...] | ||
|
Comment on lines
+110
to
+123
There was a problem hiding this comment. 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win 🧩 Analysis chain🏁 Script executed: #!/bin/bash
set -euo pipefail
echo "Files:"
fd -a 'framework-integrations\.md$' . | sed 's#^\./##'
echo
echo "English lines 95-130:"
sed -n '95,130p' repo_pages/guide/framework-integrations.md | cat -n
echo
echo "Chinese lines 95-130:"
sed -n '95,130p' repo_pages/zh/guide/framework-integrations.md | cat -nRepository: afx-team/hebb-mind Length of output: 2486 🌐 Web query:
💡 Result: In AutoGen 0.4.x, the components Citations:
🏁 Script executed: #!/bin/bash
set -euo pipefail
git fetch --depth=1 origin main 2>/dev/null || true
git checkout -b temp_checkout main 2>/dev/null || true
echo "Files:"
fd -a 'framework-integrations\.md$' . | sed 's#^\./##'
echo
echo "English lines 95-130:"
sed -n '95,130p' repo_pages/guide/framework-integrations.md | cat -n
echo
echo "Chinese lines 95-130:"
sed -n '95,130p' repo_pages/zh/guide/framework-integrations.md | cat -n
echo
echo "AutoGen packages in docs/pipeline/requirements:"
rg -n 'autogen(-agentchat|\.agentchat)?(==|>=|~=|==0\.4|0\.4\.)|autogen-ext|mcp_server_tools|StdioServerParams|read_transport|write_transport' repo_pages . --glob '!eval/**' --glob '!node_modules/**' 2>/dev/nullRepository: afx-team/hebb-mind Length of output: 2486 🌐 Web query:
💡 Result:
If you meant a transport-related setting, the closest match in the docs is Citations: 🌐 Web query:
💡 Result: In So if you’re looking for JSON transport, it’s not configured via Citations:
🌐 Web query:
💡 Result: In the AutoGen 0.4.x ecosystem, specifically within the autogen-ext package, StdioServerParams is a configuration class used to connect AutoGen agents to Model Context Protocol (MCP) servers operating over standard I/O (STDIO) [1][2][3]. Key details regarding your query include: 1. StdioServerParams: This class inherits from the MCP library's StdioServerParameters [1][4]. It allows you to define how an MCP server is executed, including the command to run, arguments (args), environment variables (env), current working directory (cwd), and encoding settings [2][5][6]. It also includes a configurable read_timeout_seconds property (defaulting to 5) [1][2][5]. 2. Transport Mechanisms: The AutoGen MCP implementation handles the underlying communication transport automatically once you provide the StdioServerParams to a factory function, such as mcp_server_tools or when using an McpWorkbench [3][7][6]. These functions manage the creation of the StdioMcpToolAdapter, which abstracts the read and write transport logic (handling the stdin/stdout streams of the subprocess) [3][8][7]. You do not need to manually configure read_transport or write_transport; the library manages these pipes internally [8][7]. 3. Versioning (0.4.0a11): Version 0.4.0a11 is an alpha release within the 0.4.x lifecycle (which introduced a complete architecture redesign) [9]. Documentation and features for MCP integration, including StdioServerParams, are consistent with the established structure of the autogen-ext package, which provides these extended capabilities [1][3][10]. To use MCP tools in this version, ensure you have the necessary extras installed: pip install -U "autogen-ext[mcp]" You can then define your server parameters and connect them as follows: from autogen_ext.tools.mcp import StdioServerParams, mcp_server_tools server_params = StdioServerParams( command="npx", args=[" Citations:
🌐 Web query:
💡 Result: In AutoGen (autogen-ext), StdioServerParams is a configuration class used to connect to a Model Context Protocol (MCP) server over STDIO [1][2]. It is defined in the autogen_ext.tools.mcp module [2]. Based on the official AutoGen documentation and source code, StdioServerParams inherits from the mcp.StdioServerParameters class [1]. It allows you to specify the command and arguments necessary to launch the MCP server process [2][3]. Regarding your query about "read_transport" and "write_transport": these specific attributes are not primary parameters of the StdioServerParams configuration class in the AutoGen SDK [2]. The AutoGen implementation of MCP handles the STDIO transport (communication via standard input and output streams) internally when you provide the command and arguments [4][5]. The primary attributes for StdioServerParams include [2]: - command: The command to execute to start the MCP server [2]. - args: A list of arguments to pass to the command [2]. - env: Optional environment variables for the server process [2]. - cwd: Optional current working directory for the process [2]. - read_timeout_seconds: A configurable timeout for read operations (defaults to 5 seconds) [1][2]. - encoding and encoding_error_handler: Configuration for character encoding [2]. If you are interacting with MCP servers in AutoGen, you typically pass these parameters to an McpWorkbench or use them with helper functions like mcp_server_tools [5][3][6]. The underlying transport mechanics—including how data is read from and written to the process—are abstracted away by the MCP client implementation (McpSessionActor) and the underlying mcp-python library [4][7]. Citations:
Use the 0.4.x MCP parameter API in both AutoGen guides.
📍 Affects 2 files
🤖 Prompt for AI Agents |
||
|
|
||
| # 2. Attach them to an agent and run a recall task | ||
| agent = AssistantAgent("memory", model_client=OpenAIChatCompletionClient(model="gpt-4o-mini"), | ||
| tools=tools, reflect_on_tool_use=True) | ||
| print(await agent.run(task="Search Hebb Mind for the user's UI preferences.")) | ||
|
|
||
| asyncio.run(main()) | ||
| ``` | ||
|
|
||
| ::: warning Pin the AutoGen version | ||
| AutoGen 0.2 (legacy) and 0.4+ have incompatible APIs. The snippet above targets | ||
| **0.4+**; on 0.2 use `autogen.ConversableAgent` with a custom `register_function` | ||
| that calls the REST API instead. | ||
| ::: | ||
|
|
||
| Prefer REST? `POST /api/v1/search` works directly — wrap it in an AutoGen tool | ||
| function (`async def search_hebb(query: str) -> str`). | ||
|
|
||
| --- | ||
|
|
||
| ## LangGraph | ||
|
|
||
| LangGraph loads MCP tools through `langchain-mcp-adapters`. We start `hebb-mcp` | ||
| over stdio, load the tools, and bind them into a ReAct-style graph node. | ||
|
|
||
| ```bash | ||
| pip install langgraph langchain-mcp-adapters langchain-openai | ||
| ``` | ||
|
|
||
| ```python | ||
| import asyncio | ||
| from langchain_mcp_adapters.client import MultiServerMCPClient | ||
|
|
||
| async def main(): | ||
| # 1. Load hebb-mcp tools from the stdio server | ||
| client = MultiServerMCPClient({"hebb": {"command": "hebb-mcp", "transport": "stdio"}}) | ||
| tools = await client.get_tools() # -> [write_memory, search_memory, ...] | ||
|
|
||
| # 2. Bind them to a chat model and do a write + recall round-trip | ||
| from langchain_openai import ChatOpenAI | ||
| llm = ChatOpenAI(model="gpt-4o-mini").bind_tools(tools) | ||
| write = next(t for t in tools if t.name == "write_memory") | ||
| print(await write.ainvoke({"content": "User prefers dark mode", "tags": ["ui"], "importance": 7.5})) | ||
| print(await llm.ainvoke("What UI does the user prefer? Use your Hebb Mind tool.")) | ||
|
Comment on lines
+162
to
+167
There was a problem hiding this comment. 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win 🧩 Analysis chain🏁 Script executed: #!/bin/bash
set -euo pipefail
echo "== candidate files =="
fd -a 'framework-integrations\.md$' . | sed 's#^\./##'
echo
echo "== relevant sections =="
for f in repo_pages/guide/framework-integrations.md repo_pages/zh/guide/framework-integrations.md; do
if [ -f "$f" ]; then
echo "--- $f ---"
nl -ba "$f" | sed -n '120,185p'
fi
done
echo
echo "== imports/tool definitions/usages in repo_pages/guide/framework-integrations.md =="
rg -n "langchain|ToolNode|bind_tools|search_memory|write_memory|create_function_tool_agent|create_react_agent|Graph|conditional|astart|agent_executor|LangGraph|mcp" repo_pages/guide/framework-integrations.md repo_pages/zh/guide/framework-integrations.md || trueRepository: afx-team/hebb-mind Length of output: 2486 🌐 Web query:
💡 Result: In LangGraph, creating an agent that uses tools involves binding tools to the LLM, executing those tools with a ToolNode, and using conditional routing to loop between the agent and the tool execution [1][2]. The fundamental workflow is: 1. Bind Tools: Use model.bind_tools(tools) to inform the LLM about available tools [2][3][4]. 2. Create Nodes: Define an agent node (to invoke the LLM) and a ToolNode (a prebuilt node that automatically executes requested tool calls) [1][5][4]. 3. Configure Conditional Routing: Use the prebuilt tools_condition function to check if the last message contains tool calls [6][7]. This function routes to "tools" if calls are present or "end" if they are not [6][7]. Here is a concise implementation example: from langgraph.graph import StateGraph, START, END from langgraph.prebuilt import ToolNode, tools_condition from langchain_openai import ChatOpenAI # 1. Bind tools to the model model = ChatOpenAI(model="gpt-4o").bind_tools(tools) # 2. Define the agent node def call_model(state): response = model.invoke(state["messages"]) return {"messages": [response]} # 3. Build the graph graph = StateGraph(State) graph.add_node("agent", call_model) graph.add_node("tools", ToolNode(tools)) # 4. Define the routing logic graph.add_edge(START, "agent") graph.add_conditional_edges("agent", tools_condition) graph.add_edge("tools", "agent") # Loop back to agent after tool execution app = graph.compile The tools_condition helper simplifies routing by returning "tools" if the last message has tool_calls, or END if it does not, which is the standard pattern for ReAct-style agent loops [6][1][7]. If custom logic is required, you can replace tools_condition with a custom function that inspects state["messages"][-1].tool_calls [8][4]. Citations:
Add an execution loop that invokes the MCP tools after 📍 Affects 2 files
🤖 Prompt for AI Agents |
||
|
|
||
| asyncio.run(main()) | ||
| ``` | ||
|
|
||
| ::: tip Don't extend the WIP skeleton | ||
| `examples/05_langchain_adapter.py` is a `NotImplementedError` skeleton for a | ||
| native `BaseRetriever` / `BaseChatMessageHistory`. This page is the low-cost | ||
| "paste a snippet" bridge — a native adapter is a separate follow-up. | ||
| ::: | ||
|
|
||
| --- | ||
|
|
||
| ## Which surface should I pick? | ||
|
|
||
| | Framework | Lowest-friction path | Why | | ||
| |-----------|---------------------|-----| | ||
| | LlamaIndex | MCP (`MCPClient`) | First-class `MCPClient` + tool → agent flow | | ||
| | CrewAI | MCP (`MCPServerAdapter`) | `tools=[...]` on `Agent` is idiomatic | | ||
| | AutoGen 0.4+ | MCP (`mcp_server_tools`) | `StdioServerParams` is the supported loader | | ||
| | LangGraph | MCP (`langchain-mcp-adapters`) | `get_tools()` binds straight into graph nodes | | ||
|
|
||
| Reach for the **REST API** only when a framework has no MCP adapter, or when you | ||
| need the full response shape (`results` + graph-expanded `related`) that the MCP | ||
| tool collapses into a text summary. | ||
|
|
||
| ## How it works | ||
|
|
||
| ``` | ||
| LlamaIndex / CrewAI / AutoGen / LangGraph | ||
| │ (stdio) | ||
| v | ||
| hebb-mcp (MCP server) ──or── httpx/requests ──> REST API | ||
| │ (HTTP) │ (port 8321) | ||
| v v | ||
| hebb service (REST API on 8321, OS background service) | ||
| │ | ||
| Storage / Embedder / Searcher / Tag graph | ||
| ``` | ||
|
Comment on lines
+193
to
+205
There was a problem hiding this comment. 📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick win Replace both ASCII architecture diagrams with Mermaid.
As per coding guidelines: 📍 Affects 2 files
🤖 Prompt for AI AgentsSource: Coding guidelines |
||
|
|
||
| The MCP server is a thin wrapper translating tool calls into HTTP requests to | ||
| the running Hebb Mind service — so both paths hit the same storage, embedding, | ||
| and hybrid-search engine. | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Make the starting-point entry clickable.
This new entry is plain text inside a code block, so readers cannot follow it from the “Pick your starting point” section. Add a Markdown link outside the code block or include the destination directly in the entry.
🤖 Prompt for AI Agents