adapted docs

Author: cryxnet

README.md

@@ -138,6 +138,73 @@ asyncio.run(main())
 
 ---
 
+## 🤝 Cross-Agent Communication
+
+DeepMCPAgent v0.5 introduces **Cross-Agent Communication** — agents that can _talk to each other_ without extra servers, message queues, or orchestration layers.
+
+You can now attach one agent as a **peer** inside another, turning it into a callable tool.  
+Each peer appears automatically as `ask_agent_<name>` or can be reached via `broadcast_to_agents` for parallel reasoning across multiple agents.
+
+This means your agents can **delegate**, **collaborate**, and **critique** each other — all through the same MCP tool interface.  
+It’s lightweight, model-agnostic, and fully transparent: every peer call is traced like any other tool invocation.
+
+---
+
+### 💻 Example
+
+```python
+import asyncio
+from deepmcpagent import HTTPServerSpec, build_deep_agent
+from deepmcpagent.cross_agent import CrossAgent
+
+async def main():
+    # 1️⃣ Build a "research" peer agent
+    research_graph, _ = await build_deep_agent(
+        servers={"web": HTTPServerSpec(url="http://127.0.0.1:8000/mcp")},
+        model="openai:gpt-4o-mini",
+        instructions="You are a focused research assistant that finds and summarizes sources.",
+    )
+
+    # 2️⃣ Build the main agent and attach the peer as a tool
+    main_graph, _ = await build_deep_agent(
+        servers={"math": HTTPServerSpec(url="http://127.0.0.1:9000/mcp")},
+        model="openai:gpt-4.1",
+        instructions="You are a lead analyst. Use peers when you need research or summarization.",
+        cross_agents={
+            "researcher": CrossAgent(agent=research_graph, description="A web research peer.")
+        },
+        trace_tools=True,  # see all tool calls + peer responses in console
+    )
+
+    # 3️⃣ Ask a question — the main agent can now call the researcher
+    result = await main_graph.ainvoke({
+        "messages": [{"role": "user", "content": "Find recent research on AI ethics and summarize it."}]
+    })
+
+    print(result)
+
+asyncio.run(main())
+```
+
+🧩 **Result:**
+Your main agent automatically calls `ask_agent_researcher(...)` when it decides delegation makes sense, and the peer agent returns its best final answer — all transparently handled by the MCP layer.
+
+---
+
+### 💡 Use Cases
+
+- Researcher → Writer → Editor pipelines
+- Safety or reviewer peers that audit outputs
+- Retrieval or reasoning specialists
+- Multi-model ensembles combining small and large LLMs
+
+No new infrastructure. No complex orchestration.
+Just **agents helping agents**, powered entirely by MCP over HTTP/SSE.
+
+> 🧠 One framework, many minds — **DeepMCPAgent** turns individual LLMs into a cooperative system.
+
+---
+
 ## 🖥️ CLI (no Python required)
 
 ```bash
@@ -160,25 +227,6 @@ deepmcpagent run \
 
 ---
 
-## 🧩 Architecture (at a glance)
-
-```
-┌────────────────┐        list_tools / call_tool        ┌─────────────────────────┐
-│ LangChain/LLM  │  ──────────────────────────────────▶ │ FastMCP Client (HTTP/SSE)│
-│  (your model)  │                                      └───────────┬──────────────┘
-└──────┬─────────┘  tools (LC BaseTool)                               │
-       │                                                              │
-       ▼                                                              ▼
-  LangGraph Agent                                    One or many MCP servers (remote APIs)
-  (or DeepAgents)                                    e.g., math, github, search, ...
-```
-
-- `HTTPServerSpec(...)` → **FastMCP client** (single client, multiple servers)
-- **Tool discovery** → JSON-Schema → Pydantic → LangChain `BaseTool`
-- **Agent loop** → DeepAgents (if installed) or LangGraph ReAct fallback
-
----
-
 ## Full Architecture & Agent Flow
 
 ### 1) High-level Architecture (modules & data flow)
@@ -381,56 +429,6 @@ classDiagram
 
 ---
 
-### 5) Deployment / Integration View (clusters & boundaries)
-
-```mermaid
-flowchart TD
-    subgraph App["Your App / Service"]
-      UI["CLI / API / Notebook"]
-      Code["deepmcpagent (Python pkg)\n- config.py\n- clients.py\n- tools.py\n- agent.py\n- prompt.py"]
-      UI --> Code
-    end
-
-    subgraph Cloud["LLM Provider(s)"]
-      P1["OpenAI / Anthropic / Groq / Ollama..."]
-    end
-
-    subgraph Net["Network"]
-      direction LR
-      FMCP["FastMCP Client\n(HTTP/SSE)"]
-      FMCP ---|mcpServers| Code
-    end
-
-    subgraph Servers["MCP Servers"]
-      direction LR
-      A["Service A (HTTP)\n/path: /mcp"]
-      B["Service B (SSE)\n/path: /mcp"]
-      C["Service C (HTTP)\n/path: /mcp"]
-    end
-
-    Code -->|init_chat_model or model instance| P1
-    Code --> FMCP
-    FMCP --> A
-    FMCP --> B
-    FMCP --> C
-```
-
----
-
-### 6) Error Handling & Observability (tool errors & retries)
-
-```mermaid
-flowchart TD
-    Start([Tool Call]) --> Try{"client.call_tool(name,args)"}
-    Try -- ok --> Parse["Extract data/text/content/result"]
-    Parse --> Return[Return ToolMessage to Agent]
-    Try -- raises --> Err["Tool/Transport Error"]
-    Err --> Wrap["ToolMessage(status=error, content=trace)"]
-    Wrap --> Agent["Agent observes error\nand may retry / alternate tool"]
-```
-
----
-
 > These diagrams reflect the current implementation:
 >
 > - **Model is required** (string provider-id or LangChain model instance).
@@ -515,3 +513,7 @@ Apache-2.0 — see [`LICENSE`](/LICENSE).
 - The [**MCP** community](https://modelcontextprotocol.io/) for a clean protocol.
 - [**LangChain**](https://www.langchain.com/) and [**LangGraph**](https://www.langchain.com/langgraph) for powerful agent runtimes.
 - [**FastMCP**](https://gofastmcp.com/getting-started/welcome) for solid client & server implementations.
+
+```
+
+```

docs/changelog.md

@@ -1,4 +1,103 @@
 # Changelog
 
+## 0.5.0 — 2025-10-18
+
+### Added
+
+- Cross-Agent Communication (in-process) with `cross_agent.py`.
+- `CrossAgent`, `make_cross_agent_tools`, `ask_agent_<name>`, and `broadcast_to_agents`.
+- `build_deep_agent(..., cross_agents=...)` to attach peers as tools.
+- Example `examples/use_cross_agent.py`.
+- Cross-Agent documentation section.
+
+### Changed
+
+- Pydantic v2 config via `model_config = ConfigDict(extra="forbid")`.
+
+### Fixed
+
+- Clearer trace output for cross-agent tool calls.
+- Better errors for unknown peers in `broadcast_to_agents`.
+- Implemented sync `_run` on tools to satisfy `BaseTool`.
+
+---
+
+## 0.4.1 — 2025-10-17
+
+### Added
+
+- No new features.
+
+### Changed
+
+- Updated runtime compatibility for environments without `deepagents` installed (graceful fallback to ReAct agent).
+- Minor code cleanup and improved defensive checks in the agent builder.
+
+### Fixed
+
+- Fixed `TypeError` when falling back to `create_react_agent()` with `langgraph>=0.6`.
+- Agent builder now dynamically detects supported parameters and omits deprecated ones for smooth operation across LangGraph versions.
+- Improved `_after()` trace hook to skip `None` values when `trace_tools=True`, correctly displaying tool results.
+
+---
+
+## 0.4.0
+
+### Added
+
+- CLI now supports pretty console output, `--trace/--no-trace`, and `--raw` modes.
+- HTTP server specs fully supported with block string syntax (`--http "name=... url=..."`).
+- Tool tracing hooks (`on_before`, `on_after`, `on_error`) integrated into the agent layer.
+- Richer agent streaming output: shows invoked tools, arguments, and results.
+- Added `__version__` export via package metadata.
+- Basic PyTests
+
+### Changed
+
+- Updated runtime dependencies:
+  - `langgraph` and `langgraph-prebuilt` pinned to `>=0.6,<0.7`.
+  - `langchain` bumped to `>=0.3.27`.
+  - `fastmcp` bumped to `>=2.12.2`.
+- CLI and agent examples polished for consistency and usability.
+- Development extras modernized (latest `ruff`, `mypy`, `pytest`, etc.).
+
+### Fixed
+
+- Multiple Ruff issues (imports, `Optional` → `X | None`, try/except cleanups).
+- Validation errors in CLI argument parsing.
+- Tool discovery now handles `None` or empty results gracefully.
+- Safer error handling in `_FastMCPTool` when tool callbacks raise.
+- CI workflow stabilized for PyPI publishing with setuptools-scm dynamic versioning.
+
+---
+
 ## 0.3.0
+
+### Added
+
+- Improved JSON Schema → Pydantic mapping:
+  - Carries through defaults and descriptions via `Field`.
+  - Generates per-tool arg models (`Args_<tool>`).
+  - Sanitizes model names for Pydantic compatibility.
+- CLI improvements:
+  - Added `--version` flag.
+  - Simplified option parsing.
+  - Updated documentation.
+- PyPI Trusted Publishing workflow (publish on tag).
+- CI improvements: Ruff formatting, mypy fixes, skip deep extra on Python 3.10.
+
+### Fixed
+
+- Type errors in CLI, agent, tools, and clients.
+- CLI annotation options adjusted to satisfy Ruff rules.
+
+### Changed
+
+- Project license clarified to Apache-2.0.
+- Project metadata aligned with license notice.
+
+---
+
+## 0.1.0
+
 - Initial FastMCP client edition.