agent-runtime-core 0.6.0__tar.gz → 0.7.1__tar.gz

{agent_runtime_core-0.6.0 → agent_runtime_core-0.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-runtime-core
-Version: 0.6.0
+Version: 0.7.1
 Summary: Framework-agnostic Python library for executing AI agents with consistent patterns
 Project-URL: Homepage, https://github.com/makemore/agent-runtime-core
 Project-URL: Repository, https://github.com/makemore/agent-runtime-core
@@ -19,10 +19,12 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.11
 Provides-Extra: all
 Requires-Dist: anthropic>=0.18.0; extra == 'all'
+Requires-Dist: google-cloud-aiplatform>=1.38.0; extra == 'all'
 Requires-Dist: langfuse>=2.0.0; extra == 'all'
 Requires-Dist: litellm>=1.0.0; extra == 'all'
 Requires-Dist: openai>=1.0.0; extra == 'all'
 Requires-Dist: redis>=5.0.0; extra == 'all'
+Requires-Dist: sqlite-vec>=0.1.0; extra == 'all'
 Provides-Extra: anthropic
 Requires-Dist: anthropic>=0.18.0; extra == 'anthropic'
 Provides-Extra: dev
@@ -39,6 +41,10 @@ Provides-Extra: openai
 Requires-Dist: openai>=1.0.0; extra == 'openai'
 Provides-Extra: redis
 Requires-Dist: redis>=5.0.0; extra == 'redis'
+Provides-Extra: sqlite-vec
+Requires-Dist: sqlite-vec>=0.1.0; extra == 'sqlite-vec'
+Provides-Extra: vertex
+Requires-Dist: google-cloud-aiplatform>=1.38.0; extra == 'vertex'
 Description-Content-Type: text/markdown
 
 # agent-runtime-core
@@ -53,6 +59,7 @@ A lightweight, framework-agnostic Python library for building AI agent systems.
 
 | Version | Date | Changes |
 |---------|------|---------|
+| **0.7.1** | 2026-01-24 | RAG module, vector stores (sqlite-vec, Vertex AI), memory system, multi-agent support, agentic loop, JSON runtime |
 | **0.6.0** | 2025-01-23 | Enhanced registry with factory functions and class registration |
 | **0.5.2** | 2025-01-14 | Add ToolCallingAgent base class, execute_with_events helper |
 | **0.5.1** | 2025-01-13 | Bug fixes and improvements |
@@ -820,6 +827,200 @@ The executor emits events for observability:
 - `EventType.STEP_SKIPPED` - Step skipped (already completed)
 - `EventType.PROGRESS_UPDATE` - Progress percentage update
 
+## Multi-Agent Systems
+
+The `multi_agent` module provides the "agent-as-tool" pattern, allowing agents to invoke other agents as tools. This enables router/dispatcher patterns, hierarchical agent systems, and specialist delegation.
+
+### Core Concepts
+
+**Invocation Modes:**
+- `DELEGATE`: Sub-agent runs and returns result to parent (parent continues). Good for "get me an answer".
+- `HANDOFF`: Control transfers completely to sub-agent (parent exits). Good for "transfer this customer to billing".
+
+**Context Modes:**
+- `FULL`: Complete conversation history passed to sub-agent (default)
+- `SUMMARY`: Summarized context + current message (more efficient)
+- `MESSAGE_ONLY`: Only the invocation message (clean isolation)
+
+### Creating Agent Tools
+
+Wrap any agent as a tool that can be called by other agents:
+
+```python
+from agent_runtime_core.multi_agent import (
+    AgentTool,
+    InvocationMode,
+    ContextMode,
+    invoke_agent,
+    register_agent_tools,
+)
+
+# Define specialist agents
+class BillingAgent(AgentRuntime):
+    @property
+    def key(self) -> str:
+        return "billing-specialist"
+
+    async def run(self, ctx: RunContext) -> RunResult:
+        # Handle billing questions, refunds, payments
+        ...
+
+class TechSupportAgent(AgentRuntime):
+    @property
+    def key(self) -> str:
+        return "tech-support"
+
+    async def run(self, ctx: RunContext) -> RunResult:
+        # Handle technical issues
+        ...
+
+# Wrap agents as tools
+billing_tool = AgentTool(
+    agent=BillingAgent(),
+    name="billing_specialist",
+    description="Handles billing questions, refunds, and payment issues. Use when customer has billing-related questions.",
+    invocation_mode=InvocationMode.DELEGATE,
+    context_mode=ContextMode.FULL,
+)
+
+tech_support_tool = AgentTool(
+    agent=TechSupportAgent(),
+    name="tech_support",
+    description="Handles technical issues and troubleshooting. Use for technical problems.",
+    invocation_mode=InvocationMode.HANDOFF,  # Transfer control completely
+)
+```
+
+### Router Agent Pattern
+
+Create a router agent that delegates to specialists:
+
+```python
+class RouterAgent(AgentRuntime):
+    """Routes customer requests to appropriate specialist agents."""
+
+    def __init__(self):
+        self.agent_tools = [billing_tool, tech_support_tool]
+
+    @property
+    def key(self) -> str:
+        return "customer-router"
+
+    async def run(self, ctx: RunContext) -> RunResult:
+        from agent_runtime_core.llm import get_llm_client
+        llm = get_llm_client()
+
+        # Create tool registry with agent-tools
+        tools = ToolRegistry()
+        messages = list(ctx.input_messages)
+
+        # Register agent-tools as callable tools
+        register_agent_tools(
+            registry=tools,
+            agent_tools=self.agent_tools,
+            get_conversation_history=lambda: messages,
+            parent_ctx=ctx,
+        )
+
+        # Add system prompt for routing
+        system_message = {
+            "role": "system",
+            "content": """You are a customer service router. Analyze the customer's
+            request and delegate to the appropriate specialist:
+            - billing_specialist: For billing, payments, refunds
+            - tech_support: For technical issues (this will transfer the customer)
+
+            If you can answer directly, do so. Otherwise, use the appropriate tool."""
+        }
+
+        while True:
+            response = await llm.generate(
+                [system_message] + messages,
+                tools=tools.to_openai_format(),
+            )
+
+            messages.append(response.message)
+
+            if not response.tool_calls:
+                # No tool call - respond directly
+                await ctx.emit(EventType.ASSISTANT_MESSAGE, {
+                    "content": response.content,
+                })
+                break
+
+            # Execute tool calls (which may invoke sub-agents)
+            for tool_call in response.tool_calls:
+                result = await tools.execute_with_events(tool_call, ctx)
+
+                # Check for handoff
+                if isinstance(result, dict) and result.get("handoff"):
+                    # Sub-agent took over - we're done
+                    return RunResult(
+                        final_output=result.get("final_output", {}),
+                        final_messages=messages,
+                    )
+
+                # Add result to conversation
+                messages.append({
+                    "role": "tool",
+                    "tool_call_id": tool_call.id,
+                    "content": str(result.get("response", result)),
+                })
+
+        return RunResult(
+            final_output={"response": response.content},
+            final_messages=messages,
+        )
+```
+
+### Direct Invocation
+
+You can also invoke agents directly without the tool pattern:
+
+```python
+from agent_runtime_core.multi_agent import invoke_agent
+
+# Invoke a sub-agent directly
+result = await invoke_agent(
+    agent_tool=billing_tool,
+    message="Customer wants a refund for order #123",
+    parent_ctx=ctx,
+    conversation_history=messages,
+    additional_context="Customer has been waiting 2 weeks",
+)
+
+if result.handoff:
+    # Sub-agent took over
+    return RunResult(final_output=result.run_result.final_output)
+else:
+    # Use the response
+    print(result.response)
+```
+
+### Events
+
+Multi-agent invocations emit events for observability:
+
+- `sub_agent.start` - Sub-agent invocation started
+- `sub_agent.end` - Sub-agent invocation completed
+- `tool.call` with `is_agent_tool: true` - Agent-tool was called
+- `tool.result` with `is_agent_tool: true` - Agent-tool returned
+
+### AgentTool Options
+
+```python
+AgentTool(
+    agent=my_agent,                          # Required: The agent to wrap
+    name="specialist",                       # Required: Tool name
+    description="When to use this agent",    # Required: Shown to parent LLM
+    invocation_mode=InvocationMode.DELEGATE, # DELEGATE or HANDOFF
+    context_mode=ContextMode.FULL,           # FULL, SUMMARY, or MESSAGE_ONLY
+    max_turns=10,                            # Optional: Limit sub-agent turns
+    input_schema={...},                      # Optional: Custom input schema
+    metadata={"category": "billing"},        # Optional: Additional metadata
+)
+```
+
 ## API Reference
 
 ### Configuration

{agent_runtime_core-0.6.0 → agent_runtime_core-0.7.1}/README.md

@@ -10,6 +10,7 @@ A lightweight, framework-agnostic Python library for building AI agent systems.
 
 | Version | Date | Changes |
 |---------|------|---------|
+| **0.7.1** | 2026-01-24 | RAG module, vector stores (sqlite-vec, Vertex AI), memory system, multi-agent support, agentic loop, JSON runtime |
 | **0.6.0** | 2025-01-23 | Enhanced registry with factory functions and class registration |
 | **0.5.2** | 2025-01-14 | Add ToolCallingAgent base class, execute_with_events helper |
 | **0.5.1** | 2025-01-13 | Bug fixes and improvements |
@@ -777,6 +778,200 @@ The executor emits events for observability:
 - `EventType.STEP_SKIPPED` - Step skipped (already completed)
 - `EventType.PROGRESS_UPDATE` - Progress percentage update
 
+## Multi-Agent Systems
+
+The `multi_agent` module provides the "agent-as-tool" pattern, allowing agents to invoke other agents as tools. This enables router/dispatcher patterns, hierarchical agent systems, and specialist delegation.
+
+### Core Concepts
+
+**Invocation Modes:**
+- `DELEGATE`: Sub-agent runs and returns result to parent (parent continues). Good for "get me an answer".
+- `HANDOFF`: Control transfers completely to sub-agent (parent exits). Good for "transfer this customer to billing".
+
+**Context Modes:**
+- `FULL`: Complete conversation history passed to sub-agent (default)
+- `SUMMARY`: Summarized context + current message (more efficient)
+- `MESSAGE_ONLY`: Only the invocation message (clean isolation)
+
+### Creating Agent Tools
+
+Wrap any agent as a tool that can be called by other agents:
+
+```python
+from agent_runtime_core.multi_agent import (
+    AgentTool,
+    InvocationMode,
+    ContextMode,
+    invoke_agent,
+    register_agent_tools,
+)
+
+# Define specialist agents
+class BillingAgent(AgentRuntime):
+    @property
+    def key(self) -> str:
+        return "billing-specialist"
+
+    async def run(self, ctx: RunContext) -> RunResult:
+        # Handle billing questions, refunds, payments
+        ...
+
+class TechSupportAgent(AgentRuntime):
+    @property
+    def key(self) -> str:
+        return "tech-support"
+
+    async def run(self, ctx: RunContext) -> RunResult:
+        # Handle technical issues
+        ...
+
+# Wrap agents as tools
+billing_tool = AgentTool(
+    agent=BillingAgent(),
+    name="billing_specialist",
+    description="Handles billing questions, refunds, and payment issues. Use when customer has billing-related questions.",
+    invocation_mode=InvocationMode.DELEGATE,
+    context_mode=ContextMode.FULL,
+)
+
+tech_support_tool = AgentTool(
+    agent=TechSupportAgent(),
+    name="tech_support",
+    description="Handles technical issues and troubleshooting. Use for technical problems.",
+    invocation_mode=InvocationMode.HANDOFF,  # Transfer control completely
+)
+```
+
+### Router Agent Pattern
+
+Create a router agent that delegates to specialists:
+
+```python
+class RouterAgent(AgentRuntime):
+    """Routes customer requests to appropriate specialist agents."""
+
+    def __init__(self):
+        self.agent_tools = [billing_tool, tech_support_tool]
+
+    @property
+    def key(self) -> str:
+        return "customer-router"
+
+    async def run(self, ctx: RunContext) -> RunResult:
+        from agent_runtime_core.llm import get_llm_client
+        llm = get_llm_client()
+
+        # Create tool registry with agent-tools
+        tools = ToolRegistry()
+        messages = list(ctx.input_messages)
+
+        # Register agent-tools as callable tools
+        register_agent_tools(
+            registry=tools,
+            agent_tools=self.agent_tools,
+            get_conversation_history=lambda: messages,
+            parent_ctx=ctx,
+        )
+
+        # Add system prompt for routing
+        system_message = {
+            "role": "system",
+            "content": """You are a customer service router. Analyze the customer's
+            request and delegate to the appropriate specialist:
+            - billing_specialist: For billing, payments, refunds
+            - tech_support: For technical issues (this will transfer the customer)
+
+            If you can answer directly, do so. Otherwise, use the appropriate tool."""
+        }
+
+        while True:
+            response = await llm.generate(
+                [system_message] + messages,
+                tools=tools.to_openai_format(),
+            )
+
+            messages.append(response.message)
+
+            if not response.tool_calls:
+                # No tool call - respond directly
+                await ctx.emit(EventType.ASSISTANT_MESSAGE, {
+                    "content": response.content,
+                })
+                break
+
+            # Execute tool calls (which may invoke sub-agents)
+            for tool_call in response.tool_calls:
+                result = await tools.execute_with_events(tool_call, ctx)
+
+                # Check for handoff
+                if isinstance(result, dict) and result.get("handoff"):
+                    # Sub-agent took over - we're done
+                    return RunResult(
+                        final_output=result.get("final_output", {}),
+                        final_messages=messages,
+                    )
+
+                # Add result to conversation
+                messages.append({
+                    "role": "tool",
+                    "tool_call_id": tool_call.id,
+                    "content": str(result.get("response", result)),
+                })
+
+        return RunResult(
+            final_output={"response": response.content},
+            final_messages=messages,
+        )
+```
+
+### Direct Invocation
+
+You can also invoke agents directly without the tool pattern:
+
+```python
+from agent_runtime_core.multi_agent import invoke_agent
+
+# Invoke a sub-agent directly
+result = await invoke_agent(
+    agent_tool=billing_tool,
+    message="Customer wants a refund for order #123",
+    parent_ctx=ctx,
+    conversation_history=messages,
+    additional_context="Customer has been waiting 2 weeks",
+)
+
+if result.handoff:
+    # Sub-agent took over
+    return RunResult(final_output=result.run_result.final_output)
+else:
+    # Use the response
+    print(result.response)
+```
+
+### Events
+
+Multi-agent invocations emit events for observability:
+
+- `sub_agent.start` - Sub-agent invocation started
+- `sub_agent.end` - Sub-agent invocation completed
+- `tool.call` with `is_agent_tool: true` - Agent-tool was called
+- `tool.result` with `is_agent_tool: true` - Agent-tool returned
+
+### AgentTool Options
+
+```python
+AgentTool(
+    agent=my_agent,                          # Required: The agent to wrap
+    name="specialist",                       # Required: Tool name
+    description="When to use this agent",    # Required: Shown to parent LLM
+    invocation_mode=InvocationMode.DELEGATE, # DELEGATE or HANDOFF
+    context_mode=ContextMode.FULL,           # FULL, SUMMARY, or MESSAGE_ONLY
+    max_turns=10,                            # Optional: Limit sub-agent turns
+    input_schema={...},                      # Optional: Custom input schema
+    metadata={"category": "billing"},        # Optional: Additional metadata
+)
+```
+
 ## API Reference
 
 ### Configuration

{agent_runtime_core-0.6.0 → agent_runtime_core-0.7.1}/agent_runtime_core/__init__.py

@@ -34,16 +34,18 @@ Example usage:
             return RunResult(final_output={"message": "Hello!"})
 """
 
-__version__ = "0.6.0"
+__version__ = "0.7.0"
 
 # Core interfaces
 from agent_runtime_core.interfaces import (
     AgentRuntime,
     EventType,
+    EventVisibility,
     ErrorInfo,
     LLMClient,
     LLMResponse,
     LLMStreamChunk,
+    LLMToolCall,
     Message,
     RunContext,
     RunResult,
@@ -57,6 +59,12 @@ from agent_runtime_core.interfaces import (
 # Tool Calling Agent base class
 from agent_runtime_core.tool_calling_agent import ToolCallingAgent
 
+# Agentic loop helper
+from agent_runtime_core.agentic_loop import (
+    run_agentic_loop,
+    AgenticLoopResult,
+)
+
 # Configuration
 from agent_runtime_core.config import (
     RuntimeConfig,
@@ -91,6 +99,12 @@ from agent_runtime_core.steps import (
     StepCancelledError,
 )
 
+# Concrete RunContext implementations for different use cases
+from agent_runtime_core.contexts import (
+    InMemoryRunContext,
+    FileRunContext,
+)
+
 # Testing utilities
 from agent_runtime_core.testing import (
     MockRunContext,
@@ -122,6 +136,7 @@ from agent_runtime_core.persistence import (
     FileConversationStore,
     FileTaskStore,
     FilePreferencesStore,
+    FileKnowledgeStore,
     # Manager
     PersistenceManager,
     PersistenceConfig,
@@ -129,6 +144,69 @@ from agent_runtime_core.persistence import (
     configure_persistence,
 )
 
+# Agent configuration schema (portable JSON format)
+from agent_runtime_core.config_schema import (
+    AgentConfig,
+    ToolConfig,
+    KnowledgeConfig,
+    SubAgentToolConfig,
+)
+
+# JSON-based runtime (loads from AgentConfig)
+from agent_runtime_core.json_runtime import (
+    JsonAgentRuntime,
+    ConfiguredTool,
+    SubAgentTool,
+    resolve_function,
+)
+
+# Vector store (optional - requires additional dependencies)
+# Import these directly from agent_runtime_core.vectorstore when needed:
+#   from agent_runtime_core.vectorstore import (
+#       VectorStore, VectorRecord, VectorSearchResult,
+#       EmbeddingClient, OpenAIEmbeddings, VertexAIEmbeddings,
+#       get_vector_store, get_embedding_client,
+#   )
+
+# RAG (Retrieval Augmented Generation)
+from agent_runtime_core.rag import (
+    chunk_text,
+    ChunkingConfig,
+    TextChunk,
+)
+
+# RAG services are imported lazily to avoid circular dependencies
+# Import directly when needed:
+#   from agent_runtime_core.rag import KnowledgeIndexer, KnowledgeRetriever
+
+# Tool schema builder utilities
+from agent_runtime_core.tools import (
+    ToolSchema,
+    ToolSchemaBuilder,
+    ToolParameter,
+    schemas_to_openai_format,
+)
+
+# Multi-agent support (agent-as-tool pattern)
+from agent_runtime_core.multi_agent import (
+    AgentTool,
+    AgentInvocationResult,
+    InvocationMode,
+    ContextMode,
+    SubAgentContext,
+    invoke_agent,
+    create_agent_tool_handler,
+    register_agent_tools,
+    build_sub_agent_messages,
+)
+
+# Cross-conversation memory
+# Import directly when needed for full functionality:
+#   from agent_runtime_core.memory import (
+#       MemoryManager, MemoryConfig, MemoryEnabledAgent,
+#       ExtractedMemory, RecalledMemory, with_memory,
+#   )
+
 __all__ = [
     # Version
     "__version__",
@@ -137,6 +215,7 @@ __all__ = [
     "LLMClient",
     "LLMResponse",
     "LLMStreamChunk",
+    "LLMToolCall",
     "Message",
     "RunContext",
     "RunResult",
@@ -145,8 +224,12 @@ __all__ = [
     "ToolDefinition",
     "TraceSink",
     "EventType",
+    "EventVisibility",
     "ErrorInfo",
-        "ToolCallingAgent",
+    # Tool calling
+    "ToolCallingAgent",
+    "run_agentic_loop",
+    "AgenticLoopResult",
     # Configuration
     "RuntimeConfig",
     "configure",
@@ -169,6 +252,9 @@ __all__ = [
     "ExecutionState",
     "StepExecutionError",
     "StepCancelledError",
+    # Concrete RunContext implementations
+    "InMemoryRunContext",
+    "FileRunContext",
     # Testing
     "MockRunContext",
     "MockLLMClient",
@@ -195,9 +281,39 @@ __all__ = [
     "FileConversationStore",
     "FileTaskStore",
     "FilePreferencesStore",
+    "FileKnowledgeStore",
     # Persistence - Manager
     "PersistenceManager",
     "PersistenceConfig",
     "get_persistence_manager",
     "configure_persistence",
+    # Agent configuration schema
+    "AgentConfig",
+    "ToolConfig",
+    "KnowledgeConfig",
+    "SubAgentToolConfig",
+    # JSON-based runtime
+    "JsonAgentRuntime",
+    "ConfiguredTool",
+    "SubAgentTool",
+    "resolve_function",
+    # RAG (Retrieval Augmented Generation)
+    "chunk_text",
+    "ChunkingConfig",
+    "TextChunk",
+    # Tool schema builder
+    "ToolSchema",
+    "ToolSchemaBuilder",
+    "ToolParameter",
+    "schemas_to_openai_format",
+    # Multi-agent support
+    "AgentTool",
+    "AgentInvocationResult",
+    "InvocationMode",
+    "ContextMode",
+    "SubAgentContext",
+    "invoke_agent",
+    "create_agent_tool_handler",
+    "register_agent_tools",
+    "build_sub_agent_messages",
 ]