Agent Mesh
Go a2aa2a-protocolagent-meshagentic-aiinferencemcpmeshmesh-networknetwork-securitynetworking-aip2p-network
docs: update docs for HTTP SSE and add agent integration guide
google-labs-jules[bot]26a6586826fa
diff --git a/README.md b/README.mdindex d20adf2e..e533aed8 100644--- a/README.md+++ b/README.md@@ -55,14 +55,14 @@ Or pass a token directly:## Local MCP Server-Each `sam-node` exposes a Model Context Protocol (MCP) server over a Unix domain socket to allow local processes to discover the capabilities of the local agent and get information from the mesh.+Each `sam-node` exposes a Model Context Protocol (MCP) server over HTTP Server-Sent Events (SSE) to allow local processes to discover the capabilities of the local agent and get information from the mesh.-By default, the socket listens at `<datadir>/mcp.sock`. You can change this with the `--mcp-socket` flag.+By default, the server listens at `127.0.0.1:8080`. You can change this with the `--bind-addr` flag.To query the mesh info via the MCP server, you can use the `mcp-client` tool provided in the repository:```bash-./bin/mcp-client -socket /path/to/mcp.sock+./bin/mcp-client -url http://127.0.0.1:8080/mcp/events```## Testingdiff --git a/docs/README.md b/docs/README.mdindex be4b96e3..f2324ba8 100644--- a/docs/README.md+++ b/docs/README.md@@ -14,7 +14,7 @@ The documentation here is intentionally small and aligned with what is implement3. Persist identity in local node store4. Run long-lived hub and node processes5. Run local and containerized BATS tests-6. Expose local tools and mesh info via MCP server on a Unix socket+6. Expose local tools and mesh info via MCP server over HTTP SSE7. Automated peer discovery via DHT and GossipSub events## Start Herediff --git a/docs/_sidebar.md b/docs/_sidebar.mdindex 857d0fb2..e4fcd036 100644--- a/docs/_sidebar.md+++ b/docs/_sidebar.md@@ -1,5 +1,6 @@- [Overview](#/README.md)- [Quick Start](#/quickstart.md)+- [Agent Integration](#/agent_integration.md)- [CLI Reference](#/cli/reference.md)- [Testing](#/testing.md)- [License](https://github.com/aojea/sam/blob/main/LICENSE)diff --git a/docs/agent_integration.md b/docs/agent_integration.mdnew file mode 100644index 00000000..b3ffab5a--- /dev/null+++ b/docs/agent_integration.md@@ -0,0 +1,78 @@+# Agent Integration Guide++SAM is designed to be the networking layer for autonomous AI agents. The easiest way for your agent to interact with the mesh is through the **Model Context Protocol (MCP)** exposed locally by your node.++Every `sam-node` runs a local MCP server that allows agents to:+- Discover tools available on the mesh.+- Connect to remote peers securely.+- Query mesh information (e.g. `get_mesh_info`).+- Call tools remotely (via `call_remote_tool`).++## Connecting via MCP++The `sam-node` exposes the MCP server over HTTP Server-Sent Events (SSE). By default, it listens at `127.0.0.1:8080`.++The repository provides a Python SDK (`sam-mcp-python`) which implements the MCP client.++### Prerequisites++You need the `sam_mcp` package installed. From the repo root, run:++```bash+pip install ./sam-mcp-python+```++### Python SDK Demo++The following snippet demonstrates how to connect to the local node's MCP server, list the available tools, and call the `get_mesh_info` tool.++```python+import asyncio+import os+import sys+from sam_mcp.client import SamClient++async def main():+ # Connect to the local SAM node's MCP SSE endpoint+ # By default, sam-node listens at 127.0.0.1:8080+ url = os.environ.get("SAM_MCP_URL", "http://127.0.0.1:8080/mcp/events")+ print(f"Connecting to SAM Node at {url}")++ try:+ async with SamClient(server_url=url) as client:+ # Discover available tools provided by the SAM node+ tools = await client.get_tools()+ print(f"Discovered {len(tools)} tools:")+ for tool in tools:+ print(f" - {tool.name}: {tool.description}")++ # Call the get_mesh_info tool to get information about the mesh+ print("\nCalling get_mesh_info tool...")+ result = await client.call_tool("get_mesh_info", {})+ print("Result:")+ print(result)++ except Exception as e:+ print(f"Error connecting to SAM Node: {e}")+ sys.exit(1)++if __name__ == "__main__":+ asyncio.run(main())+```++*(You can find this snippet at `docs/snippets/agent_demo.py`)*++### Example Output++When you run the demo while a `sam-node` is running locally, you'll see output similar to this:++```+Connecting to SAM Node at http://127.0.0.1:8080/mcp/events+Discovered tools:+ - get_mesh_info: Retrieve information about the mesh...+ - call_remote_tool: Call an MCP tool on a remote agent...++Calling get_mesh_info tool...+Result:+{'mesh_name': 'e2e-mesh', 'connected_peers': ...}+```diff --git a/docs/snippets/agent_demo.py b/docs/snippets/agent_demo.pynew file mode 100644index 00000000..62c508f4--- /dev/null+++ b/docs/snippets/agent_demo.py@@ -0,0 +1,31 @@+import asyncio+import os+import sys+from sam_mcp.client import SamClient++async def main():+ # Connect to the local SAM node's MCP SSE endpoint+ # By default, sam-node listens at 127.0.0.1:8080+ url = os.environ.get("SAM_MCP_URL", "http://127.0.0.1:8080/mcp/events")+ print(f"Connecting to SAM Node at {url}")++ try:+ async with SamClient(server_url=url) as client:+ # Discover available tools provided by the SAM node+ tools = await client.get_tools()+ print(f"Discovered {len(tools)} tools:")+ for tool in tools:+ print(f" - {tool.name}: {tool.description}")++ # Call the get_mesh_info tool to get information about the mesh+ print("\nCalling get_mesh_info tool...")+ result = await client.call_tool("get_mesh_info", {})+ print("Result:")+ print(result)++ except Exception as e:+ print(f"Error connecting to SAM Node: {e}")+ sys.exit(1)++if __name__ == "__main__":+ asyncio.run(main())diff --git a/tests/e2e/docs_snippets.bats b/tests/e2e/docs_snippets.batsnew file mode 100644index 00000000..9936857f--- /dev/null+++ b/tests/e2e/docs_snippets.bats@@ -0,0 +1,61 @@+#!/usr/bin/env bats++load "lib/container_mesh.bash"++setup() {+ if ! mesh_require_docker; then+ skip "docker not available or daemon not running"+ fi++ if [[ ! -x "./bin/sam-node" || ! -x "./bin/sam-hub" ]]; then+ skip "missing binaries; run: make build"+ fi++ mesh_setup_env+}++teardown() {+ if [[ "${BATS_TEST_COMPLETED:-0}" -ne 1 ]]; then+ echo "Node 1 logs on failure (filtered):"+ docker logs "${MESH_PREFIX}-node-1" 2>&1 | grep -i -E 'mcp|request|error|fatal|panic' || true+ fi+ mesh_cleanup_env+}++@test "Docs Snippets: agent_demo.py runs successfully" {+ run mesh_start_mock_oidc+ [[ "$status" -eq 0 ]]++ run mesh_start_hub+ [[ "$status" -eq 0 ]]++ run mesh_start_node 1 "--discovery-interval 100ms --log-level debug"+ [[ "$status" -eq 0 ]]++ local node1_name="${MESH_PREFIX}-node-1"+ mesh_wait_for_log "${node1_name}" "SAM Node Online" 20+ mesh_wait_for_mcp_ready 1 20++ # Run the agent_demo.py snippet inside a container+ run docker run --rm \+ --network "${MESH_NETWORK}" \+ -v "$(pwd)/sam-mcp-python:/sam-mcp-python" \+ -v "$(pwd)/docs/snippets:/snippets" \+ -e PYTHONPATH=/sam-mcp-python/src \+ -e SAM_MCP_URL="http://sam-node-1:8080/mcp/events" \+ python:3.12 \+ bash -c 'pip install mcp httpx && python3 /snippets/agent_demo.py'++ echo "agent_demo.py output: $output"++ if [[ "$status" -ne 0 ]]; then+ echo "Node 1 logs:"+ docker logs "${node1_name}"+ fi++ [[ "$status" -eq 0 ]]+ [[ "$output" == *"Connecting to SAM Node at"* ]]+ [[ "$output" == *"Discovered"* ]]+ [[ "$output" == *"Calling get_mesh_info tool..."* ]]+ [[ "$output" == *"Result:"* ]]+}