open-agent-sdk-py 0.2.0__py3-none-any.whl

open_agent_sdk/__init__.py

@@ -0,0 +1,129 @@
+"""
+open-agent-sdk - Python
+
+Open-source Agent SDK by CodeAny (https://codeany.ai).
+Runs the full agent loop in-process without spawning subprocesses.
+
+Features:
+- 10+ built-in tools (file I/O, shell, web, agents, etc.)
+- MCP server integration (stdio, SSE, HTTP)
+- Context compression (auto-compact, micro-compact)
+- Retry with exponential backoff
+- Git status & project context injection
+- Multi-turn session persistence
+- Permission system (allow/deny/bypass modes)
+- Subagent spawning
+- Hook system (pre/post tool use, lifecycle events)
+- Token estimation & cost tracking
+"""
+
+try:
+    from dotenv import load_dotenv
+
+    # Try to load .env from package root, parent dirs, or current dir
+    import pathlib
+
+    current_dir = pathlib.Path(__file__).parent.parent.parent
+    load_dotenv(str(current_dir / ".env"))
+except ImportError:
+    pass
+
+
+from open_agent_sdk.agent import Agent, create_agent, query
+from open_agent_sdk.types import (
+    AgentOptions,
+    ToolDefinition,
+    ToolInputSchema,
+    ToolContext,
+    ToolResult,
+    SDKMessage,
+    SDKAssistantMessage,
+    SDKToolResultMessage,
+    SDKResultMessage,
+    SDKPartialMessage,
+    SDKSystemMessage,
+    TokenUsage,
+    ConversationMessage,
+    UserMessage,
+    AssistantMessage,
+    Message,
+    PermissionMode,
+    McpStdioConfig,
+    McpSseConfig,
+    McpHttpConfig,
+    McpServerConfig,
+    AgentDefinition,
+    ThinkingConfig,
+    QueryResult,
+    PermissionBehavior,
+)
+from open_agent_sdk.providers.types import ApiType, LLMProvider
+from open_agent_sdk.providers import create_provider
+from open_agent_sdk.hooks import HookRegistry, HookInput, HookOutput
+from open_agent_sdk.skills import (
+    SkillDefinition,
+    SkillResult,
+    register_skill,
+    get_skill,
+    get_all_skills,
+    init_bundled_skills,
+)
+from open_agent_sdk.tools.types import define_tool, to_api_tool
+from open_agent_sdk.tools import get_all_base_tools, filter_tools
+from open_agent_sdk.sdk_mcp_server import create_sdk_mcp_server, is_sdk_server_config
+
+__all__ = [
+    # Agent
+    "Agent",
+    "create_agent",
+    "query",
+    # Types
+    "AgentOptions",
+    "ToolDefinition",
+    "ToolInputSchema",
+    "ToolContext",
+    "ToolResult",
+    "SDKMessage",
+    "SDKAssistantMessage",
+    "SDKToolResultMessage",
+    "SDKResultMessage",
+    "SDKPartialMessage",
+    "SDKSystemMessage",
+    "TokenUsage",
+    "ConversationMessage",
+    "UserMessage",
+    "AssistantMessage",
+    "Message",
+    "PermissionMode",
+    "PermissionBehavior",
+    "McpStdioConfig",
+    "McpSseConfig",
+    "McpHttpConfig",
+    "McpServerConfig",
+    "AgentDefinition",
+    "ThinkingConfig",
+    "QueryResult",
+    # Provider
+    "ApiType",
+    "LLMProvider",
+    "create_provider",
+    # Hooks
+    "HookRegistry",
+    "HookInput",
+    "HookOutput",
+    # Skills
+    "SkillDefinition",
+    "SkillResult",
+    "register_skill",
+    "get_skill",
+    "get_all_skills",
+    "init_bundled_skills",
+    # Tool helpers
+    "define_tool",
+    "to_api_tool",
+    "get_all_base_tools",
+    "filter_tools",
+    # MCP
+    "create_sdk_mcp_server",
+    "is_sdk_server_config",
+]

open_agent_sdk/agent.py

@@ -0,0 +1,391 @@
+"""
+Agent - High-level API.
+
+Provides Agent class, create_agent(), and query() interfaces.
+
+Usage:
+    from open_agent_sdk import create_agent
+
+    agent = create_agent(model="claude-sonnet-4-6")
+    async for event in agent.query("Hello"):
+        ...
+"""
+
+from __future__ import annotations
+
+import os
+import time
+import traceback
+import uuid
+from typing import Any, AsyncGenerator
+
+from open_agent_sdk.types import (
+    AgentOptions,
+    Message,
+    QueryEngineConfig,
+    QueryResult,
+    TokenUsage,
+    ToolDefinition,
+    UserMessage,
+    AssistantMessage,
+    ConversationMessage,
+)
+from open_agent_sdk.providers import create_provider, ApiType
+from open_agent_sdk.engine import QueryEngine
+from open_agent_sdk.tools import get_all_base_tools, filter_tools
+from open_agent_sdk.tools.agent_tool import register_agents
+from open_agent_sdk.session import save_session, load_session
+from open_agent_sdk.sdk_mcp_server import is_sdk_server_config
+
+
+class Agent:
+    """High-level agent interface with multi-turn support."""
+
+    def __init__(self, options: AgentOptions | None = None) -> None:
+        self._cfg = options or AgentOptions()
+        self._api_credentials = self._pick_credentials()
+        self._model_id = (
+            self._cfg.model or self._read_env("CODEANY_MODEL") or "claude-sonnet-4-6"
+        )
+        self._api_type = self._resolve_api_type()
+        self._provider = create_provider(
+            self._api_type,
+            api_key=self._api_credentials.get("key"),
+            base_url=self._api_credentials.get("base_url"),
+        )
+        self._sid = self._cfg.session_id or str(uuid.uuid4())
+        self._history: list[dict[str, Any]] = []
+        self._message_log: list[Message] = []
+        self._tool_pool: list[ToolDefinition] = self._build_tool_pool()
+        self._setup_done = False
+        self._hook_registry = self._cfg.hook_registry
+
+    def _pick_credentials(self) -> dict[str, str | None]:
+        env_map = self._cfg.env or {}
+        return {
+            "key": (
+                self._cfg.api_key
+                or env_map.get("CODEANY_API_KEY")
+                or env_map.get("CODEANY_AUTH_TOKEN")
+                or self._read_env("CODEANY_API_KEY")
+                or self._read_env("CODEANY_AUTH_TOKEN")
+            ),
+            "base_url": (
+                self._cfg.base_url
+                or env_map.get("CODEANY_BASE_URL")
+                or self._read_env("CODEANY_BASE_URL")
+            ),
+        }
+
+    @staticmethod
+    def _read_env(key: str) -> str | None:
+        val = os.environ.get(key)
+        return val if val else None
+
+    def _resolve_api_type(self) -> ApiType:
+        """Resolve API type from options, env, or model name heuristic."""
+        # Explicit option
+        if self._cfg.api_type:
+            return self._cfg.api_type
+
+        # Env var
+        env_map = self._cfg.env or {}
+        env_type = env_map.get("CODEANY_API_TYPE") or self._read_env("CODEANY_API_TYPE")
+        if env_type in ("openai-completions", "anthropic-messages"):
+            return env_type  # type: ignore[return-value]
+
+        # Heuristic from model name
+        model = self._model_id.lower()
+        openai_patterns = (
+            "gpt-",
+            "o1",
+            "o3",
+            "o4",
+            "deepseek",
+            "qwen",
+            "yi-",
+            "glm",
+            "mistral",
+            "gemma",
+        )
+        if any(p in model for p in openai_patterns):
+            return "openai-completions"
+
+        return "anthropic-messages"
+
+    def _resolve_api_type(self) -> ApiType:
+        """Resolve API type from options, env, or model name heuristic."""
+        # Explicit option
+        if self._cfg.api_type:
+            return self._cfg.api_type
+
+        # Env var
+        env_map = self._cfg.env or {}
+        env_type = env_map.get("CODEANY_API_TYPE") or self._read_env("CODEANY_API_TYPE")
+        if env_type in ("openai-completions", "anthropic-messages"):
+            return env_type  # type: ignore[return-value]
+
+        # Heuristic from model name
+        model = self._model_id.lower()
+        openai_patterns = (
+            "gpt-",
+            "o1",
+            "o3",
+            "o4",
+            "deepseek",
+            "qwen",
+            "yi-",
+            "glm",
+            "mistral",
+            "gemma",
+        )
+        if any(p in model for p in openai_patterns):
+            return "openai-completions"
+
+        return "anthropic-messages"
+
+    def _build_tool_pool(self) -> list[ToolDefinition]:
+        raw = self._cfg.tools
+        if raw is None:
+            pool = get_all_base_tools()
+        elif isinstance(raw, list) and raw and isinstance(raw[0], str):
+            pool = filter_tools(get_all_base_tools(), raw)  # type: ignore[arg-type]
+        elif isinstance(raw, list):
+            pool = list(raw)  # type: ignore[arg-type]
+        else:
+            pool = get_all_base_tools()
+
+        return filter_tools(pool, self._cfg.allowed_tools, self._cfg.disallowed_tools)
+
+    async def _setup(self) -> None:
+        if self._setup_done:
+            return
+        self._setup_done = True
+
+        # Register custom agent definitions
+        if self._cfg.agents:
+            register_agents(self._cfg.agents)
+
+        # Connect MCP servers
+        if self._cfg.mcp_servers:
+            for name, config in self._cfg.mcp_servers.items():
+                try:
+                    if is_sdk_server_config(config):
+                        self._tool_pool = [*self._tool_pool, *config.tools]
+                    else:
+                        from open_agent_sdk.mcp.client import connect_mcp_server
+
+                        connection = await connect_mcp_server(name, config)
+                        if connection.status == "connected" and connection.tools:
+                            self._tool_pool = [*self._tool_pool, *connection.tools]
+                except Exception as e:
+                    print(f"[MCP] Failed to connect to '{name}': {e}")
+
+        # Resume session
+        if self._cfg.resume:
+            session_data = await load_session(self._cfg.resume)
+            if session_data:
+                self._history = session_data.get("messages", [])
+                self._sid = self._cfg.resume
+
+    async def query(
+        self,
+        prompt: str,
+        **overrides: Any,
+    ) -> AsyncGenerator[dict[str, Any], None]:
+        """Run a query with streaming events."""
+        await self._setup()
+
+        cwd = overrides.get("cwd") or self._cfg.cwd or os.getcwd()
+        model = overrides.get("model") or self._cfg.model or self._model_id
+
+        # Resolve tools with overrides
+        tools = self._tool_pool
+        if "allowed_tools" in overrides or "disallowed_tools" in overrides:
+            tools = filter_tools(
+                tools,
+                overrides.get("allowed_tools"),
+                overrides.get("disallowed_tools"),
+            )
+        if "tools" in overrides:
+            ot = overrides["tools"]
+            if isinstance(ot, list) and ot and isinstance(ot[0], str):
+                tools = filter_tools(self._tool_pool, ot)
+            elif isinstance(ot, list):
+                tools = ot
+
+        # Recreate provider if overrides change credentials or apiType
+        provider = self._provider
+        if (
+            overrides.get("api_type")
+            or overrides.get("api_key")
+            or overrides.get("base_url")
+        ):
+            resolved_api_type = overrides.get("api_type") or self._api_type
+            provider = create_provider(
+                resolved_api_type,
+                api_key=overrides.get("api_key") or self._api_credentials.get("key"),
+                base_url=overrides.get("base_url")
+                or self._api_credentials.get("base_url"),
+            )
+
+        # Build query engine config
+        config = QueryEngineConfig(
+            cwd=cwd,
+            model=model,
+            provider=provider,
+            tools=tools,
+            system_prompt=overrides.get("system_prompt") or self._cfg.system_prompt,
+            append_system_prompt=overrides.get("append_system_prompt")
+            or self._cfg.append_system_prompt,
+            max_turns=overrides.get("max_turns", self._cfg.max_turns),
+            max_budget_usd=overrides.get("max_budget_usd") or self._cfg.max_budget_usd,
+            max_tokens=overrides.get("max_tokens", self._cfg.max_tokens),
+            thinking=overrides.get("thinking") or self._cfg.thinking,
+            include_partial_messages=overrides.get(
+                "include_partial_messages", self._cfg.include_partial_messages
+            ),
+            agents=overrides.get("agents") or self._cfg.agents,
+            hook_registry=self._hook_registry,
+            session_id=self._sid,
+        )
+
+        engine = QueryEngine(config)
+
+        # Inject existing conversation history
+        for msg in self._history:
+            engine.messages.append(msg)
+
+        # Run the engine
+        try:
+            async for event in engine.submit_message(prompt):
+                yield event
+
+                # Track assistant messages
+                if isinstance(event, dict) and event.get("type") == "assistant":
+                    self._message_log.append(
+                        AssistantMessage(
+                            message=event.get("message", {}),
+                        )
+                    )
+        except Exception as exc:
+            yield {
+                "type": "result",
+                "subtype": "error_during_execution",
+                "usage": {
+                    "input_tokens": 0,
+                    "output_tokens": 0,
+                    "cache_creation_input_tokens": 0,
+                    "cache_read_input_tokens": 0,
+                },
+                "num_turns": 0,
+                "cost": 0.0,
+                "is_error": True,
+                "error": str(exc),
+                "traceback": traceback.format_exc(),
+            }
+
+        # Persist conversation state for multi-turn
+        self._history = engine.get_messages()
+
+        # Track user message
+        self._message_log.append(
+            UserMessage(
+                message=ConversationMessage(role="user", content=prompt),
+            )
+        )
+
+        # Save session if configured
+        if self._cfg.persist_session:
+            await save_session(
+                self._sid,
+                self._history,
+                {"model": model, "cwd": cwd},
+            )
+
+    async def prompt(
+        self,
+        text: str,
+        **overrides: Any,
+    ) -> QueryResult:
+        """Send a prompt and collect the final answer."""
+        t0 = time.monotonic()
+        collected_text = ""
+        collected_turns = 0
+        collected_usage = TokenUsage()
+        collected_error: str | None = None
+        is_error = False
+
+        async for ev in self.query(text, **overrides):
+            if not isinstance(ev, dict):
+                continue
+            if ev.get("type") == "assistant":
+                msg = ev.get("message", {})
+                fragments = [
+                    b.get("text", "")
+                    for b in msg.get("content", [])
+                    if isinstance(b, dict) and b.get("type") == "text"
+                ]
+                if fragments:
+                    collected_text = "".join(fragments)
+
+            elif ev.get("type") == "result":
+                collected_turns = ev.get("num_turns", 0)
+                usage_data = ev.get("usage", {})
+                if isinstance(usage_data, dict):
+                    collected_usage = TokenUsage(**usage_data)
+                if ev.get("is_error"):
+                    is_error = True
+                    collected_error = ev.get("error")
+
+        duration_ms = round((time.monotonic() - t0) * 1000)
+
+        return QueryResult(
+            text=collected_text,
+            usage=collected_usage,
+            num_turns=collected_turns,
+            duration_ms=duration_ms,
+            messages=list(self._message_log),
+            is_error=is_error,
+            error=collected_error,
+        )
+
+    def get_messages(self) -> list[Message]:
+        """Get conversation messages."""
+        return list(self._message_log)
+
+    def clear(self) -> None:
+        """Reset conversation history."""
+        self._history = []
+        self._message_log = []
+
+    async def set_model(self, model: str) -> None:
+        self._model_id = model
+        self._cfg.model = model
+
+    @property
+    def session_id(self) -> str:
+        return self._sid
+
+
+def create_agent(
+    model: str | None = None,
+    **kwargs: Any,
+) -> Agent:
+    """Create a new Agent instance.
+
+    Usage:
+        agent = create_agent(model="claude-sonnet-4-6", max_turns=10)
+    """
+    opts = AgentOptions(model=model, **kwargs)
+    return Agent(opts)
+
+
+async def query(
+    prompt: str,
+    model: str | None = None,
+    **kwargs: Any,
+) -> QueryResult:
+    """One-shot query: create agent, send prompt, return result."""
+    agent = create_agent(model=model, **kwargs)
+    return await agent.prompt(prompt)