uer-mcp 3.0.0 → 4.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uer-mcp",
-  "version": "3.0.0",
+  "version": "4.0.0",
   "description": "Universal Expert Registry - Multi-LLM MCP Server with access to 100+ LLM providers, 1000+ MCP servers, and unlimited context storage",
   "main": "index.js",
   "bin": {

package/python/src/uer/models/__init__.py

@@ -0,0 +1,12 @@
+"""Data models for UER."""
+
+from .llm import LLMCallRequest, LLMCallResponse
+from .message import ContextReference, Message, ToolCall
+
+__all__ = [
+    "LLMCallRequest",
+    "LLMCallResponse",
+    "Message",
+    "ToolCall",
+    "ContextReference",
+]

package/python/src/uer/models/message.py

@@ -0,0 +1,71 @@
+"""Message models for chat history and multi-agent communication."""
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+
+class ToolCall(BaseModel):
+    """Represents a tool call made by an assistant."""
+
+    id: str = Field(..., description="Unique identifier for the tool call")
+    type: str = Field(default="function", description="Type of tool call")
+    function: dict[str, Any] = Field(
+        ..., description="Function details including name and arguments"
+    )
+
+
+class Message(BaseModel):
+    """Represents a message in a chat conversation.
+
+    Supports system, user, assistant, and tool roles for multi-agent orchestration.
+    """
+
+    role: Literal["system", "user", "assistant", "tool"] = Field(
+        ..., description="Role of the message sender"
+    )
+    content: str | None = Field(default=None, description="Text content of the message")
+    tool_calls: list[ToolCall] | None = Field(
+        default=None, description="Tool calls made by assistant (assistant role only)"
+    )
+    tool_call_id: str | None = Field(
+        default=None, description="ID of the tool call this responds to (tool role only)"
+    )
+    name: str | None = Field(
+        default=None, description="Name of the tool or function (tool role only)"
+    )
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert message to dictionary format for LLM APIs."""
+        result: dict[str, Any] = {"role": self.role}
+
+        if self.content is not None:
+            result["content"] = self.content
+
+        if self.tool_calls is not None:
+            result["tool_calls"] = [
+                {
+                    "id": tc.id,
+                    "type": tc.type,
+                    "function": tc.function,
+                }
+                for tc in self.tool_calls
+            ]
+
+        if self.tool_call_id is not None:
+            result["tool_call_id"] = self.tool_call_id
+
+        if self.name is not None:
+            result["name"] = self.name
+
+        return result
+
+
+class ContextReference(BaseModel):
+    """Reference to stored context in S3 storage."""
+
+    uri: str = Field(..., description="S3 URI or registry URI to context")
+    description: str | None = Field(default=None, description="Optional description of the context")
+    inject_as: Literal["system", "user"] = Field(
+        default="system", description="How to inject the context into messages"
+    )

package/python/src/uer/orchestration/__init__.py

@@ -0,0 +1,13 @@
+"""Orchestration components for subagent delegation and multi-agent coordination."""
+
+from .context import ContextManager
+from .history import ChatHistoryBuilder
+from .orchestrator import BehaviorLog, DelegationResult, SubagentOrchestrator
+
+__all__ = [
+    "ChatHistoryBuilder",
+    "ContextManager",
+    "SubagentOrchestrator",
+    "DelegationResult",
+    "BehaviorLog",
+]

package/python/src/uer/orchestration/context.py

@@ -0,0 +1,327 @@
+"""Enhanced context manager with Jinja2 templates and registry data fetching."""
+
+import logging
+from datetime import datetime
+from typing import Any
+
+from jinja2 import BaseLoader, Environment, TemplateNotFound
+
+from ..storage.manager import StorageManager
+
+logger = logging.getLogger(__name__)
+
+
+class RegistryLoader(BaseLoader):
+    """Jinja2 loader that fetches templates from S3 storage."""
+
+    def __init__(self, storage: StorageManager):
+        """Initialize registry loader.
+
+        Args:
+            storage: Storage manager for fetching templates
+        """
+        self.storage = storage
+        self._cache: dict[str, tuple[str, str | None]] = {}
+
+    def get_source(self, environment: Environment, template: str):
+        """Load template from storage.
+
+        Args:
+            environment: Jinja2 environment
+            template: Template URI (e.g., 'registry://templates/prompt.md' or 's3://bucket/key')
+
+        Returns:
+            Tuple of (source, filename, uptodate_func)
+        """
+        # Check cache first
+        if template in self._cache:
+            source, etag = self._cache[template]
+            return source, template, lambda: True
+
+        try:
+            if not self.storage.is_available():
+                logger.warning(f"Storage not available, cannot load template: {template}")
+                raise TemplateNotFound(template)
+
+            # Fetch from storage
+            content, metadata = self.storage.get_sync(template)
+            source = content.decode("utf-8")
+            etag = metadata.etag if hasattr(metadata, "etag") else None
+
+            # Cache it
+            self._cache[template] = (source, etag)
+
+            logger.debug(f"Loaded template from {template} ({len(source)} chars)")
+            return source, template, lambda: True
+
+        except Exception as e:
+            logger.error(f"Failed to load template {template}: {e}")
+            raise TemplateNotFound(template) from None
+
+
+class ContextManager:
+    """Manages context assembly with Jinja2 templates and registry data fetching.
+
+    Features:
+    - Template-based context assembly
+    - Registry data expansion ({{ uri | expand }})
+    - Token optimization through caching
+    - Dynamic variable injection
+    - Nested template support
+    """
+
+    def __init__(self, storage: StorageManager | None = None):
+        """Initialize context manager.
+
+        Args:
+            storage: Storage manager for registry access
+        """
+        self.storage = storage or StorageManager()
+
+        # Initialize Jinja2 environment with registry loader
+        self.env = Environment(
+            loader=RegistryLoader(self.storage),
+            autoescape=False,  # Don't escape for LLM prompts
+            trim_blocks=True,
+            lstrip_blocks=True,
+        )
+
+        # Add custom filters
+        self.env.filters["expand"] = self._expand_filter
+        self.env.filters["fetch"] = self._fetch_filter
+        self.env.filters["truncate_tokens"] = self._truncate_tokens_filter
+        self.env.filters["summarize"] = self._summarize_filter
+
+        # Context cache for token optimization
+        self._context_cache: dict[str, tuple[str, datetime]] = {}
+        self._cache_ttl_seconds = 300  # 5 minutes
+
+        logger.info("ContextManager initialized with Jinja2 support")
+
+    def _expand_filter(self, uri: str) -> str:
+        """Jinja2 filter to expand a URI by fetching its content.
+
+        Usage: {{ 'registry://context/analysis.txt' | expand }}
+
+        Args:
+            uri: URI to expand
+
+        Returns:
+            Content from the URI
+        """
+        try:
+            # Check cache
+            if uri in self._context_cache:
+                content, cached_at = self._context_cache[uri]
+                age = (datetime.now() - cached_at).total_seconds()
+                if age < self._cache_ttl_seconds:
+                    logger.debug(f"Cache hit for {uri} (age: {age:.1f}s)")
+                    return content
+
+            if not self.storage.is_available():
+                logger.warning(f"Storage not available, cannot expand: {uri}")
+                return f"[Storage unavailable: {uri}]"
+
+            # Fetch from storage
+            content_bytes, metadata = self.storage.get_sync(uri)
+            content = content_bytes.decode("utf-8")
+
+            # Cache it
+            self._context_cache[uri] = (content, datetime.now())
+
+            logger.info(f"Expanded {uri} ({len(content)} chars)")
+            return content
+
+        except Exception as e:
+            logger.error(f"Failed to expand {uri}: {e}")
+            return f"[Error expanding {uri}: {e}]"
+
+    def _fetch_filter(self, uri: str, default: str = "") -> str:
+        """Jinja2 filter to fetch content with a default fallback.
+
+        Usage: {{ 'registry://context/optional.txt' | fetch('default value') }}
+
+        Args:
+            uri: URI to fetch
+            default: Default value if fetch fails
+
+        Returns:
+            Content or default value
+        """
+        try:
+            return self._expand_filter(uri)
+        except Exception:
+            return default
+
+    def _truncate_tokens_filter(self, text: str, max_tokens: int = 1000) -> str:
+        """Jinja2 filter to truncate text to approximate token count.
+
+        Usage: {{ long_text | truncate_tokens(500) }}
+
+        Args:
+            text: Text to truncate
+            max_tokens: Maximum token count (approximate)
+
+        Returns:
+            Truncated text
+        """
+        # Rough approximation: 4 chars per token
+        max_chars = max_tokens * 4
+        if len(text) <= max_chars:
+            return text
+
+        truncated = text[:max_chars]
+        logger.debug(
+            f"Truncated text from {len(text)} to {len(truncated)} chars (~{max_tokens} tokens)"
+        )
+        return truncated + "..."
+
+    def _summarize_filter(self, text: str, max_lines: int = 10) -> str:
+        """Jinja2 filter to summarize text by taking first N lines.
+
+        Usage: {{ long_text | summarize(5) }}
+
+        Args:
+            text: Text to summarize
+            max_lines: Maximum number of lines
+
+        Returns:
+            Summarized text
+        """
+        lines = text.split("\n")
+        if len(lines) <= max_lines:
+            return text
+
+        summary = "\n".join(lines[:max_lines])
+        logger.debug(f"Summarized text from {len(lines)} to {max_lines} lines")
+        return summary + f"\n... ({len(lines) - max_lines} more lines)"
+
+    async def render_template(
+        self, template_uri: str, variables: dict[str, Any] | None = None
+    ) -> str:
+        """Render a Jinja2 template with variables.
+
+        Args:
+            template_uri: URI to template (e.g., 'registry://templates/prompt.md')
+            variables: Variables to inject into template
+
+        Returns:
+            Rendered template content
+        """
+        variables = variables or {}
+
+        try:
+            template = self.env.get_template(template_uri)
+            rendered = template.render(**variables)
+            logger.info(f"Rendered template {template_uri} ({len(rendered)} chars)")
+            return rendered
+
+        except Exception as e:
+            logger.error(f"Failed to render template {template_uri}: {e}")
+            raise
+
+    def render_string(self, template_string: str, variables: dict[str, Any] | None = None) -> str:
+        """Render a template string with variables.
+
+        Args:
+            template_string: Template content as string
+            variables: Variables to inject into template
+
+        Returns:
+            Rendered content
+        """
+        variables = variables or {}
+
+        try:
+            template = self.env.from_string(template_string)
+            rendered = template.render(**variables)
+            logger.debug(f"Rendered string template ({len(rendered)} chars)")
+            return rendered
+
+        except Exception as e:
+            logger.error(f"Failed to render string template: {e}")
+            raise
+
+    async def assemble_context(
+        self,
+        template: str | None = None,
+        context_refs: list[str] | None = None,
+        variables: dict[str, Any] | None = None,
+        max_tokens: int | None = None,
+    ) -> str:
+        """Assemble context from template and/or URIs.
+
+        Args:
+            template: Template string or URI to render
+            context_refs: List of URIs to expand and include
+            variables: Variables for template rendering
+            max_tokens: Optional token limit for truncation
+
+        Returns:
+            Assembled context string
+        """
+        variables = variables or {}
+        parts: list[str] = []
+
+        # Add context refs as variables
+        if context_refs:
+            for i, uri in enumerate(context_refs):
+                try:
+                    content = self._expand_filter(uri)
+                    variables[f"context_{i}"] = content
+                    variables[f"context_{i}_uri"] = uri
+                except Exception as e:
+                    logger.warning(f"Failed to load context ref {uri}: {e}")
+
+        # Render template if provided
+        if template:
+            if template.startswith("registry://") or template.startswith("s3://"):
+                # Template URI
+                rendered = await self.render_template(template, variables)
+            else:
+                # Template string
+                rendered = self.render_string(template, variables)
+            parts.append(rendered)
+
+        # Add raw context refs if no template
+        elif context_refs:
+            for uri in context_refs:
+                try:
+                    content = self._expand_filter(uri)
+                    parts.append(f"# Context from {uri}\n\n{content}")
+                except Exception as e:
+                    logger.warning(f"Failed to expand {uri}: {e}")
+
+        # Combine parts
+        assembled = "\n\n---\n\n".join(parts)
+
+        # Truncate if needed
+        if max_tokens:
+            assembled = self._truncate_tokens_filter(assembled, max_tokens)
+
+        logger.info(f"Assembled context ({len(assembled)} chars, ~{len(assembled) // 4} tokens)")
+        return assembled
+
+    def clear_cache(self) -> None:
+        """Clear the context cache."""
+        self._context_cache.clear()
+        logger.info("Cleared context cache")
+
+    def get_cache_stats(self) -> dict[str, Any]:
+        """Get cache statistics.
+
+        Returns:
+            Dictionary with cache stats
+        """
+        now = datetime.now()
+        valid_entries = sum(
+            1
+            for _, (_, cached_at) in self._context_cache.items()
+            if (now - cached_at).total_seconds() < self._cache_ttl_seconds
+        )
+
+        return {
+            "total_entries": len(self._context_cache),
+            "valid_entries": valid_entries,
+            "ttl_seconds": self._cache_ttl_seconds,
+        }

package/python/src/uer/orchestration/history.py

@@ -0,0 +1,170 @@
+"""Chat history builder for multi-agent conversations."""
+
+import logging
+from typing import Any
+
+from ..models.message import ContextReference, Message, ToolCall
+
+logger = logging.getLogger(__name__)
+
+
+class ChatHistoryBuilder:
+    """Builds chat history for LLM conversations with support for context injection.
+
+    Supports system, user, assistant, and tool messages for multi-agent orchestration.
+    Can inject context from S3 storage URIs.
+    """
+
+    def __init__(self):
+        """Initialize empty chat history."""
+        self.messages: list[Message] = []
+        self.context_refs: list[ContextReference] = []
+
+    def add_system(self, content: str) -> "ChatHistoryBuilder":
+        """Add a system message.
+
+        Args:
+            content: System message content (instructions, context, etc.)
+
+        Returns:
+            Self for method chaining
+        """
+        self.messages.append(Message(role="system", content=content))
+        logger.debug(f"Added system message ({len(content)} chars)")
+        return self
+
+    def add_user(self, content: str) -> "ChatHistoryBuilder":
+        """Add a user message.
+
+        Args:
+            content: User message content
+
+        Returns:
+            Self for method chaining
+        """
+        self.messages.append(Message(role="user", content=content))
+        logger.debug(f"Added user message ({len(content)} chars)")
+        return self
+
+    def add_assistant(
+        self, content: str | None = None, tool_calls: list[dict[str, Any]] | None = None
+    ) -> "ChatHistoryBuilder":
+        """Add an assistant message.
+
+        Args:
+            content: Assistant response content (optional if tool_calls provided)
+            tool_calls: List of tool calls made by assistant
+
+        Returns:
+            Self for method chaining
+        """
+        parsed_tool_calls = None
+        if tool_calls:
+            parsed_tool_calls = [
+                ToolCall(
+                    id=tc.get("id", ""),
+                    type=tc.get("type", "function"),
+                    function=tc.get("function", {}),
+                )
+                for tc in tool_calls
+            ]
+
+        self.messages.append(
+            Message(role="assistant", content=content, tool_calls=parsed_tool_calls)
+        )
+        logger.debug(
+            f"Added assistant message (content: {len(content or '')} chars, "
+            f"tool_calls: {len(tool_calls or [])})"
+        )
+        return self
+
+    def add_tool_result(
+        self, tool_call_id: str, result: str, name: str | None = None
+    ) -> "ChatHistoryBuilder":
+        """Add a tool result message.
+
+        Args:
+            tool_call_id: ID of the tool call this responds to
+            result: Result content from tool execution
+            name: Optional name of the tool
+
+        Returns:
+            Self for method chaining
+        """
+        self.messages.append(
+            Message(role="tool", content=result, tool_call_id=tool_call_id, name=name)
+        )
+        logger.debug(f"Added tool result for call {tool_call_id} ({len(result)} chars)")
+        return self
+
+    def add_context_ref(
+        self,
+        uri: str,
+        description: str | None = None,
+        inject_as: str = "system",
+    ) -> "ChatHistoryBuilder":
+        """Add a context reference to be resolved later.
+
+        Args:
+            uri: S3 URI or registry URI to context
+            description: Optional description of the context
+            inject_as: How to inject context ('system' or 'user')
+
+        Returns:
+            Self for method chaining
+        """
+        self.context_refs.append(
+            ContextReference(uri=uri, description=description, inject_as=inject_as)
+        )
+        logger.debug(f"Added context reference: {uri} (inject as {inject_as})")
+        return self
+
+    def build(self) -> list[dict[str, Any]]:
+        """Build the final message list for LLM API.
+
+        Returns:
+            List of message dictionaries ready for LLM API
+        """
+        result = [msg.to_dict() for msg in self.messages]
+        logger.info(f"Built chat history with {len(result)} messages")
+        return result
+
+    def get_messages(self) -> list[Message]:
+        """Get the raw message list.
+
+        Returns:
+            List of Message objects
+        """
+        return self.messages
+
+    def clear(self) -> "ChatHistoryBuilder":
+        """Clear all messages and context references.
+
+        Returns:
+            Self for method chaining
+        """
+        self.messages.clear()
+        self.context_refs.clear()
+        logger.debug("Cleared chat history")
+        return self
+
+    def message_count(self) -> int:
+        """Get the number of messages in the history.
+
+        Returns:
+            Number of messages
+        """
+        return len(self.messages)
+
+    def estimate_tokens(self) -> int:
+        """Estimate token count (rough approximation).
+
+        Uses simple heuristic: ~4 characters per token.
+
+        Returns:
+            Estimated token count
+        """
+        total_chars = sum(len(msg.content or "") for msg in self.messages)
+        estimated_tokens = total_chars // 4
+        logger.debug(f"Estimated tokens: {estimated_tokens} ({total_chars} chars)")
+        return estimated_tokens

package/python/src/uer/orchestration/orchestrator.py

@@ -0,0 +1,380 @@
+"""Subagent orchestrator for multi-agent delegation and coordination."""
+
+import logging
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from ..llm.gateway import LLMGateway
+from ..storage.manager import StorageManager
+from .context import ContextManager
+
+logger = logging.getLogger(__name__)
+
+
+class DelegationResult(BaseModel):
+    """Result from a subagent delegation."""
+
+    success: bool = Field(..., description="Whether delegation succeeded")
+    response: str | None = Field(default=None, description="Final response from agent")
+    tool_calls: list[dict[str, Any]] | None = Field(
+        default=None, description="Tool calls made by agent"
+    )
+    error: str | None = Field(default=None, description="Error message if failed")
+    tokens_used: int | None = Field(default=None, description="Total tokens used in delegation")
+    model_used: str | None = Field(default=None, description="Model used for delegation")
+    iterations: int = Field(default=0, description="Number of agentic loop iterations")
+    stored_at: str | None = Field(default=None, description="URI where result was stored")
+    metadata: dict[str, Any] = Field(default_factory=dict, description="Additional metadata")
+
+
+class BehaviorLog(BaseModel):
+    """Log entry for multi-agent behavior monitoring."""
+
+    timestamp: datetime = Field(default_factory=datetime.now)
+    agent_id: str = Field(..., description="Identifier for the agent")
+    behavior_type: str = Field(
+        ..., description="Type of behavior (volunteer, conformity, destructive, etc.)"
+    )
+    description: str = Field(..., description="Description of the behavior")
+    context: dict[str, Any] = Field(default_factory=dict, description="Context information")
+    severity: str = Field(default="info", description="Severity level (info, warning, critical)")
+
+
+class SubagentOrchestrator:
+    """Orchestrates subagent delegation with multi-agent behavior monitoring.
+
+    Inspired by Chen 2024 AgentVerse research on emergent behaviors:
+    - Volunteer behaviors: Agents offering unsolicited assistance
+    - Conformity behaviors: Agents aligning with group goals
+    - Destructive behaviors: Actions leading to undesired outcomes
+    """
+
+    def __init__(
+        self,
+        gateway: LLMGateway | None = None,
+        storage: StorageManager | None = None,
+    ):
+        """Initialize orchestrator.
+
+        Args:
+            gateway: LLM gateway for model calls (creates new if None)
+            storage: Storage manager for context resolution (creates new if None)
+        """
+        self.gateway = gateway or LLMGateway()
+        self.storage = storage or StorageManager()
+        self.context_manager = ContextManager(storage=self.storage)
+        self.behavior_logs: list[BehaviorLog] = []
+        logger.info("SubagentOrchestrator initialized with ContextManager")
+
+    async def delegate(
+        self,
+        model: str,
+        messages: list[dict[str, Any]],
+        tools: list[dict[str, Any]] | None = None,
+        context_refs: list[str] | None = None,
+        context_template: str | None = None,
+        context_variables: dict[str, Any] | None = None,
+        store_result: str | None = None,
+        max_iterations: int = 10,
+        max_context_tokens: int | None = None,
+        agent_id: str | None = None,
+    ) -> DelegationResult:
+        """Delegate a task to a subagent with enhanced context assembly.
+
+        Args:
+            model: Model identifier (e.g., 'gpt-4', 'claude-3-5-sonnet')
+            messages: List of message dictionaries
+            tools: Optional list of tools available to agent
+            context_refs: Optional list of S3/registry URIs to inject as context
+            context_template: Optional Jinja2 template string or URI for context assembly
+            context_variables: Variables to inject into context template
+            store_result: Optional URI to store the final result
+            max_iterations: Maximum agentic loop iterations
+            max_context_tokens: Optional token limit for context truncation
+            agent_id: Optional identifier for behavior tracking
+
+        Returns:
+            DelegationResult with response and metadata
+        """
+        agent_id = agent_id or f"agent_{datetime.now().timestamp()}"
+        logger.info(
+            f"Delegating to {model} (agent_id: {agent_id}, " f"max_iterations: {max_iterations})"
+        )
+
+        try:
+            # Assemble and inject context using ContextManager
+            if context_refs or context_template:
+                messages = await self._inject_context(
+                    messages,
+                    context_refs,
+                    context_template,
+                    context_variables,
+                    max_context_tokens,
+                )
+
+            # Agentic loop
+            iterations = 0
+            total_tokens = 0
+            current_messages = messages.copy()
+
+            while iterations < max_iterations:
+                iterations += 1
+                logger.debug(f"Iteration {iterations}/{max_iterations}")
+
+                # Call LLM
+                response = await self.gateway.call(
+                    model=model, messages=current_messages, tools=tools
+                )
+
+                # Track token usage
+                if response.get("usage"):
+                    total_tokens += response["usage"].get("total_tokens", 0)
+
+                # Get response content
+                message = response.get("choices", [{}])[0].get("message", {})
+                content = message.get("content")
+                tool_calls = message.get("tool_calls")
+
+                # Check for destructive behavior patterns
+                if content:
+                    self._monitor_behavior(agent_id, content, "response", iterations)
+
+                # If no tool calls, we're done
+                if not tool_calls:
+                    logger.info(
+                        f"Delegation complete after {iterations} iterations "
+                        f"({total_tokens} tokens)"
+                    )
+
+                    # Store result if requested
+                    stored_at = None
+                    if store_result and content:
+                        stored_at = await self._store_result(store_result, content)
+
+                    return DelegationResult(
+                        success=True,
+                        response=content,
+                        tokens_used=total_tokens,
+                        model_used=model,
+                        iterations=iterations,
+                        stored_at=stored_at,
+                        metadata={
+                            "agent_id": agent_id,
+                            "behavior_logs": len(self.behavior_logs),
+                        },
+                    )
+
+                # Add assistant message with tool calls
+                current_messages.append(message)
+
+                # Execute tool calls (simulated for now)
+                for tool_call in tool_calls:
+                    tool_name = tool_call.get("function", {}).get("name")
+                    logger.debug(f"Tool call: {tool_name}")
+
+                    # Monitor for volunteer behavior (unsolicited tool use)
+                    self._monitor_behavior(
+                        agent_id,
+                        f"Tool call: {tool_name}",
+                        "tool_use",
+                        iterations,
+                    )
+
+                    # Add tool result (placeholder)
+                    current_messages.append(
+                        {
+                            "role": "tool",
+                            "tool_call_id": tool_call.get("id"),
+                            "content": f"Tool {tool_name} executed successfully",
+                        }
+                    )
+
+            # Max iterations reached
+            logger.warning(f"Max iterations ({max_iterations}) reached")
+            return DelegationResult(
+                success=False,
+                error=f"Maximum iterations ({max_iterations}) reached",
+                tokens_used=total_tokens,
+                model_used=model,
+                iterations=iterations,
+                metadata={
+                    "agent_id": agent_id,
+                    "behavior_logs": len(self.behavior_logs),
+                },
+            )
+
+        except Exception as e:
+            logger.error(f"Delegation failed: {e}", exc_info=True)
+            return DelegationResult(success=False, error=str(e), metadata={"agent_id": agent_id})
+
+    async def _inject_context(
+        self,
+        messages: list[dict[str, Any]],
+        context_refs: list[str] | None = None,
+        context_template: str | None = None,
+        context_variables: dict[str, Any] | None = None,
+        max_context_tokens: int | None = None,
+    ) -> list[dict[str, Any]]:
+        """Inject context from storage URIs with optional template assembly.
+
+        Uses ContextManager for enhanced features:
+        - Jinja2 template rendering with {{ uri | expand }} filter
+        - Token optimization through caching
+        - Dynamic variable injection
+        - Context truncation
+
+        Args:
+            messages: Original message list
+            context_refs: Optional list of URIs to inject
+            context_template: Optional Jinja2 template string or URI
+            context_variables: Variables for template rendering
+            max_context_tokens: Optional token limit for truncation
+
+        Returns:
+            Messages with injected context
+        """
+        injected = messages.copy()
+
+        try:
+            # Assemble context using ContextManager
+            assembled_context = await self.context_manager.assemble_context(
+                template=context_template,
+                context_refs=context_refs,
+                variables=context_variables,
+                max_tokens=max_context_tokens,
+            )
+
+            if assembled_context:
+                # Inject as system message at the beginning
+                injected.insert(
+                    0,
+                    {
+                        "role": "system",
+                        "content": assembled_context,
+                    },
+                )
+                logger.info(
+                    f"Injected assembled context ({len(assembled_context)} chars, "
+                    f"~{len(assembled_context) // 4} tokens)"
+                )
+
+        except Exception as e:
+            logger.error(f"Failed to assemble/inject context: {e}", exc_info=True)
+
+        return injected
+
+    async def _store_result(self, uri: str, content: str) -> str:
+        """Store delegation result in storage.
+
+        Args:
+            uri: URI to store at
+            content: Content to store
+
+        Returns:
+            URI where content was stored
+        """
+        try:
+            if not self.storage.is_available():
+                logger.warning("Storage not available, cannot store result")
+                return uri
+
+            await self.storage.put(
+                uri,
+                content.encode("utf-8"),
+                content_type="text/plain",
+                metadata={"type": "delegation_result", "timestamp": str(datetime.now())},
+            )
+            logger.info(f"Stored result at {uri}")
+            return uri
+
+        except Exception as e:
+            logger.error(f"Failed to store result at {uri}: {e}")
+            return uri
+
+    def _monitor_behavior(
+        self, agent_id: str, content: str, behavior_context: str, iteration: int
+    ) -> None:
+        """Monitor agent behavior for emergent patterns.
+
+        Based on Chen 2024 AgentVerse research:
+        - Volunteer: Unsolicited assistance or tool use
+        - Conformity: Alignment with instructions
+        - Destructive: Potentially harmful actions
+
+        Args:
+            agent_id: Agent identifier
+            content: Content to analyze
+            behavior_context: Context of behavior (response, tool_use, etc.)
+            iteration: Current iteration number
+        """
+        content_lower = content.lower()
+
+        # Check for destructive patterns
+        destructive_keywords = [
+            "delete",
+            "remove",
+            "destroy",
+            "override",
+            "bypass",
+            "ignore",
+            "hack",
+        ]
+        if any(keyword in content_lower for keyword in destructive_keywords):
+            self.behavior_logs.append(
+                BehaviorLog(
+                    agent_id=agent_id,
+                    behavior_type="destructive",
+                    description=f"Potentially destructive action detected: {content[:100]}",
+                    context={
+                        "iteration": iteration,
+                        "context": behavior_context,
+                    },
+                    severity="warning",
+                )
+            )
+            logger.warning(f"Destructive behavior detected in {agent_id} at iteration {iteration}")
+
+        # Check for volunteer patterns (unsolicited tool use)
+        if behavior_context == "tool_use" and iteration == 1:
+            self.behavior_logs.append(
+                BehaviorLog(
+                    agent_id=agent_id,
+                    behavior_type="volunteer",
+                    description=f"Proactive tool use: {content[:100]}",
+                    context={
+                        "iteration": iteration,
+                        "context": behavior_context,
+                    },
+                    severity="info",
+                )
+            )
+            logger.debug(f"Volunteer behavior detected in {agent_id} at iteration {iteration}")
+
+    def get_behavior_logs(
+        self, agent_id: str | None = None, behavior_type: str | None = None
+    ) -> list[BehaviorLog]:
+        """Get behavior logs with optional filtering.
+
+        Args:
+            agent_id: Optional agent ID to filter by
+            behavior_type: Optional behavior type to filter by
+
+        Returns:
+            List of matching behavior logs
+        """
+        logs = self.behavior_logs
+
+        if agent_id:
+            logs = [log for log in logs if log.agent_id == agent_id]
+
+        if behavior_type:
+            logs = [log for log in logs if log.behavior_type == behavior_type]
+
+        return logs
+
+    def clear_behavior_logs(self) -> None:
+        """Clear all behavior logs."""
+        self.behavior_logs.clear()
+        logger.info("Cleared behavior logs")

package/python/src/uer/server.py

@@ -16,6 +16,7 @@ from uer.mcp.manager import MCPManager
 from uer.models.llm import LLMCallRequest
 from uer.storage import StorageManager
 from uer.tools import skills_tools, storage_tools, template_tools
+from uer.tools.delegate import DelegateToolHandler
 
 # Configure logging
 logging.basicConfig(
@@ -40,6 +41,9 @@ if storage_manager.is_available():
 else:
     logger.info("Storage backend disabled - storage/skills/template tools will not be available")
 
+# Initialize delegate tool handler for multi-agent orchestration
+delegate_handler = DelegateToolHandler(gateway=gateway, storage=storage_manager)
+
 
 @app.list_tools()
 async def list_tools() -> list[Tool]:
@@ -277,6 +281,8 @@ async def list_tools() -> list[Tool]:
                 "required": ["operation"],
             },
         ),
+        # Delegate tool for multi-agent orchestration
+        delegate_handler.get_tool_definition(),
     ]
 
     # Conditionally add storage-dependent tools
@@ -320,6 +326,9 @@ async def call_tool(name: str, arguments: Any) -> Sequence[TextContent]:
         return await handle_mcp_registry(arguments)
     elif name == "mcp_servers":
         return await handle_mcp_servers(arguments)
+    # Delegate tool for multi-agent orchestration
+    elif name == "delegate":
+        return await delegate_handler.handle(arguments)
     # Storage tools
     elif name == "storage_put":
         return await storage_tools.storage_put(arguments)

package/python/src/uer/tools/delegate.py

@@ -0,0 +1,230 @@
+"""Delegation tool for multi-agent orchestration."""
+
+import logging
+from typing import Any
+
+from mcp.types import TextContent, Tool
+
+from ..llm.gateway import LLMGateway
+from ..orchestration.orchestrator import DelegationResult, SubagentOrchestrator
+from ..storage.manager import StorageManager
+
+logger = logging.getLogger(__name__)
+
+
+class DelegateToolHandler:
+    """Handler for the delegate tool."""
+
+    def __init__(self, gateway: LLMGateway, storage: StorageManager):
+        """Initialize delegate tool handler.
+
+        Args:
+            gateway: LLM gateway for model calls
+            storage: Storage manager for context resolution
+        """
+        self.orchestrator = SubagentOrchestrator(gateway=gateway, storage=storage)
+        logger.info("DelegateToolHandler initialized")
+
+    def get_tool_definition(self) -> Tool:
+        """Get the delegate tool definition for MCP.
+
+        Returns:
+            Tool definition
+        """
+        return Tool(
+            name="delegate",
+            description=(
+                "Delegate a task to a subagent with a different model. "
+                "Enables multi-agent orchestration with behavior monitoring. "
+                "Based on Chen 2024 AgentVerse research on emergent behaviors. "
+                "Supports context injection from S3 storage and result persistence."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "model": {
+                        "type": "string",
+                        "description": (
+                            "Model to delegate to (e.g., 'gpt-4', 'claude-3-5-sonnet-20241022', "
+                            "'gemini/gemini-2.0-flash-exp')"
+                        ),
+                    },
+                    "task": {
+                        "type": "string",
+                        "description": "Task description for the subagent",
+                    },
+                    "messages": {
+                        "type": "array",
+                        "description": (
+                            "Optional pre-built message list. If not provided, "
+                            "will create from task description."
+                        ),
+                        "items": {"type": "object"},
+                    },
+                    "tools": {
+                        "type": "array",
+                        "description": "Optional list of tools available to the subagent",
+                        "items": {"type": "object"},
+                    },
+                    "context_refs": {
+                        "type": "array",
+                        "description": (
+                            "Optional list of S3/registry URIs to inject as context "
+                            "(e.g., ['s3://uer-context/analysis.txt', 'registry://skills/financial'])"
+                        ),
+                        "items": {"type": "string"},
+                    },
+                    "context_template": {
+                        "type": "string",
+                        "description": (
+                            "Optional Jinja2 template for dynamic context assembly. "
+                            "Can be a template string or URI to template in storage. "
+                            "Supports filters: {{ uri | expand }}, "
+                            "{{ text | truncate_tokens(500) }}, {{ text | summarize(10) }}, "
+                            "{{ uri | fetch('default') }}. "
+                            "Example: 'Analysis of {{ context_0 | summarize(5) }}\\n\\n"
+                            '{{ "s3://data.txt" | expand }}\''
+                        ),
+                    },
+                    "context_variables": {
+                        "type": "object",
+                        "description": (
+                            "Variables to inject into context template. "
+                            "Context refs are automatically available as "
+                            "context_0, context_1, etc. "
+                            "Example: {'project': 'UER', 'date': '2026-01-11'}"
+                        ),
+                    },
+                    "max_context_tokens": {
+                        "type": "integer",
+                        "description": (
+                            "Optional token limit for context truncation (approximate). "
+                            "Useful for staying within model context windows."
+                        ),
+                    },
+                    "store_result": {
+                        "type": "string",
+                        "description": (
+                            "Optional URI to store the delegation result "
+                            "(e.g., 's3://uer-context/result.txt')"
+                        ),
+                    },
+                    "max_iterations": {
+                        "type": "integer",
+                        "description": "Maximum agentic loop iterations (default: 10)",
+                        "default": 10,
+                    },
+                    "agent_id": {
+                        "type": "string",
+                        "description": (
+                            "Optional identifier for behavior tracking "
+                            "(auto-generated if not provided)"
+                        ),
+                    },
+                },
+                "required": ["model", "task"],
+            },
+        )
+
+    async def handle(self, arguments: dict[str, Any]) -> list[TextContent]:
+        """Handle delegate tool call.
+
+        Args:
+            arguments: Tool arguments
+
+        Returns:
+            List of text content with delegation result
+        """
+        model = arguments["model"]
+        task = arguments["task"]
+        messages = arguments.get("messages")
+        tools = arguments.get("tools")
+        context_refs = arguments.get("context_refs")
+        context_template = arguments.get("context_template")
+        context_variables = arguments.get("context_variables")
+        max_context_tokens = arguments.get("max_context_tokens")
+        store_result = arguments.get("store_result")
+        max_iterations = arguments.get("max_iterations", 10)
+        agent_id = arguments.get("agent_id")
+
+        logger.info(f"Handling delegate call to {model} for task: {task[:100]}")
+
+        # Build messages if not provided
+        if not messages:
+            messages = [{"role": "user", "content": task}]
+
+        # Delegate to subagent with enhanced context assembly
+        result: DelegationResult = await self.orchestrator.delegate(
+            model=model,
+            messages=messages,
+            tools=tools,
+            context_refs=context_refs,
+            context_template=context_template,
+            context_variables=context_variables,
+            max_context_tokens=max_context_tokens,
+            store_result=store_result,
+            max_iterations=max_iterations,
+            agent_id=agent_id,
+        )
+
+        # Format response
+        if result.success:
+            response_text = "✅ Delegation successful\n\n"
+            response_text += f"**Model:** {result.model_used}\n"
+            response_text += f"**Iterations:** {result.iterations}\n"
+            response_text += f"**Tokens:** {result.tokens_used}\n"
+
+            if result.stored_at:
+                response_text += f"**Stored at:** {result.stored_at}\n"
+
+            # Check for behavior logs
+            behavior_logs = self.orchestrator.get_behavior_logs(
+                agent_id=result.metadata.get("agent_id")
+            )
+            if behavior_logs:
+                response_text += f"\n**Behaviors detected:** {len(behavior_logs)}\n"
+                for log in behavior_logs:
+                    response_text += f"- {log.behavior_type}: {log.description[:100]}\n"
+
+            response_text += f"\n**Response:**\n{result.response}"
+
+        else:
+            response_text = "❌ Delegation failed\n\n"
+            response_text += f"**Error:** {result.error}\n"
+            response_text += f"**Iterations:** {result.iterations}\n"
+            if result.tokens_used:
+                response_text += f"**Tokens used:** {result.tokens_used}\n"
+
+        return [TextContent(type="text", text=response_text)]
+
+    def get_behavior_summary(self) -> str:
+        """Get summary of all behavior logs.
+
+        Returns:
+            Formatted summary of behavior logs
+        """
+        logs = self.orchestrator.get_behavior_logs()
+
+        if not logs:
+            return "No behaviors logged yet."
+
+        summary = f"**Behavior Summary ({len(logs)} total)**\n\n"
+
+        # Count by type
+        by_type: dict[str, int] = {}
+        for log in logs:
+            by_type[log.behavior_type] = by_type.get(log.behavior_type, 0) + 1
+
+        summary += "**By Type:**\n"
+        for behavior_type, count in sorted(by_type.items()):
+            summary += f"- {behavior_type}: {count}\n"
+
+        # Show recent logs
+        summary += "\n**Recent Behaviors:**\n"
+        for log in logs[-5:]:
+            summary += (
+                f"- [{log.severity}] {log.agent_id}: "
+                f"{log.behavior_type} - {log.description[:80]}\n"
+            )
+
+        return summary