agent-runtime-core 0.6.0__py3-none-any.whl → 0.7.1__py3-none-any.whl

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",
 ]

agent_runtime_core/agentic_loop.py

@@ -0,0 +1,254 @@
+"""
+Reusable agentic loop for tool-calling agents.
+
+This module provides a flexible `run_agentic_loop` function that handles
+the standard tool-calling pattern:
+1. Call LLM with tools
+2. If tool calls, execute them and loop back
+3. If no tool calls, return final response
+
+This can be used by any agent implementation without requiring inheritance.
+"""
+
+import json
+import logging
+from dataclasses import dataclass
+from typing import Any, Callable, Optional, Awaitable, Union
+
+from agent_runtime_core.interfaces import (
+    RunContext,
+    EventType,
+    LLMClient,
+    LLMResponse,
+)
+
+logger = logging.getLogger(__name__)
+
+# Type alias for tool executor function
+ToolExecutor = Callable[[str, dict], Awaitable[Any]]
+
+
+@dataclass
+class AgenticLoopResult:
+    """Result from running the agentic loop."""
+    
+    final_content: str
+    """The final text response from the LLM."""
+    
+    messages: list[dict]
+    """All messages including tool calls and results."""
+    
+    iterations: int
+    """Number of iterations the loop ran."""
+    
+    usage: dict
+    """Token usage from the final LLM call."""
+
+
+async def run_agentic_loop(
+    llm: LLMClient,
+    messages: list[dict],
+    tools: Optional[list[dict]],
+    execute_tool: ToolExecutor,
+    ctx: RunContext,
+    *,
+    model: Optional[str] = None,
+    max_iterations: int = 15,
+    emit_events: bool = True,
+    **llm_kwargs,
+) -> AgenticLoopResult:
+    """
+    Run the standard agentic tool-calling loop.
+    
+    This handles the common pattern of:
+    1. Call LLM with available tools
+    2. If LLM returns tool calls, execute them
+    3. Add tool results to messages and loop back to step 1
+    4. If LLM returns a text response (no tool calls), return it
+    
+    Args:
+        llm: The LLM client to use for generation
+        messages: Initial messages (should include system prompt)
+        tools: List of tool schemas in OpenAI format, or None for no tools
+        execute_tool: Async function that executes a tool: (name, args) -> result
+        ctx: Run context for emitting events
+        model: Model to use (passed to LLM client)
+        max_iterations: Maximum loop iterations to prevent infinite loops
+        emit_events: Whether to emit TOOL_CALL and TOOL_RESULT events
+        **llm_kwargs: Additional kwargs passed to llm.generate()
+    
+    Returns:
+        AgenticLoopResult with final content, messages, and metadata
+    
+    Example:
+        async def my_tool_executor(name: str, args: dict) -> Any:
+            if name == "get_weather":
+                return {"temp": 72, "conditions": "sunny"}
+            raise ValueError(f"Unknown tool: {name}")
+        
+        result = await run_agentic_loop(
+            llm=my_llm_client,
+            messages=[{"role": "system", "content": "You are helpful."}],
+            tools=[{"type": "function", "function": {...}}],
+            execute_tool=my_tool_executor,
+            ctx=ctx,
+            model="gpt-4o",
+        )
+    """
+    iteration = 0
+    final_content = ""
+    last_response: Optional[LLMResponse] = None
+    consecutive_errors = 0
+    max_consecutive_errors = 3  # Bail out if tool keeps failing
+
+    while iteration < max_iterations:
+        iteration += 1
+        print(f"[agentic-loop] Iteration {iteration}/{max_iterations}, messages={len(messages)}", flush=True)
+        logger.debug(f"Agentic loop iteration {iteration}/{max_iterations}")
+
+        # Call LLM
+        if tools:
+            response = await llm.generate(
+                messages,
+                model=model,
+                tools=tools,
+                **llm_kwargs,
+            )
+        else:
+            response = await llm.generate(
+                messages,
+                model=model,
+                **llm_kwargs,
+            )
+        
+        last_response = response
+        
+        # Check for tool calls
+        if response.tool_calls:
+            # Add assistant message with tool calls to conversation
+            messages.append(response.message)
+            
+            # Execute each tool call
+            for tool_call in response.tool_calls:
+                # Debug: log raw tool call to help diagnose empty args issue
+                print(f"[agentic-loop] Raw tool_call type={type(tool_call).__name__}", flush=True)
+                if hasattr(tool_call, '_data'):
+                    print(f"[agentic-loop] tool_call._data={tool_call._data}", flush=True)
+
+                # Handle both ToolCall objects (with .id, .name, .arguments) and dicts
+                if hasattr(tool_call, 'id') and not isinstance(tool_call, dict):
+                    # ToolCall object
+                    tool_call_id = tool_call.id
+                    tool_name = tool_call.name
+                    tool_args = tool_call.arguments
+                    print(f"[agentic-loop] Parsed: name={tool_name}, args={tool_args}", flush=True)
+                else:
+                    # Dict format
+                    tool_call_id = tool_call.get("id")
+                    tool_name = tool_call.get("function", {}).get("name")
+                    tool_args_str = tool_call.get("function", {}).get("arguments", "{}")
+                    logger.debug(f"Dict tool_call: id={tool_call_id}, name={tool_name}, args_str={tool_args_str}")
+                    # Parse arguments (handle both string and dict)
+                    if isinstance(tool_args_str, dict):
+                        tool_args = tool_args_str
+                    else:
+                        try:
+                            tool_args = json.loads(tool_args_str)
+                        except json.JSONDecodeError:
+                            logger.warning(f"Failed to parse tool args: {tool_args_str}")
+                            tool_args = {}
+                
+                # Emit tool call event
+                if emit_events:
+                    await ctx.emit(EventType.TOOL_CALL, {
+                        "id": tool_call_id,
+                        "name": tool_name,
+                        "arguments": tool_args,
+                    })
+                
+                # Execute the tool
+                try:
+                    result = await execute_tool(tool_name, tool_args)
+                    # Reset error counter on success
+                    if not isinstance(result, dict) or "error" not in result:
+                        consecutive_errors = 0
+                    else:
+                        consecutive_errors += 1
+                except Exception as e:
+                    logger.exception(f"Error executing tool {tool_name}")
+                    result = {"error": str(e)}
+                    consecutive_errors += 1
+
+                # Emit tool result event
+                if emit_events:
+                    await ctx.emit(EventType.TOOL_RESULT, {
+                        "tool_call_id": tool_call_id,
+                        "name": tool_name,
+                        "result": result,
+                    })
+
+                # Add tool result to messages
+                result_str = json.dumps(result) if not isinstance(result, str) else result
+                messages.append({
+                    "role": "tool",
+                    "tool_call_id": tool_call_id,
+                    "content": result_str,
+                })
+
+                # Check for too many consecutive errors
+                if consecutive_errors >= max_consecutive_errors:
+                    error_msg = result.get('error', 'Unknown error') if isinstance(result, dict) else str(result)
+                    logger.warning(f"Aborting agentic loop after {consecutive_errors} consecutive tool errors: {error_msg}")
+
+                    # Emit error event for run history
+                    if emit_events:
+                        await ctx.emit(EventType.ERROR, {
+                            "error": f"Tool loop aborted after {consecutive_errors} consecutive errors",
+                            "last_error": error_msg,
+                            "tool_name": tool_name,
+                            "iterations": iteration,
+                        })
+
+                    # Add error to messages for conversation history
+                    final_content = f"I encountered repeated errors while trying to complete this task. The last error was: {error_msg}"
+                    messages.append({
+                        "role": "assistant",
+                        "content": final_content,
+                    })
+
+                    if emit_events:
+                        await ctx.emit(EventType.ASSISTANT_MESSAGE, {
+                            "content": final_content,
+                            "role": "assistant",
+                        })
+
+                    return AgenticLoopResult(
+                        final_content=final_content,
+                        messages=messages,
+                        iterations=iteration,
+                        usage=last_response.usage if last_response else {},
+                    )
+
+            # Continue the loop to get next response
+            continue
+        
+        # No tool calls - we have the final response
+        final_content = response.message.get("content", "")
+        messages.append(response.message)
+
+        # Emit assistant message event for the final response
+        if emit_events and final_content:
+            await ctx.emit(EventType.ASSISTANT_MESSAGE, {
+                "content": final_content,
+                "role": "assistant",
+            })
+
+        break
+    
+    return AgenticLoopResult(
+        final_content=final_content,
+        messages=messages,
+        iterations=iteration,
+        usage=last_response.usage if last_response else {},
+    )
+

agent_runtime_core/config.py

@@ -59,7 +59,35 @@ class RuntimeConfig:
     max_retries: int = 3
     retry_backoff_base: int = 2
     retry_backoff_max: int = 300
-    
+
+    # Conversation history settings
+    # When True, agents automatically receive message history from previous runs
+    # in the same conversation. This enables multi-turn conversations by default.
+    include_conversation_history: bool = True
+
+    # Maximum number of history messages to include (None = no limit)
+    # Useful for limiting context window usage with long conversations
+    max_history_messages: Optional[int] = None
+
+    # Whether to automatically persist messages after each run
+    # When True, final_messages are saved to the conversation store
+    auto_persist_messages: bool = True
+
+    # Vector store settings
+    vector_store_backend: str = "none"  # none, sqlite_vec, pgvector, vertex
+    vector_store_path: Optional[str] = None  # For sqlite_vec file path
+
+    # Embedding settings
+    embedding_provider: str = "openai"  # openai, vertex
+    embedding_model: str = "text-embedding-3-small"
+
+    # Vertex AI settings (for vertex vector store and embeddings)
+    vertex_project_id: Optional[str] = None
+    vertex_location: str = "us-central1"
+    vertex_index_endpoint_id: Optional[str] = None
+    vertex_deployed_index_id: Optional[str] = None
+    vertex_index_id: Optional[str] = None
+
     def get_openai_api_key(self) -> Optional[str]:
         """Get OpenAI API key from config or environment."""
         return self.openai_api_key or os.environ.get("OPENAI_API_KEY")
@@ -150,8 +178,19 @@ def _apply_env_vars(config: RuntimeConfig) -> None:
         "AGENT_RUNTIME_LANGFUSE_PUBLIC_KEY": "langfuse_public_key",
         "AGENT_RUNTIME_LANGFUSE_SECRET_KEY": "langfuse_secret_key",
         "AGENT_RUNTIME_LANGFUSE_HOST": "langfuse_host",
+        # Vector store settings
+        "AGENT_RUNTIME_VECTOR_STORE_BACKEND": "vector_store_backend",
+        "AGENT_RUNTIME_VECTOR_STORE_PATH": "vector_store_path",
+        "AGENT_RUNTIME_EMBEDDING_PROVIDER": "embedding_provider",
+        "AGENT_RUNTIME_EMBEDDING_MODEL": "embedding_model",
+        # Vertex AI settings
+        "AGENT_RUNTIME_VERTEX_PROJECT_ID": "vertex_project_id",
+        "AGENT_RUNTIME_VERTEX_LOCATION": "vertex_location",
+        "AGENT_RUNTIME_VERTEX_INDEX_ENDPOINT_ID": "vertex_index_endpoint_id",
+        "AGENT_RUNTIME_VERTEX_DEPLOYED_INDEX_ID": "vertex_deployed_index_id",
+        "AGENT_RUNTIME_VERTEX_INDEX_ID": "vertex_index_id",
     }
-    
+
     int_fields = {
         "AGENT_RUNTIME_RUN_TIMEOUT_SECONDS": "run_timeout_seconds",
         "AGENT_RUNTIME_HEARTBEAT_INTERVAL_SECONDS": "heartbeat_interval_seconds",
@@ -159,14 +198,25 @@ def _apply_env_vars(config: RuntimeConfig) -> None:
         "AGENT_RUNTIME_MAX_RETRIES": "max_retries",
         "AGENT_RUNTIME_RETRY_BACKOFF_BASE": "retry_backoff_base",
         "AGENT_RUNTIME_RETRY_BACKOFF_MAX": "retry_backoff_max",
+        "AGENT_RUNTIME_MAX_HISTORY_MESSAGES": "max_history_messages",
     }
-    
+
+    bool_fields = {
+        "AGENT_RUNTIME_INCLUDE_CONVERSATION_HISTORY": "include_conversation_history",
+        "AGENT_RUNTIME_AUTO_PERSIST_MESSAGES": "auto_persist_messages",
+    }
+
     for env_var, attr in env_mapping.items():
         value = os.environ.get(env_var)
         if value is not None:
             setattr(config, attr, value)
-    
+
     for env_var, attr in int_fields.items():
         value = os.environ.get(env_var)
         if value is not None:
             setattr(config, attr, int(value))
+
+    for env_var, attr in bool_fields.items():
+        value = os.environ.get(env_var)
+        if value is not None:
+            setattr(config, attr, value.lower() in ("true", "1", "yes", "on"))