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

rem/api/mcp_router/tools.py

@@ -20,6 +20,7 @@ Available Tools:
 - get_schema: Get detailed schema for a table (columns, types, indexes)
 """
 
+import json
 from functools import wraps
 from typing import Any, Callable, Literal, cast
 
@@ -128,201 +129,228 @@ def mcp_tool_error_handler(func: Callable) -> Callable:
 
 @mcp_tool_error_handler
 async def search_rem(
-    query_type: Literal["lookup", "fuzzy", "search", "sql", "traverse"],
-    # LOOKUP parameters
-    entity_key: str | None = None,
-    # FUZZY parameters
-    query_text: str | None = None,
-    threshold: float = 0.7,
-    # SEARCH parameters
-    table: str | None = None,
+    query: str,
     limit: int = 20,
-    # SQL parameters
-    sql_query: str | None = None,
-    # TRAVERSE parameters
-    initial_query: str | None = None,
-    edge_types: list[str] | None = None,
-    depth: int = 1,
-    # Optional context override (defaults to authenticated user)
-    user_id: str | None = None,
 ) -> dict[str, Any]:
     """
-    Execute REM queries for entity lookup, semantic search, and graph traversal.
-
-    REM supports multiple query types for different retrieval patterns:
+    Execute a REM query using the REM query dialect.
 
-    **LOOKUP** - O(1) entity resolution by natural language key:
-    - Fast exact match across all tables
-    - Uses indexed label_vector for instant retrieval
-    - Example: LOOKUP "Sarah Chen" returns all entities named "Sarah Chen"
+    **REM Query Syntax:**
 
-    **FUZZY** - Fuzzy text matching with similarity threshold:
-    - Finds partial matches and typos
-    - Example: FUZZY "sara" threshold=0.7 finds "Sarah Chen", "Sara Martinez"
+    LOOKUP <entity_key>
+        Find entity by exact name/key. Searches across all tables.
+        Example: LOOKUP phq-9-procedure
+        Example: LOOKUP sertraline
 
-    **SEARCH** - Semantic vector search (table-specific):
-    - Finds conceptually similar entities
-    - Example: SEARCH "database migration" table=resources returns related documents
+    SEARCH <text> IN <table>
+        Semantic vector search within a specific table.
+        Tables: 'ontologies' (clinical knowledge, procedures, drugs, DSM criteria)
+                'resources' (documents, files, user content)
+        Example: SEARCH depression IN ontologies
+        Example: SEARCH Module F IN ontologies
 
-    **SQL** - Direct SQL queries for structured data:
-    - Full PostgreSQL query power (scoped to table)
-    - Example: SQL "role = 'engineer'" (WHERE clause only)
+    FUZZY <text>
+        Fuzzy text matching for partial matches and typos.
+        Example: FUZZY setraline
 
-    **TRAVERSE** - Graph traversal following relationships:
-    - Explores entity neighborhood via graph edges
-    - Supports depth control and edge type filtering
-    - Example: TRAVERSE "Sarah Chen" edge_types=["manages", "reports_to"] depth=2
+    TRAVERSE <start_entity>
+        Graph traversal from a starting entity.
+        Example: TRAVERSE sarah-chen
 
     Args:
-        query_type: Type of query (lookup, fuzzy, search, sql, traverse)
-        entity_key: Entity key for LOOKUP (e.g., "Sarah Chen")
-        query_text: Search text for FUZZY or SEARCH
-        threshold: Similarity threshold for FUZZY (0.0-1.0)
-        table: Target table for SEARCH (resources, moments, users, etc.)
-        limit: Max results for SEARCH
-        sql_query: SQL WHERE clause for SQL type (e.g. "id = '123'")
-        initial_query: Starting entity for TRAVERSE
-        edge_types: Edge types to follow for TRAVERSE (e.g., ["manages", "reports_to"])
-        depth: Traversal depth for TRAVERSE (0=plan only, 1-5=actual traversal)
-        user_id: Optional user identifier (defaults to authenticated user or "default")
+        query: REM query string (e.g., "LOOKUP phq-9-procedure", "SEARCH depression IN ontologies")
+        limit: Maximum results to return (default: 20)
 
     Returns:
-        Dict with query results, metadata, and execution info
+        Dict with query results and metadata. If no results found, includes
+        'suggestions' with alternative search strategies.
 
     Examples:
-        # Lookup entity (uses authenticated user context)
-        search_rem(
-            query_type="lookup",
-            entity_key="Sarah Chen"
-        )
-
-        # Semantic search
-        search_rem(
-            query_type="search",
-            query_text="database migration",
-            table="resources",
-            limit=10
-        )
-
-        # SQL query (WHERE clause only)
-        search_rem(
-            query_type="sql",
-            table="resources",
-            sql_query="category = 'document'"
-        )
-
-        # Graph traversal
-        search_rem(
-            query_type="traverse",
-            initial_query="Sarah Chen",
-            edge_types=["manages", "reports_to"],
-            depth=2
-        )
+        search_rem("LOOKUP phq-9-procedure")
+        search_rem("SEARCH depression IN ontologies")
+        search_rem("SEARCH anxiety treatment IN ontologies", limit=10)
+        search_rem("FUZZY setraline")
     """
     # Get RemService instance (lazy initialization)
     rem_service = await get_rem_service()
 
-    # Get user_id from context if not provided
-    # TODO: Extract from authenticated session context when auth is enabled
-    user_id = AgentContext.get_user_id_or_default(user_id, source="search_rem")
+    # Get user_id from context
+    user_id = AgentContext.get_user_id_or_default(None, source="search_rem")
+
+    # Parse the REM query string
+    if not query or not query.strip():
+        return {
+            "status": "error",
+            "error": "Empty query. Use REM syntax: LOOKUP <key>, SEARCH <text> IN <table>, FUZZY <text>, or TRAVERSE <entity>",
+        }
+
+    query = query.strip()
+    parts = query.split(None, 1)  # Split on first whitespace
+
+    if len(parts) < 2:
+        return {
+            "status": "error",
+            "error": f"Invalid query format: '{query}'. Expected: LOOKUP <key>, SEARCH <text> IN <table>, FUZZY <text>, or TRAVERSE <entity>",
+        }
 
-    # Normalize query_type to lowercase for case-insensitive REM dialect
-    query_type = cast(Literal["lookup", "fuzzy", "search", "sql", "traverse"], query_type.lower())
+    query_type = parts[0].upper()
+    remainder = parts[1].strip()
 
     # Build RemQuery based on query_type
-    if query_type == "lookup":
-        if not entity_key:
-            return {"status": "error", "error": "entity_key required for LOOKUP"}
+    if query_type == "LOOKUP":
+        if not remainder:
+            return {
+                "status": "error",
+                "error": "LOOKUP requires an entity key. Example: LOOKUP phq-9-procedure",
+            }
 
-        query = RemQuery(
+        rem_query = RemQuery(
             query_type=QueryType.LOOKUP,
             parameters=LookupParameters(
-                key=entity_key,
+                key=remainder,
                 user_id=user_id,
             ),
             user_id=user_id,
         )
+        table = None  # LOOKUP searches all tables
+
+    elif query_type == "SEARCH":
+        # Parse "text IN table" format
+        if " IN " in remainder.upper():
+            # Find the last " IN " to handle cases like "SEARCH pain IN back IN ontologies"
+            in_pos = remainder.upper().rfind(" IN ")
+            search_text = remainder[:in_pos].strip()
+            table = remainder[in_pos + 4:].strip().lower()
+        else:
+            return {
+                "status": "error",
+                "error": f"SEARCH requires table: SEARCH <text> IN <table>. "
+                "Use 'ontologies' for clinical knowledge or 'resources' for documents. "
+                f"Example: SEARCH {remainder} IN ontologies",
+            }
 
-    elif query_type == "fuzzy":
-        if not query_text:
-            return {"status": "error", "error": "query_text required for FUZZY"}
-
-        query = RemQuery(
-            query_type=QueryType.FUZZY,
-            parameters=FuzzyParameters(
-                query_text=query_text,
-                threshold=threshold,
-                limit=limit, # Limit was missing in original logic but likely intended
-            ),
-            user_id=user_id,
-        )
-
-    elif query_type == "search":
-        if not query_text:
-            return {"status": "error", "error": "query_text required for SEARCH"}
-        if not table:
-            return {"status": "error", "error": "table required for SEARCH"}
+        if not search_text:
+            return {
+                "status": "error",
+                "error": "SEARCH requires search text. Example: SEARCH depression IN ontologies",
+            }
 
-        query = RemQuery(
+        rem_query = RemQuery(
             query_type=QueryType.SEARCH,
             parameters=SearchParameters(
-                query_text=query_text,
+                query_text=search_text,
                 table_name=table,
                 limit=limit,
             ),
             user_id=user_id,
         )
 
-    elif query_type == "sql":
-        if not sql_query:
-            return {"status": "error", "error": "sql_query required for SQL"}
-        
-        # SQLParameters requires table_name. If not provided, we cannot execute.
-        # Assuming sql_query is just the WHERE clause based on RemService implementation,
-        # OR if table is provided we use it.
-        if not table:
-             return {"status": "error", "error": "table required for SQL queries (parameter: table)"}
-
-        query = RemQuery(
-            query_type=QueryType.SQL,
-            parameters=SQLParameters(
-                table_name=table,
-                where_clause=sql_query,
+    elif query_type == "FUZZY":
+        if not remainder:
+            return {
+                "status": "error",
+                "error": "FUZZY requires search text. Example: FUZZY setraline",
+            }
+
+        rem_query = RemQuery(
+            query_type=QueryType.FUZZY,
+            parameters=FuzzyParameters(
+                query_text=remainder,
+                threshold=0.3,  # pg_trgm similarity - 0.3 is reasonable for typo correction
                 limit=limit,
             ),
             user_id=user_id,
         )
+        table = None
 
-    elif query_type == "traverse":
-        if not initial_query:
+    elif query_type == "TRAVERSE":
+        if not remainder:
             return {
                 "status": "error",
-                "error": "initial_query required for TRAVERSE",
+                "error": "TRAVERSE requires a starting entity. Example: TRAVERSE sarah-chen",
             }
 
-        query = RemQuery(
+        rem_query = RemQuery(
             query_type=QueryType.TRAVERSE,
             parameters=TraverseParameters(
-                initial_query=initial_query,
-                edge_types=edge_types or [],
-                max_depth=depth,
+                initial_query=remainder,
+                edge_types=[],
+                max_depth=1,
             ),
             user_id=user_id,
         )
+        table = None
 
     else:
-        return {"status": "error", "error": f"Unknown query_type: {query_type}"}
+        return {
+            "status": "error",
+            "error": f"Unknown query type: '{query_type}'. Valid types: LOOKUP, SEARCH, FUZZY, TRAVERSE. "
+            "Examples: LOOKUP phq-9-procedure, SEARCH depression IN ontologies",
+        }
 
     # Execute query (errors handled by decorator)
     logger.info(f"Executing REM query: {query_type} for user {user_id}")
-    result = await rem_service.execute_query(query)
+    result = await rem_service.execute_query(rem_query)
 
     logger.info(f"Query completed successfully: {query_type}")
-    return {
+
+    # Provide helpful guidance when no results found
+    response: dict[str, Any] = {
         "query_type": query_type,
         "results": result,
     }
 
+    # Check if results are empty - handle both list and dict result formats
+    is_empty = False
+    if not result:
+        is_empty = True
+    elif isinstance(result, list) and len(result) == 0:
+        is_empty = True
+    elif isinstance(result, dict):
+        # RemService returns dict with 'results' key containing actual matches
+        inner_results = result.get("results", [])
+        count = result.get("count", len(inner_results) if isinstance(inner_results, list) else 0)
+        is_empty = count == 0 or (isinstance(inner_results, list) and len(inner_results) == 0)
+
+    if is_empty:
+        # Build helpful suggestions based on query type
+        suggestions = []
+
+        if query_type in ("LOOKUP", "FUZZY"):
+            suggestions.append(
+                "LOOKUP/FUZZY searches across ALL tables. If you expected results, "
+                "verify the entity name is spelled correctly."
+            )
+
+        if query_type == "SEARCH":
+            if table == "resources":
+                suggestions.append(
+                    "No results in 'resources' table. Try: SEARCH <text> IN ontologies - "
+                    "clinical procedures, drug info, and diagnostic criteria are stored there."
+                )
+            elif table == "ontologies":
+                suggestions.append(
+                    "No results in 'ontologies' table. Try: SEARCH <text> IN resources - "
+                    "for user-uploaded documents and general content."
+                )
+            else:
+                suggestions.append(
+                    "Try: SEARCH <text> IN ontologies (clinical knowledge, procedures, drugs) "
+                    "or SEARCH <text> IN resources (documents, files)."
+                )
+
+        # Always suggest both tables if no specific table guidance given
+        if not suggestions:
+            suggestions.append(
+                "No results found. Try: SEARCH <text> IN ontologies (clinical procedures, drugs) "
+                "or SEARCH <text> IN resources (documents, files)."
+            )
+
+        response["suggestions"] = suggestions
+        response["hint"] = "0 results returned. See 'suggestions' for alternative search strategies."
+
+    return response
+
 
 @mcp_tool_error_handler
 async def ask_rem_agent(
@@ -373,20 +401,45 @@ async def ask_rem_agent(
             query="Show me Sarah's reporting chain and their recent projects"
         )
     """
-    # Get user_id from context if not provided
-    # TODO: Extract from authenticated session context when auth is enabled
-    user_id = AgentContext.get_user_id_or_default(user_id, source="ask_rem_agent")
-
     from ...agentic import create_agent
+    from ...agentic.context import get_current_context
     from ...utils.schema_loader import load_agent_schema
 
-    # Create agent context
-    # Note: tenant_id defaults to "default" if user_id is None
-    context = AgentContext(
-        user_id=user_id,
-        tenant_id=user_id or "default",  # Use default tenant for anonymous users
-        default_model=settings.llm.default_model,
-    )
+    # Get parent context for multi-agent support
+    # This enables context propagation from parent agent to child agent
+    parent_context = get_current_context()
+
+    # Build child context: inherit from parent if available, otherwise use defaults
+    if parent_context is not None:
+        # Inherit user_id, tenant_id, session_id, is_eval from parent
+        # Allow explicit user_id override if provided
+        effective_user_id = user_id or parent_context.user_id
+        context = parent_context.child_context(agent_schema_uri=agent_schema)
+        if user_id is not None:
+            # Override user_id if explicitly provided
+            context = AgentContext(
+                user_id=user_id,
+                tenant_id=parent_context.tenant_id,
+                session_id=parent_context.session_id,
+                default_model=parent_context.default_model,
+                agent_schema_uri=agent_schema,
+                is_eval=parent_context.is_eval,
+            )
+        logger.debug(
+            f"ask_rem_agent inheriting context from parent: "
+            f"user_id={context.user_id}, session_id={context.session_id}"
+        )
+    else:
+        # No parent context - create fresh context (backwards compatible)
+        effective_user_id = AgentContext.get_user_id_or_default(
+            user_id, source="ask_rem_agent"
+        )
+        context = AgentContext(
+            user_id=effective_user_id,
+            tenant_id=effective_user_id or "default",
+            default_model=settings.llm.default_model,
+            agent_schema_uri=agent_schema,
+        )
 
     # Load agent schema
     try:
@@ -426,15 +479,18 @@ async def ingest_into_rem(
     category: str | None = None,
     tags: list[str] | None = None,
     is_local_server: bool = False,
-    user_id: str | None = None,
     resource_type: str | None = None,
 ) -> dict[str, Any]:
     """
-    Ingest file into REM, creating searchable resources and embeddings.
+    Ingest file into REM, creating searchable PUBLIC resources and embeddings.
+
+    **IMPORTANT: All ingested data is PUBLIC by default.** This is correct for
+    shared knowledge bases (ontologies, procedures, reference data). Private
+    user-scoped data requires different handling via the CLI with --make-private.
 
     This tool provides the complete file ingestion pipeline:
     1. **Read**: File from local/S3/HTTP
-    2. **Store**: To user-scoped internal storage
+    2. **Store**: To internal storage (public namespace)
     3. **Parse**: Extract content, metadata, tables, images
     4. **Chunk**: Semantic chunking for embeddings
     5. **Embed**: Create Resource chunks with vector embeddings
@@ -453,7 +509,6 @@ async def ingest_into_rem(
         category: Optional category (document, code, audio, etc.)
         tags: Optional tags for file
         is_local_server: True if running as local/stdio MCP server
-        user_id: Optional user identifier (defaults to authenticated user or "default")
         resource_type: Optional resource type for storing chunks (case-insensitive).
             Supports flexible naming:
             - "resource", "resources", "Resource" → Resource (default)
@@ -472,10 +527,10 @@ async def ingest_into_rem(
         - message: Human-readable status message
 
     Examples:
-        # Ingest local file (local server only, uses authenticated user context)
+        # Ingest local file (local server only)
         ingest_into_rem(
-            file_uri="/Users/me/contract.pdf",
-            category="legal",
+            file_uri="/Users/me/procedure.pdf",
+            category="medical",
             is_local_server=True
         )
 
@@ -499,15 +554,14 @@ async def ingest_into_rem(
     """
     from ...services.content import ContentService
 
-    # Get user_id from context if not provided
-    # TODO: Extract from authenticated session context when auth is enabled
-    user_id = AgentContext.get_user_id_or_default(user_id, source="ingest_into_rem")
+    # Data is PUBLIC by default (user_id=None)
+    # Private user-scoped data requires CLI with --make-private flag
 
     # Delegate to ContentService for centralized ingestion (errors handled by decorator)
     content_service = ContentService()
     result = await content_service.ingest_file(
         file_uri=file_uri,
-        user_id=user_id,
+        user_id=None,  # PUBLIC - all ingested data is shared/public
         category=category,
         tags=tags,
         is_local_server=is_local_server,
@@ -540,15 +594,18 @@ async def read_resource(uri: str) -> dict[str, Any]:
     **Available Resources:**
 
     Agent Schemas:
-    • rem://schemas - List all agent schemas
-    • rem://schema/{name} - Get specific schema definition
-    • rem://schema/{name}/{version} - Get specific version
+    • rem://agents - List all available agent schemas
+    • rem://agents/{agent_name} - Get specific agent schema
+
+    Documentation:
+    • rem://schema/entities - Entity schemas (Resource, Message, User, File, Moment)
+    • rem://schema/query-types - REM query type documentation
 
     System Status:
     • rem://status - System health and statistics
 
     Args:
-        uri: Resource URI (e.g., "rem://schemas", "rem://schema/ask_rem")
+        uri: Resource URI (e.g., "rem://agents", "rem://agents/ask_rem")
 
     Returns:
         Dict with:
@@ -557,14 +614,11 @@ async def read_resource(uri: str) -> dict[str, Any]:
         - data: Resource data (format depends on resource type)
 
     Examples:
-        # List all schemas
-        read_resource(uri="rem://schemas")
-
-        # Get specific schema
-        read_resource(uri="rem://schema/ask_rem")
+        # List all agents
+        read_resource(uri="rem://agents")
 
-        # Get schema version
-        read_resource(uri="rem://schema/ask_rem/v1.0.0")
+        # Get specific agent
+        read_resource(uri="rem://agents/ask_rem")
 
         # Check system status
         read_resource(uri="rem://status")
@@ -617,6 +671,8 @@ async def register_metadata(
     recommended_action: str | None = None,
     # Generic extension - any additional key-value pairs
     extra: dict[str, Any] | None = None,
+    # Agent schema (auto-populated from context if not provided)
+    agent_schema: str | None = None,
 ) -> dict[str, Any]:
     """
     Register response metadata to be emitted as an SSE MetadataEvent.
@@ -657,6 +713,8 @@ async def register_metadata(
         extra: Dict of arbitrary additional metadata. Use this for any
             domain-specific fields not covered by the standard parameters.
             Example: {"topics_detected": ["anxiety", "sleep"], "session_count": 5}
+        agent_schema: Optional agent schema name. If not provided, automatically
+            populated from the current agent context (for multi-agent tracing).
 
     Returns:
         Dict with:
@@ -700,10 +758,17 @@ async def register_metadata(
             }
         )
     """
+    # Auto-populate agent_schema from context if not provided
+    if agent_schema is None:
+        from ...agentic.context import get_current_context
+        current_context = get_current_context()
+        if current_context and current_context.agent_schema_uri:
+            agent_schema = current_context.agent_schema_uri
+
     logger.debug(
         f"Registering metadata: confidence={confidence}, "
         f"risk_level={risk_level}, refs={len(references or [])}, "
-        f"sources={len(sources or [])}"
+        f"sources={len(sources or [])}, agent_schema={agent_schema}"
     )
 
     result = {
@@ -713,6 +778,7 @@ async def register_metadata(
         "references": references,
         "sources": sources,
         "flags": flags,
+        "agent_schema": agent_schema,  # Include agent schema for tracing
     }
 
     # Add session name if provided
@@ -1134,6 +1200,382 @@ async def save_agent(
     return result
 
 
+# =============================================================================
+# Multi-Agent Tools
+# =============================================================================
+
+
+@mcp_tool_error_handler
+async def ask_agent(
+    agent_name: str,
+    input_text: str,
+    input_data: dict[str, Any] | None = None,
+    user_id: str | None = None,
+    timeout_seconds: int = 300,
+) -> dict[str, Any]:
+    """
+    Invoke another agent by name and return its response.
+
+    This tool enables multi-agent orchestration by allowing one agent to call
+    another. The child agent inherits the parent's context (user_id, session_id,
+    tenant_id, is_eval) for proper scoping and continuity.
+
+    Use Cases:
+    - Orchestrator agents that delegate to specialized sub-agents
+    - Workflow agents that chain multiple processing steps
+    - Ensemble agents that aggregate responses from multiple specialists
+
+    Args:
+        agent_name: Name of the agent to invoke. Can be:
+            - A user-created agent (saved via save_agent)
+            - A system agent (e.g., "ask_rem", "knowledge-query")
+        input_text: The user message/query to send to the agent
+        input_data: Optional structured input data for the agent
+        user_id: Optional user override (defaults to parent's user_id)
+        timeout_seconds: Maximum execution time (default: 300s)
+
+    Returns:
+        Dict with:
+        - status: "success" or "error"
+        - output: Agent's structured output (if using output schema)
+        - text_response: Agent's text response
+        - agent_schema: Name of the invoked agent
+        - metadata: Any metadata registered by the agent (confidence, etc.)
+
+    Examples:
+        # Simple delegation
+        ask_agent(
+            agent_name="sentiment-analyzer",
+            input_text="I love this product! Best purchase ever."
+        )
+        # Returns: {"status": "success", "output": {"sentiment": "positive"}, ...}
+
+        # Orchestrator pattern
+        ask_agent(
+            agent_name="knowledge-query",
+            input_text="What are the latest Q3 results?"
+        )
+
+        # Chain with structured input
+        ask_agent(
+            agent_name="summarizer",
+            input_text="Summarize this document",
+            input_data={"document_id": "doc-123", "max_length": 500}
+        )
+    """
+    import asyncio
+    from ...agentic import create_agent
+    from ...agentic.context import get_current_context, agent_context_scope, get_event_sink, push_event
+    from ...agentic.agents.agent_manager import get_agent
+    from ...utils.schema_loader import load_agent_schema
+
+    # Get parent context for inheritance
+    parent_context = get_current_context()
+
+    # Determine effective user_id
+    if parent_context is not None:
+        effective_user_id = user_id or parent_context.user_id
+    else:
+        effective_user_id = AgentContext.get_user_id_or_default(
+            user_id, source="ask_agent"
+        )
+
+    # Build child context
+    if parent_context is not None:
+        child_context = parent_context.child_context(agent_schema_uri=agent_name)
+        if user_id is not None:
+            # Explicit user_id override
+            child_context = AgentContext(
+                user_id=user_id,
+                tenant_id=parent_context.tenant_id,
+                session_id=parent_context.session_id,
+                default_model=parent_context.default_model,
+                agent_schema_uri=agent_name,
+                is_eval=parent_context.is_eval,
+            )
+        logger.debug(
+            f"ask_agent '{agent_name}' inheriting context: "
+            f"user_id={child_context.user_id}, session_id={child_context.session_id}"
+        )
+    else:
+        child_context = AgentContext(
+            user_id=effective_user_id,
+            tenant_id=effective_user_id or "default",
+            default_model=settings.llm.default_model,
+            agent_schema_uri=agent_name,
+        )
+
+    # Try to load agent schema from:
+    # 1. Database (user-created or system agents)
+    # 2. File system (packaged agents)
+    schema = None
+
+    # Try database first
+    if effective_user_id:
+        schema = await get_agent(agent_name, user_id=effective_user_id)
+        if schema:
+            logger.debug(f"Loaded agent '{agent_name}' from database")
+
+    # Fall back to file system
+    if schema is None:
+        try:
+            schema = load_agent_schema(agent_name)
+            logger.debug(f"Loaded agent '{agent_name}' from file system")
+        except FileNotFoundError:
+            pass
+
+    if schema is None:
+        return {
+            "status": "error",
+            "error": f"Agent not found: {agent_name}",
+            "hint": "Use list_agents to see available agents, or save_agent to create one",
+        }
+
+    # Create agent runtime
+    agent_runtime = await create_agent(
+        context=child_context,
+        agent_schema_override=schema,
+    )
+
+    # Build prompt with optional input_data
+    prompt = input_text
+    if input_data:
+        prompt = f"{input_text}\n\nInput data: {json.dumps(input_data)}"
+
+    # Load session history for the sub-agent (CRITICAL for multi-turn conversations)
+    # Sub-agents need to see the full conversation context, not just the summary
+    pydantic_message_history = None
+    if child_context.session_id and settings.postgres.enabled:
+        try:
+            from ...services.session import SessionMessageStore, session_to_pydantic_messages
+            from ...agentic.schema import get_system_prompt
+
+            store = SessionMessageStore(user_id=child_context.user_id or "default")
+            raw_session_history = await store.load_session_messages(
+                session_id=child_context.session_id,
+                user_id=child_context.user_id,
+                compress_on_load=False,  # Need full data for reconstruction
+            )
+            if raw_session_history:
+                # Extract agent's system prompt from schema
+                agent_system_prompt = get_system_prompt(schema) if schema else None
+                pydantic_message_history = session_to_pydantic_messages(
+                    raw_session_history,
+                    system_prompt=agent_system_prompt,
+                )
+                logger.debug(
+                    f"ask_agent '{agent_name}': loaded {len(raw_session_history)} session messages "
+                    f"-> {len(pydantic_message_history)} pydantic-ai messages"
+                )
+
+                # Audit session history if enabled
+                from ...services.session import audit_session_history
+                audit_session_history(
+                    session_id=child_context.session_id,
+                    agent_name=agent_name,
+                    prompt=prompt,
+                    raw_session_history=raw_session_history,
+                    pydantic_messages_count=len(pydantic_message_history),
+                )
+        except Exception as e:
+            logger.warning(f"ask_agent '{agent_name}': failed to load session history: {e}")
+            # Fall back to running without history
+
+    # Run agent with timeout and context propagation
+    logger.info(f"Invoking agent '{agent_name}' with prompt: {prompt[:100]}...")
+
+    # Check if we have an event sink for streaming
+    push_event = get_event_sink()
+    use_streaming = push_event is not None
+
+    streamed_content = ""  # Track if content was streamed
+
+    try:
+        # Set child context for nested tool calls
+        with agent_context_scope(child_context):
+            if use_streaming:
+                # STREAMING MODE: Use iter() and proxy events to parent
+                logger.debug(f"ask_agent '{agent_name}': using streaming mode with event proxying")
+
+                async def run_with_streaming():
+                    from pydantic_ai.messages import (
+                        PartStartEvent, PartDeltaEvent, PartEndEvent,
+                        FunctionToolResultEvent, FunctionToolCallEvent,
+                    )
+                    from pydantic_ai.agent import Agent
+
+                    accumulated_content = []
+                    child_tool_calls = []
+
+                    # iter() returns an async context manager, not an awaitable
+                    iter_kwargs = {"message_history": pydantic_message_history} if pydantic_message_history else {}
+                    async with agent_runtime.iter(prompt, **iter_kwargs) as agent_run:
+                        async for node in agent_run:
+                            if Agent.is_model_request_node(node):
+                                async with node.stream(agent_run.ctx) as request_stream:
+                                    async for event in request_stream:
+                                        # Proxy part starts (text content only - tool calls handled in is_call_tools_node)
+                                        if isinstance(event, PartStartEvent):
+                                            from pydantic_ai.messages import ToolCallPart, TextPart
+                                            if isinstance(event.part, ToolCallPart):
+                                                # Track tool call for later (args are incomplete at PartStartEvent)
+                                                # Full args come via FunctionToolCallEvent in is_call_tools_node
+                                                child_tool_calls.append({
+                                                    "tool_name": event.part.tool_name,
+                                                    "index": event.index,
+                                                })
+                                            elif isinstance(event.part, TextPart):
+                                                # TextPart may have initial content
+                                                if event.part.content:
+                                                    accumulated_content.append(event.part.content)
+                                                    await push_event.put({
+                                                        "type": "child_content",
+                                                        "agent_name": agent_name,
+                                                        "content": event.part.content,
+                                                    })
+                                        # Proxy text content deltas to parent for real-time streaming
+                                        elif isinstance(event, PartDeltaEvent):
+                                            if hasattr(event, 'delta') and hasattr(event.delta, 'content_delta'):
+                                                content = event.delta.content_delta
+                                                if content:
+                                                    accumulated_content.append(content)
+                                                    # Push content chunk to parent for streaming
+                                                    await push_event.put({
+                                                        "type": "child_content",
+                                                        "agent_name": agent_name,
+                                                        "content": content,
+                                                    })
+
+                            elif Agent.is_call_tools_node(node):
+                                async with node.stream(agent_run.ctx) as tools_stream:
+                                    async for tool_event in tools_stream:
+                                        # FunctionToolCallEvent fires when tool call is parsed
+                                        # with complete arguments (before execution)
+                                        if isinstance(tool_event, FunctionToolCallEvent):
+                                            # Get full arguments from completed tool call
+                                            tool_args = None
+                                            if hasattr(tool_event, 'part') and hasattr(tool_event.part, 'args'):
+                                                raw_args = tool_event.part.args
+                                                if isinstance(raw_args, str):
+                                                    try:
+                                                        tool_args = json.loads(raw_args)
+                                                    except json.JSONDecodeError:
+                                                        tool_args = {"raw": raw_args}
+                                                elif isinstance(raw_args, dict):
+                                                    tool_args = raw_args
+                                            # Push tool start with full arguments
+                                            await push_event.put({
+                                                "type": "child_tool_start",
+                                                "agent_name": agent_name,
+                                                "tool_name": tool_event.part.tool_name if hasattr(tool_event, 'part') else "unknown",
+                                                "arguments": tool_args,
+                                            })
+                                        elif isinstance(tool_event, FunctionToolResultEvent):
+                                            result_content = tool_event.result.content if hasattr(tool_event.result, 'content') else tool_event.result
+                                            # Push tool result to parent
+                                            await push_event.put({
+                                                "type": "child_tool_result",
+                                                "agent_name": agent_name,
+                                                "result": result_content,
+                                            })
+
+                        # Get final result (inside context manager)
+                        return agent_run.result, "".join(accumulated_content), child_tool_calls
+
+                result, streamed_content, tool_calls = await asyncio.wait_for(
+                    run_with_streaming(),
+                    timeout=timeout_seconds
+                )
+            else:
+                # NON-STREAMING MODE: Use run() for backwards compatibility
+                if pydantic_message_history:
+                    result = await asyncio.wait_for(
+                        agent_runtime.run(prompt, message_history=pydantic_message_history),
+                        timeout=timeout_seconds
+                    )
+                else:
+                    result = await asyncio.wait_for(
+                        agent_runtime.run(prompt),
+                        timeout=timeout_seconds
+                    )
+    except asyncio.TimeoutError:
+        return {
+            "status": "error",
+            "error": f"Agent '{agent_name}' timed out after {timeout_seconds}s",
+            "agent_schema": agent_name,
+        }
+
+    # Serialize output
+    from rem.agentic.serialization import serialize_agent_result, is_pydantic_model
+    output = serialize_agent_result(result.output)
+
+    logger.info(f"Agent '{agent_name}' completed successfully")
+
+    # If child agent returned structured output (Pydantic model), emit as tool_call SSE event
+    # This allows the frontend to render structured results (forms, cards, etc.)
+    is_structured_output = is_pydantic_model(result.output)
+    structured_tool_id = f"{agent_name}_structured_output"
+    logger.debug(f"ask_agent '{agent_name}': is_structured_output={is_structured_output}, output_type={type(result.output).__name__}")
+
+    if use_streaming and is_structured_output and push_event is not None:
+        # Emit structured output as a tool_call event with the serialized result
+        # Use agent_name as tool_name so it appears as the logical tool (e.g., "finalize_intake_agent")
+        await push_event.put({
+            "type": "tool_call",
+            "tool_name": agent_name,  # Use agent name as tool name for clarity
+            "tool_id": structured_tool_id,
+            "status": "completed",
+            "arguments": {"input_text": input_text},
+            "result": output,  # Serialized Pydantic model as dict
+        })
+        logger.debug(f"ask_agent '{agent_name}': emitted structured output as tool_call SSE event")
+
+    # Save structured output as a tool message in the database
+    # This makes structured output agents look like tool calls in session history
+    if is_structured_output and child_context and child_context.session_id and settings.postgres.enabled:
+        try:
+            from ...services.session import SessionMessageStore
+            from ...utils.date_utils import utc_now, to_iso
+
+            store = SessionMessageStore(user_id=child_context.user_id or "default")
+
+            # Build tool message in the same format as regular tool calls
+            tool_message = {
+                "role": "tool",
+                "content": json.dumps(output, default=str),  # Structured output as JSON
+                "timestamp": to_iso(utc_now()),
+                "tool_call_id": structured_tool_id,
+                "tool_name": agent_name,  # Agent name as tool name
+                "tool_arguments": {"input_text": input_text},
+            }
+
+            # Store as a single message (not using store_session_messages to avoid compression)
+            await store.store_session_messages(
+                session_id=child_context.session_id,
+                messages=[tool_message],
+                user_id=child_context.user_id,
+                compress=False,  # Don't compress tool results
+            )
+            logger.debug(f"ask_agent '{agent_name}': saved structured output as tool message in session")
+        except Exception as e:
+            logger.warning(f"ask_agent '{agent_name}': failed to save structured output to database: {e}")
+
+    response = {
+        "status": "success",
+        "output": output,
+        "agent_schema": agent_name,
+        "input_text": input_text,
+        "is_structured_output": is_structured_output,  # Flag for caller to know result type
+    }
+
+    # Only include text_response if content was NOT streamed
+    # When streaming, child_content events already delivered the content
+    if not use_streaming or not streamed_content:
+        response["text_response"] = str(result.output)
+
+    return response
+
+
 # =============================================================================
 # Test/Debug Tools (for development only)
 # =============================================================================