remdb 0.3.180__py3-none-any.whl → 0.3.230__py3-none-any.whl

rem/agentic/README.md

@@ -716,11 +716,45 @@ curl -X POST http://localhost:8000/api/v1/chat/completions \
 
 See `rem/api/README.md` for full SSE event protocol documentation.
 
+## Multi-Agent Orchestration
+
+Agents can delegate work to other agents via the `ask_agent` tool. This enables orchestrator patterns where a parent agent routes to specialists.
+
+### How It Works
+
+1. **Parent agent** calls `ask_agent(agent_name, input_text)`
+2. **Child agent** executes and streams its response
+3. **Child events** bubble up to parent via an event sink (asyncio.Queue in ContextVar)
+4. **All tool calls** are saved to the database for the session
+
+### Key Components
+
+| Component | Location | Purpose |
+|-----------|----------|---------|
+| `ask_agent` tool | `mcp_router/tools.py` | Loads child agent, runs with streaming, pushes events to sink |
+| Event sink | `context.py` | ContextVar holding asyncio.Queue for child→parent event flow |
+| Streaming controller | `streaming.py` | Drains event sink, emits SSE events, saves to DB |
+
+### Event Types
+
+Child agents emit events that the parent streams to the client:
+
+- **`child_tool_start`**: Child is calling a tool (logged, streamed, saved to DB)
+- **`child_content`**: Child's text response (streamed as SSE content delta)
+- **`child_tool_result`**: Tool completed with result (metadata extraction)
+
+### Testing
+
+Integration tests in `tests/integration/test_ask_agent_streaming.py` verify:
+- Child content streams correctly to client
+- Tool calls are persisted to database
+- Multi-turn conversations save all messages
+
 ## Future Work
 
 - [ ] Phoenix evaluator integration
 - [ ] Agent schema registry (load schemas by URI)
 - [ ] Schema validation and versioning
-- [ ] Multi-turn conversation management
-- [ ] Agent composition (agents calling agents)
+- [x] Multi-turn conversation management
+- [x] Agent composition (agents calling agents)
 - [ ] Alternative provider implementations (if needed)

rem/agentic/context.py

@@ -22,14 +22,153 @@ Key Design Pattern:
 - Enables session tracking across API, CLI, and test execution
 - Supports header-based configuration override (model, schema URI)
 - Clean separation: context (who/what) vs agent (how)
+
+Multi-Agent Context Propagation:
+- ContextVar (_current_agent_context) threads context through nested agent calls
+- Parent context is automatically available to child agents via get_current_context()
+- Use agent_context_scope() context manager for scoped context setting
+- Child agents inherit user_id, tenant_id, session_id, is_eval from parent
 """
 
+import asyncio
+from contextlib import contextmanager
+from contextvars import ContextVar
+from typing import Any, Generator
+
 from loguru import logger
 from pydantic import BaseModel, Field
 
 from ..settings import settings
 
 
+# Thread-local context for current agent execution
+# This enables context propagation through nested agent calls (multi-agent)
+_current_agent_context: ContextVar["AgentContext | None"] = ContextVar(
+    "current_agent_context", default=None
+)
+
+# Event sink for streaming child agent events to parent
+# When set, child agents (via ask_agent) should push their events here
+# for the parent's streaming loop to proxy to the client
+_parent_event_sink: ContextVar["asyncio.Queue | None"] = ContextVar(
+    "parent_event_sink", default=None
+)
+
+
+def get_current_context() -> "AgentContext | None":
+    """
+    Get the current agent context from context var.
+
+    Used by MCP tools (like ask_agent) to inherit context from parent agent.
+    Returns None if no context is set (e.g., direct CLI invocation without context).
+
+    Example:
+        # In an MCP tool
+        parent_context = get_current_context()
+        if parent_context:
+            # Inherit user_id, session_id, etc. from parent
+            child_context = parent_context.child_context(agent_schema_uri="child-agent")
+    """
+    return _current_agent_context.get()
+
+
+def set_current_context(ctx: "AgentContext | None") -> None:
+    """
+    Set the current agent context.
+
+    Called by streaming layer before agent execution.
+    Should be cleared (set to None) after execution completes.
+    """
+    _current_agent_context.set(ctx)
+
+
+@contextmanager
+def agent_context_scope(ctx: "AgentContext") -> Generator["AgentContext", None, None]:
+    """
+    Context manager for scoped context setting.
+
+    Automatically restores previous context when exiting scope.
+    Safe for nested agent calls - each level preserves its parent's context.
+
+    Example:
+        context = AgentContext(user_id="user-123")
+        with agent_context_scope(context):
+            # Context is available via get_current_context()
+            result = await agent.run(...)
+        # Previous context (or None) is restored
+    """
+    previous = _current_agent_context.get()
+    _current_agent_context.set(ctx)
+    try:
+        yield ctx
+    finally:
+        _current_agent_context.set(previous)
+
+
+# =============================================================================
+# Event Sink for Streaming Multi-Agent Delegation
+# =============================================================================
+
+
+def get_event_sink() -> "asyncio.Queue | None":
+    """
+    Get the parent's event sink for streaming child events.
+
+    Used by ask_agent to push child agent events to the parent's stream.
+    Returns None if not in a streaming context.
+    """
+    return _parent_event_sink.get()
+
+
+def set_event_sink(sink: "asyncio.Queue | None") -> None:
+    """Set the event sink for child agents to push events to."""
+    _parent_event_sink.set(sink)
+
+
+@contextmanager
+def event_sink_scope(sink: "asyncio.Queue") -> Generator["asyncio.Queue", None, None]:
+    """
+    Context manager for scoped event sink setting.
+
+    Used by streaming layer to set up event proxying before tool execution.
+    Child agents (via ask_agent) will push their events to this sink.
+
+    Example:
+        event_queue = asyncio.Queue()
+        with event_sink_scope(event_queue):
+            # ask_agent will push child events to event_queue
+            async for event in tools_stream:
+                ...
+            # Also consume from event_queue
+    """
+    previous = _parent_event_sink.get()
+    _parent_event_sink.set(sink)
+    try:
+        yield sink
+    finally:
+        _parent_event_sink.set(previous)
+
+
+async def push_event(event: Any) -> bool:
+    """
+    Push an event to the parent's event sink (if available).
+
+    Used by ask_agent to proxy child agent events to the parent's stream.
+    Returns True if event was pushed, False if no sink available.
+
+    Args:
+        event: Any streaming event (ToolCallEvent, content chunk, etc.)
+
+    Returns:
+        True if event was pushed to sink, False otherwise
+    """
+    sink = _parent_event_sink.get()
+    if sink is not None:
+        await sink.put(event)
+        return True
+    return False
+
+
 class AgentContext(BaseModel):
     """
     Session and configuration context for agent execution.
@@ -85,6 +224,40 @@ class AgentContext(BaseModel):
 
     model_config = {"populate_by_name": True}
 
+    def child_context(
+        self,
+        agent_schema_uri: str | None = None,
+        model_override: str | None = None,
+    ) -> "AgentContext":
+        """
+        Create a child context for nested agent calls.
+
+        Inherits user_id, tenant_id, session_id, is_eval from parent.
+        Allows overriding agent_schema_uri and default_model for the child.
+
+        Args:
+            agent_schema_uri: Agent schema for the child agent (required for lineage)
+            model_override: Optional model override for child agent
+
+        Returns:
+            New AgentContext for the child agent
+
+        Example:
+            parent_context = get_current_context()
+            child_context = parent_context.child_context(
+                agent_schema_uri="sentiment-analyzer"
+            )
+            agent = await create_agent(context=child_context)
+        """
+        return AgentContext(
+            user_id=self.user_id,
+            tenant_id=self.tenant_id,
+            session_id=self.session_id,
+            default_model=model_override or self.default_model,
+            agent_schema_uri=agent_schema_uri or self.agent_schema_uri,
+            is_eval=self.is_eval,
+        )
+
     @staticmethod
     def get_user_id_or_default(
         user_id: str | None,

rem/agentic/context_builder.py

@@ -217,11 +217,21 @@ class ContextBuilder:
                 )
 
                 # Convert to ContextMessage format
+                # For tool messages, wrap content with clear markers so the agent
+                # can see previous tool results when the prompt is concatenated
                 for msg_dict in session_history:
+                    role = msg_dict["role"]
+                    content = msg_dict["content"]
+
+                    if role == "tool":
+                        # Wrap tool results with clear markers for visibility
+                        tool_name = msg_dict.get("tool_name", "unknown")
+                        content = f"[TOOL RESULT: {tool_name}]\n{content}\n[/TOOL RESULT]"
+
                     messages.append(
                         ContextMessage(
-                            role=msg_dict["role"],
-                            content=msg_dict["content"],
+                            role=role,
+                            content=content,
                         )
                     )
 

rem/agentic/mcp/tool_wrapper.py

@@ -116,7 +116,7 @@ def create_resource_tool(uri: str, usage: str = "", mcp_server: Any = None) -> T
     the artificial MCP distinction between tools and resources.
 
     Supports both:
-    - Concrete URIs: "rem://schemas" -> tool with no parameters
+    - Concrete URIs: "rem://agents" -> tool with no parameters
     - Template URIs: "patient-profile://field/{field_key}" -> tool with field_key parameter
 
     Args:
@@ -131,7 +131,7 @@ def create_resource_tool(uri: str, usage: str = "", mcp_server: Any = None) -> T
 
     Example:
         # Concrete URI -> no-param tool
-        tool = create_resource_tool("rem://schemas", "List all agent schemas")
+        tool = create_resource_tool("rem://agents", "List all agent schemas")
 
         # Template URI -> parameterized tool
         tool = create_resource_tool("patient-profile://field/{field_key}", "Get field definition", mcp_server=mcp)

rem/agentic/providers/pydantic_ai.py

@@ -732,7 +732,7 @@ async def create_agent(
     # the artificial MCP distinction between tools and resources
     #
     # Supports both concrete and template URIs:
-    # - Concrete: "rem://schemas" -> no-param tool
+    # - Concrete: "rem://agents" -> no-param tool
     # - Template: "patient-profile://field/{field_key}" -> tool with field_key param
     from ..mcp.tool_wrapper import create_resource_tool
 

rem/agentic/schema.py

@@ -79,7 +79,7 @@ class MCPResourceReference(BaseModel):
 
     Example (exact URI):
         {
-            "uri": "rem://schemas",
+            "uri": "rem://agents",
             "name": "Agent Schemas",
             "description": "List all available agent schemas"
         }
@@ -96,7 +96,7 @@ class MCPResourceReference(BaseModel):
         default=None,
         description=(
             "Exact resource URI or URI with query parameters. "
-            "Examples: 'rem://schemas', 'rem://resources?category=drug.*'"
+            "Examples: 'rem://agents', 'rem://resources?category=drug.*'"
         )
     )
 

rem/api/main.py

@@ -322,7 +322,7 @@ def create_app() -> FastAPI:
 
     app.add_middleware(
         AuthMiddleware,
-        protected_paths=["/api/v1"],
+        protected_paths=["/api/v1", "/api/admin"],
         excluded_paths=["/api/auth", "/api/dev", "/api/v1/mcp/auth", "/api/v1/slack"],
         # Allow anonymous when auth is disabled, otherwise use setting
         allow_anonymous=(not settings.auth.enabled) or settings.auth.allow_anonymous,

rem/api/mcp_router/server.py

@@ -34,6 +34,7 @@ from .resources import (
     register_status_resources,
 )
 from .tools import (
+    ask_agent,
     ask_rem_agent,
     get_schema,
     ingest_into_rem,
@@ -203,6 +204,9 @@ def create_mcp_server(is_local: bool = False) -> FastMCP:
     mcp.tool()(get_schema)
     mcp.tool()(save_agent)
 
+    # Register multi-agent tools
+    mcp.tool()(ask_agent)
+
     # Register test tool only in development environment (not staging/production)
     if settings.environment not in ("staging", "production"):
         mcp.tool()(test_error_handling)