cloudbase-agent-core 0.1.1__py3-none-any.whl

cloudbase_agent/__init__.py

@@ -0,0 +1,69 @@
+"""Agents Package.
+
+This package provides agent creation utilities for the Cloudbase Agent Python SDK.
+It includes base agent classes and framework-specific implementations with
+lazy loading support for optional dependencies.
+
+Framework Support:
+    - LangGraph: Install with `pip install cloudbase_agent_py[langgraph]`
+    - CrewAI: Install with `pip install cloudbase_agent_py[crewai]`
+    - All frameworks: Install with `pip install cloudbase_agent_py[all]`
+
+Available Classes:
+    - BaseAgent: Abstract base class for all Cloudbase Agent agents
+    - AgentCallback: Protocol for event callbacks
+    - ToolProxy: Protocol for tool call interception
+    - ToolCallResult: Result of tool proxy interception
+    - LangGraphAgent: LangGraph-based agent implementation (lazy-loaded)
+    - CrewAIAgent: CrewAI-based agent implementation (lazy-loaded)
+
+Example:
+    Using LangGraph::
+
+        # Install: pip install cloudbase_agent_py[langgraph]
+        from cloudbase_agent.agents import LangGraphAgent
+        from langgraph.graph import StateGraph
+
+        workflow = StateGraph(State)
+        compiled_graph = workflow.compile()
+        agent = LangGraphAgent("MyAgent", "Description", compiled_graph)
+
+    Using CrewAI::
+
+        # Install: pip install cloudbase_agent_py[crewai]
+        from cloudbase_agent.agents import CrewAIAgent
+        from crewai.flow.flow import Flow
+
+        class MyFlow(Flow):
+            pass
+
+        flow = MyFlow()
+        agent = CrewAIAgent("MyAgent", "Description", flow)
+
+Note:
+    Framework-specific agents are lazy-loaded. If you try to import an agent
+    without installing its dependencies, you'll get a helpful error message
+    indicating which package to install.
+"""
+
+import lazy_loader as lazy
+
+# Eager imports (always available, no optional dependencies)
+from .base_agent import AgentCallback, BaseAgent, ToolCallResult, ToolProxy
+
+# Lazy imports setup (framework-specific agents loaded on demand)
+__getattr__, __dir__, __all__ = lazy.attach_stub(__name__, __file__)
+
+# Ensure base classes and lazy-loaded agents are in __all__
+__all__ = [
+    "BaseAgent",
+    "AgentCallback",
+    "ToolProxy",
+    "ToolCallResult",
+    "LangGraphAgent",  # Lazy-loaded when accessed
+    "CrewAIAgent",     # Lazy-loaded when accessed
+]
+
+# Enable namespace package support to allow other cloudbase_agent subpackages
+# (like cloudbase_agent.server, cloudbase_agent.storage) to be imported
+__path__ = __import__('pkgutil').extend_path(__path__, __name__)

cloudbase_agent/__init__.pyi

@@ -0,0 +1,12 @@
+"""Type stubs for cloudbase_agent core package.
+
+This stub file provides type hints for IDE and static analysis tools.
+"""
+
+# Eager imports (always available)
+from .base_agent import AgentCallback as AgentCallback
+from .base_agent import BaseAgent as BaseAgent
+from .base_agent import ToolCallResult as ToolCallResult
+from .base_agent import ToolProxy as ToolProxy
+
+__all__: list[str]

cloudbase_agent/base_agent.py

@@ -0,0 +1,743 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Base Agent Class.
+
+This module provides the abstract base class for all Cloudbase Agent agents.
+It defines the common interface and functionality that all agent implementations
+must provide, similar to the TypeScript Agent class.
+
+Enhanced with optional callback support, context management, and event processing utilities.
+"""
+
+import json
+from abc import ABC, abstractmethod
+from contextlib import contextmanager
+from contextvars import ContextVar
+from typing import Any, AsyncGenerator, Dict, List, Optional, Protocol
+
+from ag_ui.core import BaseEvent, EventType, RunAgentInput
+
+
+# Callback Protocol
+class AgentCallback(Protocol):
+    """Agent callback protocol for event processing.
+
+    Callbacks can be used to intercept and process events during agent execution,
+    enabling features like logging, monitoring, state mutation, and custom event handling.
+
+    All callback methods are optional - implement only the ones you need.
+    """
+
+    async def on_text_message_content(self, event: BaseEvent, buffer: str) -> Optional[Dict[str, Any]]:
+        """Called when text message content is received.
+
+        :param event: The text message content event
+        :type event: BaseEvent
+        :param buffer: Accumulated text buffer for this message
+        :type buffer: str
+        :return: Optional mutation dict to modify agent state
+        :rtype: Optional[Dict[str, Any]]
+        """
+        ...
+
+    async def on_tool_call_args(
+        self, event: BaseEvent, buffer: str, partial_args: Dict[str, Any]
+    ) -> Optional[Dict[str, Any]]:
+        """Called when tool call arguments are received.
+
+        :param event: The tool call args event
+        :type event: BaseEvent
+        :param buffer: Raw accumulated argument string
+        :type buffer: str
+        :param partial_args: Partially parsed arguments (if valid JSON)
+        :type partial_args: Dict[str, Any]
+        :return: Optional mutation dict to modify agent state
+        :rtype: Optional[Dict[str, Any]]
+        """
+        ...
+
+    async def on_run_started(self, event: BaseEvent) -> None:
+        """Called when agent run starts.
+
+        :param event: The run started event
+        :type event: BaseEvent
+        """
+        ...
+
+    async def on_run_finished(self, event: BaseEvent) -> None:
+        """Called when agent run finishes.
+
+        :param event: The run finished event
+        :type event: BaseEvent
+        """
+        ...
+
+    async def on_run_error(self, event: BaseEvent) -> None:
+        """Called when agent run encounters an error.
+
+        :param event: The run error event
+        :type event: BaseEvent
+        """
+        ...
+
+
+# ============ ToolProxy Protocol ============
+class ToolCallResult:
+    """Result of a tool call interception.
+
+    This class encapsulates the result of a tool proxy's interception,
+    allowing proxies to either allow, block, or modify tool calls.
+    """
+
+    def __init__(
+        self,
+        allowed: bool = True,
+        modified_args: Optional[Dict[str, Any]] = None,
+        override_result: Optional[Any] = None,
+        error_message: Optional[str] = None,
+    ):
+        """Initialize tool call result.
+
+        :param allowed: Whether the tool call is allowed to proceed
+        :type allowed: bool
+        :param modified_args: Modified arguments (if None, use original)
+        :type modified_args: Optional[Dict[str, Any]]
+        :param override_result: Override result without calling the tool
+        :type override_result: Optional[Any]
+        :param error_message: Error message if call is blocked
+        :type error_message: Optional[str]
+        """
+        self.allowed = allowed
+        self.modified_args = modified_args
+        self.override_result = override_result
+        self.error_message = error_message
+
+
+class ToolProxy(Protocol):
+    """Tool proxy protocol for intercepting and modifying tool calls.
+
+    Tool proxies can be used to:
+    - Validate and modify tool arguments before execution
+    - Implement permission checks and access control
+    - Cache tool results
+    - Log tool usage
+    - Implement human-in-the-loop approval
+    - Transform or filter tool results
+
+    All proxy methods are optional - implement only the ones you need.
+    """
+
+    async def before_tool_call(self, tool_name: str, args: Dict[str, Any], context: Dict[str, Any]) -> ToolCallResult:
+        """Called before a tool is invoked.
+
+        This method can:
+        - Validate arguments
+        - Modify arguments
+        - Block the tool call
+        - Return a cached result
+        - Request human approval
+
+        :param tool_name: Name of the tool being called
+        :type tool_name: str
+        :param args: Tool arguments
+        :type args: Dict[str, Any]
+        :param context: Additional context (thread_id, run_id, etc.)
+        :type context: Dict[str, Any]
+        :return: Result indicating whether to proceed and any modifications
+        :rtype: ToolCallResult
+        """
+        ...
+
+    async def after_tool_call(
+        self,
+        tool_name: str,
+        args: Dict[str, Any],
+        result: Any,
+        context: Dict[str, Any],
+    ) -> Any:
+        """Called after a tool has been invoked.
+
+        This method can:
+        - Transform the result
+        - Cache the result
+        - Log the result
+        - Trigger side effects
+
+        :param tool_name: Name of the tool that was called
+        :type tool_name: str
+        :param args: Tool arguments that were used
+        :type args: Dict[str, Any]
+        :param result: Result returned by the tool
+        :type result: Any
+        :param context: Additional context (thread_id, run_id, etc.)
+        :type context: Dict[str, Any]
+        :return: Potentially modified result
+        :rtype: Any
+        """
+        ...
+
+    async def on_tool_error(
+        self,
+        tool_name: str,
+        args: Dict[str, Any],
+        error: Exception,
+        context: Dict[str, Any],
+    ) -> Optional[Any]:
+        """Called when a tool call raises an error.
+
+        This method can:
+        - Handle the error gracefully
+        - Return a fallback result
+        - Re-raise the error
+        - Log the error
+
+        :param tool_name: Name of the tool that failed
+        :type tool_name: str
+        :param args: Tool arguments that were used
+        :type args: Dict[str, Any]
+        :param error: The exception that was raised
+        :type error: Exception
+        :param context: Additional context (thread_id, run_id, etc.)
+        :type context: Dict[str, Any]
+        :return: Optional fallback result (None to re-raise)
+        :rtype: Optional[Any]
+        """
+        ...
+
+
+# Context Management
+_current_agent: ContextVar[Optional["BaseAgent"]] = ContextVar("current_agent", default=None)
+
+
+class BaseAgent(ABC):
+    """Abstract base class for all Cloudbase Agent agents.
+
+    This class defines the common interface that all agent implementations
+    must follow. It provides the basic structure for agent configuration,
+    execution, and event handling.
+
+    Enhanced with optional features:
+    - Callback system for event processing (monitoring, logging)
+    - Tool proxy system for tool call interception (validation, control)
+    - Context management for accessing current agent
+    - Event ID fixing utilities
+    - Buffer management for streaming events
+
+    :param name: Human-readable name for the agent
+    :type name: str
+    :param description: Detailed description of the agent's purpose and capabilities
+    :type description: str
+    :param agent: The underlying agent implementation (e.g., LangGraphAgent)
+    :type agent: Any
+    :param flow: Optional flow/graph object for the agent
+    :type flow: Any
+
+    Example:
+        Creating a custom agent implementation::
+
+            class MyCustomAgent(BaseAgent):
+                def __init__(self, name: str, description: str, custom_config: dict):
+                    # Initialize with custom agent implementation
+                    agent = create_custom_agent(custom_config)
+                    super().__init__(name, description, agent)
+
+                async def run(
+                    self,
+                    run_input: RunAgentInput
+                ) -> AsyncGenerator[BaseEvent, None]:
+                    # Implement custom run logic
+                    pass
+
+        Using callbacks::
+
+            class LoggingCallback:
+                async def on_text_message_content(self, event, buffer):
+                    print(f"Message: {buffer}")
+                    return None
+
+            agent = MyCustomAgent(...)
+            agent.add_callback(LoggingCallback())
+
+    Note:
+        All concrete agent implementations must implement the abstract `run` method.
+    """
+
+    def __init__(self, name: str, description: str, agent: Any, flow: Any = None):
+        """Initialize the base agent.
+
+        :param name: Human-readable name for the agent
+        :type name: str
+        :param description: Detailed description of the agent's purpose and capabilities
+        :type description: str
+        :param agent: The underlying agent implementation
+        :type agent: Any
+        :param flow: Optional flow/graph object
+        :type flow: Any
+        """
+        self._name = name
+        self._description = description
+        self._agent = agent
+        self._flow = flow
+
+        # Optional callback support
+        self._callbacks: List[AgentCallback] = []
+
+        # Optional tool proxy support
+        self._tool_proxies: List[ToolProxy] = []
+
+        # Optional buffer management for streaming events
+        self._text_buffers: Dict[str, str] = {}
+        self._tool_call_buffers: Dict[str, Dict[str, Any]] = {}
+
+    @property
+    def name(self) -> str:
+        """Get the agent name.
+
+        :return: Agent name
+        :rtype: str
+        """
+        return self._name
+
+    @property
+    def description(self) -> str:
+        """Get the agent description.
+
+        :return: Agent description
+        :rtype: str
+        """
+        return self._description
+
+    @property
+    def agent(self) -> Any:
+        """Get the underlying agent implementation.
+
+        :return: The underlying agent instance
+        :rtype: Any
+        """
+        return self._agent
+
+    @property
+    def flow(self) -> Any:
+        """Get the flow/graph object.
+
+        :return: The flow/graph instance
+        :rtype: Any
+        """
+        return self._flow
+
+    # ============ Callback System ============
+
+    def add_callback(self, callback: AgentCallback) -> None:
+        """Add a callback for event processing.
+
+        :param callback: Callback instance implementing AgentCallback protocol
+        :type callback: AgentCallback
+        """
+        self._callbacks.append(callback)
+
+    def remove_callback(self, callback: AgentCallback) -> None:
+        """Remove a callback.
+
+        :param callback: Callback instance to remove
+        :type callback: AgentCallback
+        """
+        if callback in self._callbacks:
+            self._callbacks.remove(callback)
+
+    def clear_callbacks(self) -> None:
+        """Remove all callbacks."""
+        self._callbacks.clear()
+
+    # Tool Proxy Management
+
+    def add_tool_proxy(self, proxy: ToolProxy) -> None:
+        """Add a tool proxy to intercept tool calls.
+
+        Tool proxies are invoked in the order they are added.
+        Each proxy can modify arguments, block calls, or transform results.
+
+        :param proxy: Tool proxy instance to add
+        :type proxy: ToolProxy
+
+        Example::
+
+            class PermissionProxy:
+                async def before_tool_call(self, tool_name, args, context):
+                    if not self.has_permission(tool_name):
+                        return ToolCallResult(allowed=False, error_message="Permission denied")
+                    return ToolCallResult(allowed=True)
+
+            agent.add_tool_proxy(PermissionProxy())
+        """
+        self._tool_proxies.append(proxy)
+
+    def remove_tool_proxy(self, proxy: ToolProxy) -> None:
+        """Remove a tool proxy.
+
+        :param proxy: Tool proxy instance to remove
+        :type proxy: ToolProxy
+        """
+        if proxy in self._tool_proxies:
+            self._tool_proxies.remove(proxy)
+
+    def clear_tool_proxies(self) -> None:
+        """Remove all tool proxies."""
+        self._tool_proxies.clear()
+
+    async def _invoke_tool_proxies_before(
+        self, tool_name: str, args: Dict[str, Any], context: Dict[str, Any]
+    ) -> ToolCallResult:
+        """Invoke all tool proxies before a tool call.
+
+        Proxies are invoked in order. If any proxy blocks the call,
+        the chain stops and the blocking result is returned.
+
+        :param tool_name: Name of the tool being called
+        :type tool_name: str
+        :param args: Tool arguments
+        :type args: Dict[str, Any]
+        :param context: Additional context (thread_id, run_id, etc.)
+        :type context: Dict[str, Any]
+        :return: Aggregated result from all proxies
+        :rtype: ToolCallResult
+        """
+        if not self._tool_proxies:
+            return ToolCallResult(allowed=True)
+
+        current_args = args
+        for proxy in self._tool_proxies:
+            if hasattr(proxy, "before_tool_call"):
+                result = await proxy.before_tool_call(tool_name, current_args, context)
+
+                # If blocked, stop the chain
+                if not result.allowed:
+                    return result
+
+                # If result has override, stop the chain
+                if result.override_result is not None:
+                    return result
+
+                # If args were modified, use them for next proxy
+                if result.modified_args is not None:
+                    current_args = result.modified_args
+
+        # All proxies passed, return final args
+        return ToolCallResult(allowed=True, modified_args=current_args)
+
+    async def _invoke_tool_proxies_after(
+        self,
+        tool_name: str,
+        args: Dict[str, Any],
+        result: Any,
+        context: Dict[str, Any],
+    ) -> Any:
+        """Invoke all tool proxies after a tool call.
+
+        Proxies are invoked in order. Each proxy can transform the result.
+
+        :param tool_name: Name of the tool that was called
+        :type tool_name: str
+        :param args: Tool arguments that were used
+        :type args: Dict[str, Any]
+        :param result: Result returned by the tool
+        :type result: Any
+        :param context: Additional context (thread_id, run_id, etc.)
+        :type context: Dict[str, Any]
+        :return: Potentially transformed result
+        :rtype: Any
+        """
+        if not self._tool_proxies:
+            return result
+
+        current_result = result
+        for proxy in self._tool_proxies:
+            if hasattr(proxy, "after_tool_call"):
+                current_result = await proxy.after_tool_call(tool_name, args, current_result, context)
+
+        return current_result
+
+    async def _invoke_tool_proxies_error(
+        self,
+        tool_name: str,
+        args: Dict[str, Any],
+        error: Exception,
+        context: Dict[str, Any],
+    ) -> Optional[Any]:
+        """Invoke all tool proxies when a tool call fails.
+
+        Proxies are invoked in order. The first proxy that returns a non-None
+        result will provide the fallback value.
+
+        :param tool_name: Name of the tool that failed
+        :type tool_name: str
+        :param args: Tool arguments that were used
+        :type args: Dict[str, Any]
+        :param error: The exception that was raised
+        :type error: Exception
+        :param context: Additional context (thread_id, run_id, etc.)
+        :type context: Dict[str, Any]
+        :return: Optional fallback result (None to re-raise)
+        :rtype: Optional[Any]
+        """
+        if not self._tool_proxies:
+            return None
+
+        for proxy in self._tool_proxies:
+            if hasattr(proxy, "on_tool_error"):
+                fallback = await proxy.on_tool_error(tool_name, args, error, context)
+                if fallback is not None:
+                    return fallback
+
+        return None
+
+    # ============ Callback Management ============
+
+    async def _invoke_callbacks(self, event: BaseEvent) -> Optional[Dict[str, Any]]:
+        """Invoke callbacks for an event.
+
+        This method processes events through registered callbacks and manages
+        internal buffers for streaming events.
+
+        :param event: Event to process
+        :type event: BaseEvent
+        :return: Aggregated mutations from all callbacks
+        :rtype: Optional[Dict[str, Any]]
+        """
+        if not self._callbacks:
+            return None
+
+        mutations = {}
+
+        # Handle text message events
+        if event.type == EventType.TEXT_MESSAGE_CONTENT:
+            message_id = getattr(event, "message_id", None)
+            if message_id:
+                # Update buffer
+                delta = getattr(event, "delta", "")
+                self._text_buffers[message_id] = self._text_buffers.get(message_id, "") + delta
+
+                # Invoke callbacks
+                for callback in self._callbacks:
+                    if hasattr(callback, "on_text_message_content"):
+                        result = await callback.on_text_message_content(event, self._text_buffers[message_id])
+                        if result:
+                            mutations.update(result)
+
+        # Handle tool call events
+        elif event.type == EventType.TOOL_CALL_ARGS:
+            tool_call_id = getattr(event, "tool_call_id", None)
+            if tool_call_id:
+                # Update buffer
+                delta = getattr(event, "delta", "")
+                if tool_call_id not in self._tool_call_buffers:
+                    self._tool_call_buffers[tool_call_id] = {
+                        "buffer": "",
+                        "partial_args": {},
+                    }
+
+                self._tool_call_buffers[tool_call_id]["buffer"] += delta
+
+                # Try to parse partial JSON
+                try:
+                    partial_args = json.loads(self._tool_call_buffers[tool_call_id]["buffer"])
+                    self._tool_call_buffers[tool_call_id]["partial_args"] = partial_args
+                except (json.JSONDecodeError, ValueError):
+                    # Not valid JSON yet, keep accumulating
+                    pass
+
+                # Invoke callbacks
+                for callback in self._callbacks:
+                    if hasattr(callback, "on_tool_call_args"):
+                        result = await callback.on_tool_call_args(
+                            event,
+                            self._tool_call_buffers[tool_call_id]["buffer"],
+                            self._tool_call_buffers[tool_call_id]["partial_args"],
+                        )
+                        if result:
+                            mutations.update(result)
+
+        # Handle lifecycle events
+        elif event.type == EventType.RUN_STARTED:
+            for callback in self._callbacks:
+                if hasattr(callback, "on_run_started"):
+                    await callback.on_run_started(event)
+
+        elif event.type == EventType.RUN_FINISHED:
+            # Clear buffers on run finish
+            self._text_buffers.clear()
+            self._tool_call_buffers.clear()
+
+            for callback in self._callbacks:
+                if hasattr(callback, "on_run_finished"):
+                    await callback.on_run_finished(event)
+
+        elif event.type == EventType.RUN_ERROR:
+            for callback in self._callbacks:
+                if hasattr(callback, "on_run_error"):
+                    await callback.on_run_error(event)
+
+        return mutations if mutations else None
+
+    async def _process_event(self, event: BaseEvent) -> AsyncGenerator[BaseEvent, None]:
+        """Process an event through callbacks and yield result.
+
+        This is a helper method that subclasses can use to integrate callbacks
+        into their event processing pipeline.
+
+        :param event: Event to process
+        :type event: BaseEvent
+        :yield: Processed event (potentially modified by callbacks)
+        :rtype: AsyncGenerator[BaseEvent, None]
+        """
+        # Invoke callbacks
+        mutations = await self._invoke_callbacks(event)
+
+        # Apply mutations if any
+        if mutations:
+            await self._apply_mutations(mutations)
+
+        # Yield the event
+        yield event
+
+    async def _apply_mutations(self, mutations: Dict[str, Any]) -> None:
+        """Apply mutations to agent state.
+
+        Subclasses should override this to implement state mutation logic.
+        By default, this method does nothing.
+
+        :param mutations: Mutations to apply
+        :type mutations: Dict[str, Any]
+        """
+        pass
+
+    # Context Management
+
+    @contextmanager
+    def as_current(self):
+        """Context manager to set this agent as current.
+
+        This allows accessing the current agent from anywhere in the call stack
+        using BaseAgent.get_current().
+
+        :yields: The current agent instance
+        :ytype: BaseAgent
+
+        Example::
+
+            with agent.as_current():
+                # agent is now accessible via BaseAgent.get_current()
+                current = BaseAgent.get_current()
+                assert current is agent
+        """
+        token = _current_agent.set(self)
+        try:
+            yield self
+        finally:
+            _current_agent.reset(token)
+
+    @staticmethod
+    def get_current() -> Optional["BaseAgent"]:
+        """Get the current agent from context.
+
+        :return: Current agent or None if no agent is set
+        :rtype: Optional[BaseAgent]
+        """
+        return _current_agent.get()
+
+    # ============ Event ID Fixing ============
+
+    def _fix_event_ids(self, event: BaseEvent, thread_id: str, run_id: str) -> BaseEvent:
+        """Fix event IDs to match run context.
+
+        Useful for frameworks that don't set thread_id/run_id correctly.
+        This method modifies the event in-place.
+
+        :param event: Event to fix
+        :type event: BaseEvent
+        :param thread_id: Correct thread ID
+        :type thread_id: str
+        :param run_id: Correct run ID
+        :type run_id: str
+        :return: Fixed event (same instance)
+        :rtype: BaseEvent
+        """
+        if hasattr(event, "thread_id") and not event.thread_id:
+            event.thread_id = thread_id
+        if hasattr(event, "run_id") and not event.run_id:
+            event.run_id = run_id
+        return event
+
+    # Core Interface
+
+    @abstractmethod
+    def run(self, run_input: RunAgentInput) -> AsyncGenerator[BaseEvent, None]:
+        """Execute the agent with the given input.
+
+        This is the main execution method that all agent implementations must provide.
+        It should process the input, execute the agent logic, and yield events
+        representing the agent's progress and results.
+
+        :param run_input: Input data for the agent execution containing messages, run_id,
+                         thread_id, state, context, tools, and forwarded_props
+        :type run_input: RunAgentInput
+
+        :yield: Events representing the agent's execution progress
+        :rtype: AsyncGenerator[BaseEvent, None]
+
+        :raises NotImplementedError: If the method is not implemented by subclass
+
+        Example:
+            Implementing the run method::
+
+                from ag_ui.core import RunAgentInput
+
+                async def run(
+                    self,
+                    run_input: RunAgentInput
+                ) -> AsyncGenerator[BaseEvent, None]:
+                    # Emit run started event
+                    yield RunStartedEvent(
+                        type=EventType.RUN_STARTED,
+                        thread_id=run_input.thread_id,
+                        run_id=run_input.run_id
+                    )
+
+                    try:
+                        # Execute agent logic
+                        result = await self._agent.execute(run_input)
+
+                        # Emit result events
+                        yield TextMessageStartEvent(...)
+                        yield TextMessageContentEvent(...)
+                        yield TextMessageEndEvent(...)
+
+                        # Emit run finished event
+                        yield RunFinishedEvent(
+                            type=EventType.RUN_FINISHED,
+                            thread_id=run_input.thread_id,
+                            run_id=run_input.run_id
+                        )
+                    except Exception as e:
+                        # Emit error event
+                        yield RunErrorEvent(
+                            type=EventType.RUN_ERROR,
+                            thread_id=run_input.thread_id,
+                            run_id=run_input.run_id,
+                            message=str(e)
+                        )
+        """
+        raise NotImplementedError("Subclasses must implement the run method")
+
+    def destroy(self) -> None:
+        """Clean up resources used by the agent.
+
+        This method should be called when the agent is no longer needed
+        to properly release any resources (connections, memory, etc.).
+
+        Subclasses can override this method to provide custom cleanup logic.
+        """
+        # Clear callbacks, proxies, and buffers
+        self._callbacks.clear()
+        self._tool_proxies.clear()
+        self._text_buffers.clear()
+        self._tool_call_buffers.clear()

cloudbase_agent/schemas/__init__.py

@@ -0,0 +1,58 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Cloudbase Agent type definitions organized by domain.
+
+All type definitions are centralized here to avoid circular dependencies.
+"""
+
+from .core import Message, MessageRole, IMemoryEvent
+from .streaming import StreamEvent, EventType, BaseEvent
+from .tools import ToolCall, ToolResult, ToolFunction, ErrorType
+from .server import (
+    Tool,
+    SystemMessage,
+    UserMessage,
+    ToolMessage,
+    AssistantMessage,
+    ClientMessage,
+    ResumeMessage,
+    SendMessageRequest,
+    SendMessageResponse,
+)
+from .storage import Checkpoint, CheckpointMetadata, CheckpointConfig
+from .types import JSON, Headers, Metadata, AgentState
+
+__all__ = [
+    # Core types
+    "Message",
+    "MessageRole",
+    "IMemoryEvent",
+    # Streaming types
+    "StreamEvent",
+    "EventType",
+    "BaseEvent",
+    # Tool types
+    "ToolCall",
+    "ToolResult",
+    "ToolFunction",
+    "ErrorType",
+    # Server types
+    "Tool",
+    "SystemMessage",
+    "UserMessage",
+    "ToolMessage",
+    "AssistantMessage",
+    "ClientMessage",
+    "ResumeMessage",
+    "SendMessageRequest",
+    "SendMessageResponse",
+    # Storage types
+    "Checkpoint",
+    "CheckpointMetadata",
+    "CheckpointConfig",
+    # Common types
+    "JSON",
+    "Headers",
+    "Metadata",
+    "AgentState",
+]

cloudbase_agent/schemas/core.py

@@ -0,0 +1,35 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Core message and event types.
+
+This module defines the fundamental message and event types used throughout Cloudbase Agent.
+"""
+
+from typing import Literal, Optional
+from pydantic import BaseModel
+
+
+class MessageRole:
+    """Message role constants."""
+    SYSTEM = "system"
+    USER = "user"
+    ASSISTANT = "assistant"
+    TOOL = "tool"
+
+
+class Message(BaseModel):
+    """Base message model."""
+    role: Literal["system", "user", "assistant", "tool"]
+    content: str
+    
+    class Config:
+        """Pydantic model configuration."""
+        validate_by_name = True
+        validate_assignment = True
+
+
+class IMemoryEvent(BaseModel):
+    """Memory event interface."""
+    type: str
+    timestamp: float
+    data: dict

cloudbase_agent/schemas/server.py

@@ -0,0 +1,113 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Server API types.
+
+This module defines types for server API requests and responses.
+"""
+
+from typing import Any, List, Literal, Optional, Union
+from pydantic import BaseModel, ConfigDict, Field
+
+from .tools import ToolCall
+
+
+class Tool(BaseModel):
+    """Tool definition.
+    
+    :param name: The name of the tool
+    :type name: str
+    :param description: Human-readable description of the tool
+    :type description: str
+    :param parameters: JSON schema defining the tool's input parameters
+    :type parameters: Any
+    """
+    name: str
+    description: str
+    parameters: Any
+
+
+class SystemMessage(BaseModel):
+    """System message."""
+    role: Literal["system"] = "system"
+    content: str
+    
+    class Config:
+        """Pydantic model configuration."""
+        validate_by_name = True
+        validate_assignment = True
+
+
+class UserMessage(BaseModel):
+    """User message."""
+    role: Literal["user"] = "user"
+    content: str
+    
+    class Config:
+        """Pydantic model configuration."""
+        validate_by_name = True
+        validate_assignment = True
+
+
+class ToolMessage(BaseModel):
+    """Tool result message."""
+    role: Literal["tool"] = "tool"
+    content: str
+    tool_call_id: str = Field(..., alias="toolCallId")
+    
+    class Config:
+        """Pydantic model configuration."""
+        validate_by_name = True
+        validate_assignment = True
+
+
+class AssistantMessage(BaseModel):
+    """AI assistant message."""
+    id: str
+    role: Literal["assistant"] = "assistant"
+    content: Optional[str] = None
+    tool_calls: Optional[List[ToolCall]] = Field(None, alias="toolCalls")
+    
+    class Config:
+        """Pydantic model configuration."""
+        validate_by_name = True
+        validate_assignment = True
+
+
+ClientMessage = Union[SystemMessage, UserMessage, ToolMessage, AssistantMessage]
+
+
+class ResumeMessage(BaseModel):
+    """Resume message for interrupted conversations."""
+    interruptId: str
+    payload: str
+
+
+class SendMessageRequest(BaseModel):
+    """Send message API request.
+    
+    :param messages: List of conversation messages
+    :type messages: Optional[List[ClientMessage]]
+    :param tools: Optional list of available tools
+    :type tools: Optional[List[Tool]]
+    :param resume: Optional resume message
+    :type resume: Optional[ResumeMessage]
+    :param conversationId: Unique identifier for the conversation
+    :type conversationId: str
+    """
+    messages: Optional[List[ClientMessage]] = []
+    tools: Optional[List[Tool]] = []
+    resume: Optional[ResumeMessage] = None
+    conversationId: str
+    
+    class Config:
+        """Pydantic model configuration."""
+        validate_by_name = True
+        validate_assignment = True
+
+
+class SendMessageResponse(BaseModel):
+    """Send message API response."""
+    model_config = ConfigDict(populate_by_name=True)
+    
+    type: str
+    data: Any

cloudbase_agent/schemas/storage.py

@@ -0,0 +1,66 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Storage and checkpoint types.
+
+This module defines types for checkpoint storage and state management.
+"""
+
+from typing import Any, Dict, Optional
+from pydantic import BaseModel
+
+
+class CheckpointMetadata(BaseModel):
+    """Checkpoint metadata.
+    
+    :param source: Source of the checkpoint (e.g., "update", "input")
+    :type source: str
+    :param step: Step number in the execution
+    :type step: int
+    :param writes: Optional writes metadata
+    :type writes: Optional[Dict[str, Any]]
+    """
+    source: str = "update"
+    step: int = -1
+    writes: Optional[Dict[str, Any]] = None
+
+
+class CheckpointConfig(BaseModel):
+    """Checkpoint configuration.
+    
+    :param thread_id: Thread identifier
+    :type thread_id: str
+    :param checkpoint_ns: Checkpoint namespace
+    :type checkpoint_ns: str
+    :param checkpoint_id: Optional checkpoint identifier
+    :type checkpoint_id: Optional[str]
+    """
+    thread_id: str
+    checkpoint_ns: str = ""
+    checkpoint_id: Optional[str] = None
+
+
+class Checkpoint(BaseModel):
+    """Checkpoint data.
+    
+    :param v: Checkpoint version
+    :type v: int
+    :param id: Checkpoint identifier
+    :type id: str
+    :param ts: Timestamp
+    :type ts: str
+    :param channel_values: Channel values
+    :type channel_values: Dict[str, Any]
+    :param channel_versions: Channel versions
+    :type channel_versions: Dict[str, Any]
+    :param versions_seen: Versions seen
+    :type versions_seen: Dict[str, Any]
+    :param pending_sends: Pending sends
+    :type pending_sends: list
+    """
+    v: int = 1
+    id: str
+    ts: str
+    channel_values: Dict[str, Any]
+    channel_versions: Dict[str, Any]
+    versions_seen: Dict[str, Any]
+    pending_sends: list = []

cloudbase_agent/schemas/streaming.py

@@ -0,0 +1,39 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Streaming event types.
+
+This module defines event types for streaming agent responses.
+"""
+
+from typing import Any, Literal, Optional
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class EventType:
+    """Event type constants."""
+    RUN_STARTED = "run-started"
+    RUN_FINISHED = "run-finished"
+    RUN_ERROR = "run-error"
+    TEXT_MESSAGE_START = "text-message-start"
+    TEXT_MESSAGE_CONTENT = "text-message-content"
+    TEXT_MESSAGE_END = "text-message-end"
+    TOOL_CALL_START = "tool-call-start"
+    TOOL_CALL_ARGS = "tool-call-args"
+    TOOL_CALL_END = "tool-call-end"
+    TOOL_RESULT = "tool-result"
+    INTERRUPT = "interrupt"
+    ERROR = "error"
+
+
+class BaseEvent(BaseModel):
+    """Base event model."""
+    model_config = ConfigDict(populate_by_name=True)
+    
+    type: str
+    thread_id: Optional[str] = Field(None, alias="threadId")
+    run_id: Optional[str] = Field(None, alias="runId")
+
+
+class StreamEvent(BaseEvent):
+    """Generic streaming event."""
+    data: Optional[Any] = None

cloudbase_agent/schemas/tools.py

@@ -0,0 +1,59 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Tool-related types.
+
+This module defines types for tool calls, results, and errors.
+"""
+
+from typing import Any, Dict, Literal, Optional
+from pydantic import BaseModel, Field
+
+
+class ErrorType:
+    """Tool error type constants."""
+    VALIDATION_ERROR = "validation_error"
+    EXECUTION_ERROR = "execution_error"
+    TIMEOUT_ERROR = "timeout_error"
+    PERMISSION_ERROR = "permission_error"
+
+
+class ToolFunction(BaseModel):
+    """Tool function definition.
+    
+    :param name: The name of the function to call
+    :type name: str
+    :param arguments: JSON-serialized function arguments as a string
+    :type arguments: str
+    """
+    name: str
+    arguments: str
+
+
+class ToolCall(BaseModel):
+    """Tool function call.
+    
+    :param id: Unique identifier for this tool call
+    :type id: str
+    :param type: Type of the call, always "function"
+    :type type: Literal["function"]
+    :param function: The function being called with its arguments
+    :type function: ToolFunction
+    """
+    id: str
+    type: Literal["function"] = "function"
+    function: ToolFunction
+
+
+class ToolResult(BaseModel):
+    """Tool execution result.
+    
+    :param tool_call_id: ID of the tool call this result corresponds to
+    :type tool_call_id: str
+    :param result: The tool execution result
+    :type result: str
+    :param error: Optional error message if execution failed
+    :type error: Optional[str]
+    """
+    tool_call_id: str = Field(..., alias="toolCallId")
+    result: Optional[str] = None
+    error: Optional[str] = None

cloudbase_agent/schemas/types.py

@@ -0,0 +1,14 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Common utility types.
+
+This module defines common utility types used throughout Cloudbase Agent.
+"""
+
+from typing import Any, Dict
+
+# Type aliases
+JSON = Dict[str, Any]
+Headers = Dict[str, str]
+Metadata = Dict[str, Any]
+AgentState = Dict[str, Any]

cloudbase_agent_core-0.1.1.dist-info/METADATA

@@ -0,0 +1,28 @@
+Metadata-Version: 2.4
+Name: cloudbase-agent-core
+Version: 0.1.1
+Summary: Cloudbase Agent Python SDK - Core functionality
+Author-email: Cloudbase Agent Team <ag-kit@example.com>
+License: Apache-2.0
+Keywords: Cloudbase Agent,agent,ai,llm
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Requires-Dist: ag-ui-protocol>=0.1.9
+Requires-Dist: lazy-loader>=0.4
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.12.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Cloudbase Agent Python SDK - Core
+
+Core functionality for Cloudbase Agent Python SDK, including base agent classes and protocols.

cloudbase_agent_core-0.1.1.dist-info/RECORD

@@ -0,0 +1,13 @@
+cloudbase_agent/__init__.py,sha256=b7HT7WjWOzZ1l8eoUXFEVYM9co6GQJwr91KtszoHlHU,2486
+cloudbase_agent/__init__.pyi,sha256=-JkUj3AM5FEX0IoJWAHiOuuDPAdVsRTQIqgWJi4OfYg,385
+cloudbase_agent/base_agent.py,sha256=diliCEZb1hFm64gG_bcKLxxbWVCd38OnLXoaI-Y6IaA,25528
+cloudbase_agent/schemas/__init__.py,sha256=QGu4M3MSXJinbPBH4lSnYN24C3Y-tzkUthUwcYhmMpc,1306
+cloudbase_agent/schemas/core.py,sha256=P9VbHyA-rQgBHj0gPEJofQnkHkwiUklW8z8ha5YjE0I,771
+cloudbase_agent/schemas/server.py,sha256=IlEkjKg9ixiVgm22C50UFYp6qGsZcb7igg2b4S_kJUY,2917
+cloudbase_agent/schemas/storage.py,sha256=wzxZ9XjPVgldpB4-8GCL1A1APSKne-Brxmo-FGdkYew,1761
+cloudbase_agent/schemas/streaming.py,sha256=kpFiZr1GAagl8Utg9LDwd-ZEbVirhzPpJZpHhuJyT3Q,1055
+cloudbase_agent/schemas/tools.py,sha256=UXQEf6rLRlMjYZjhR9mkEulf2oVsId_fwA3mMzIN4i0,1579
+cloudbase_agent/schemas/types.py,sha256=QhO5ZMo2CYwWGshyMqZ3_LUAZahiAh21mUo3NVbRSQc,298
+cloudbase_agent_core-0.1.1.dist-info/METADATA,sha256=Rc5jc7jh5V3aKg7r_vgpwIXnLA85DMQjaZZCgeQYaRI,1091
+cloudbase_agent_core-0.1.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+cloudbase_agent_core-0.1.1.dist-info/RECORD,,

cloudbase_agent_core-0.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any