kagent-claude 0.2.0__py3-none-any.whl

kagent/claude/__init__.py

@@ -0,0 +1,23 @@
+from importlib.metadata import PackageNotFoundError, version
+
+from ._a2a import KAgentApp
+from ._executor import ClaudeAgentExecutor, ClaudeAgentExecutorConfig
+from ._hitl import ApprovalDecision, HitlBridge
+from ._session_store import ClaudeSessionStore, SessionStore
+from ._tracing import trace_query
+
+__all__ = [
+    "KAgentApp",
+    "ClaudeAgentExecutor",
+    "ClaudeAgentExecutorConfig",
+    "ClaudeSessionStore",
+    "SessionStore",
+    "HitlBridge",
+    "ApprovalDecision",
+    "trace_query",
+]
+
+try:
+    __version__ = version("kagent-claude")
+except PackageNotFoundError:
+    __version__ = "0.0.0-dev"

kagent/claude/_a2a.py

@@ -0,0 +1,132 @@
+"""KAgent Claude Agent SDK A2A Server Integration."""
+
+import faulthandler
+import logging
+from contextlib import asynccontextmanager
+
+import httpx
+from a2a.server.apps import A2AStarletteApplication
+from a2a.server.request_handlers import DefaultRequestHandler
+from a2a.types import AgentCard
+from claude_agent_sdk import ClaudeAgentOptions
+from fastapi import FastAPI, Request
+from fastapi.responses import PlainTextResponse
+
+from kagent.core import KAgentConfig, configure_logging, configure_tracing
+from kagent.core.a2a import (
+    KAgentRequestContextBuilder,
+    KAgentTaskStore,
+    get_a2a_max_content_length,
+)
+
+from ._executor import ClaudeAgentExecutor, ClaudeAgentExecutorConfig
+from ._session_store import ClaudeSessionStore
+
+logger = logging.getLogger(__name__)
+
+
+def _health_check(request: Request) -> PlainTextResponse:
+    return PlainTextResponse("OK")
+
+
+def _thread_dump(request: Request) -> PlainTextResponse:
+    import tempfile
+
+    with tempfile.TemporaryFile(mode="w+") as tmp:
+        faulthandler.dump_traceback(file=tmp, all_threads=True)
+        tmp.seek(0)
+        return PlainTextResponse(tmp.read())
+
+
+class KAgentApp:
+    """
+    Builds an A2A-compliant HTTP server wrapping the Claude Agent SDK.
+
+    Usage:
+        app = KAgentApp(
+            options=ClaudeAgentOptions(allowed_tools=["Bash", "Read"]),
+            agent_card=AgentCard(...),
+            config=KAgentConfig(),  # reads from KAGENT_URL, KAGENT_NAME, KAGENT_NAMESPACE env vars
+        )
+        app.run()
+    """
+
+    def __init__(
+        self,
+        *,
+        options: ClaudeAgentOptions,
+        agent_card: AgentCard,
+        config: KAgentConfig = None,
+        executor_config: ClaudeAgentExecutorConfig | None = None,
+        tracing: bool = True,
+    ):
+        self._options = options
+        self.agent_card = AgentCard.model_validate(agent_card)
+        self.config = config or KAgentConfig()
+        self._enable_tracing = tracing
+        self._session_store = ClaudeSessionStore()
+        self._executor_config = executor_config or ClaudeAgentExecutorConfig()
+
+    def build(self) -> FastAPI:
+        """Construct and return the FastAPI ASGI application."""
+        http_client = httpx.AsyncClient(base_url=self.config.url)
+
+        agent_executor = ClaudeAgentExecutor(
+            options=self._options,
+            session_store=self._session_store,
+            app_name=self.config.app_name,
+            config=self._executor_config,
+        )
+
+        task_store = KAgentTaskStore(http_client)
+        request_context_builder = KAgentRequestContextBuilder(task_store=task_store)
+        request_handler = DefaultRequestHandler(
+            agent_executor=agent_executor,
+            task_store=task_store,
+            request_context_builder=request_context_builder,
+        )
+
+        max_content_length = get_a2a_max_content_length()
+        a2a_app = A2AStarletteApplication(
+            agent_card=self.agent_card,
+            http_handler=request_handler,
+            max_content_length=max_content_length,
+        )
+
+        # Lifespan for graceful shutdown
+        @asynccontextmanager
+        async def lifespan(app: FastAPI):
+            logger.info(f"KAgent Claude starting: {self.config.app_name}")
+            yield
+            # Shutdown: cancel running queries
+            await agent_executor.shutdown()
+            await http_client.aclose()
+            logger.info(f"KAgent Claude stopped: {self.config.app_name}")
+
+        faulthandler.enable()
+        app = FastAPI(
+            title=f"KAgent Claude: {self.config.app_name}",
+            description=f"Claude Agent SDK with KAgent integration: {self.agent_card.description}",
+            version=self.agent_card.version,
+            lifespan=lifespan,
+        )
+
+        configure_logging()
+
+        if self._enable_tracing:
+            try:
+                configure_tracing(self.config.name, self.config.namespace, app)
+            except Exception:
+                logger.exception("Failed to configure tracing")
+
+        app.add_route("/health", methods=["GET"], route=_health_check)
+        app.add_route("/thread_dump", methods=["GET"], route=_thread_dump)
+        a2a_app.add_routes_to_app(app)
+
+        return app
+
+    def run(self, host: str = "0.0.0.0", port: int = 8080) -> None:
+        """Start the uvicorn server. Blocks until shutdown."""
+        import uvicorn
+
+        uvicorn.run(self.build(), host=host, port=port)

kagent/claude/_converters.py

@@ -0,0 +1,217 @@
+"""
+Convert Claude Agent SDK messages to A2A DataParts for streaming intermediate events.
+
+The Claude Agent SDK yields several message types during execution:
+- SystemMessage (subtype="init") — session initialization
+- AssistantMessage — Claude's thinking/response with content blocks
+- ToolUseBlock (in AssistantMessage.content) — tool invocation
+- ToolResultBlock (in UserMessage/ResultMessage) — tool result
+- ResultMessage — final aggregated result
+
+This module converts these into structured A2A DataParts so the kagent
+dashboard can display real-time agent activity.
+"""
+
+import hashlib
+from datetime import datetime, timezone
+from typing import Any
+
+from a2a.types import DataPart, Message, Part, Role, TaskState, TaskStatus, TaskStatusUpdateEvent, TextPart
+
+from kagent.core.a2a import (
+    A2A_DATA_PART_METADATA_TYPE_FUNCTION_CALL,
+    A2A_DATA_PART_METADATA_TYPE_KEY,
+    get_kagent_metadata_key,
+)
+
+# Metadata type for tool results (matching langgraph's convention)
+A2A_DATA_PART_METADATA_TYPE_FUNCTION_RESPONSE = "function_response"
+
+
+def convert_assistant_message(message) -> list[Part] | None:
+    """
+    Convert an AssistantMessage to A2A Parts.
+
+    AssistantMessage has a .content list with TextBlock and ToolUseBlock items.
+    Returns Parts for streaming to the dashboard, or None if nothing useful.
+    """
+    content = getattr(message, "content", None)
+    if not content:
+        return None
+
+    parts: list[Part] = []
+
+    for block in content:
+        block_type = getattr(block, "type", None)
+
+        if block_type == "tool_use":
+            # Tool invocation — emit as a DataPart with function_call metadata
+            tool_name = getattr(block, "name", "unknown_tool")
+            tool_input = getattr(block, "input", {})
+            tool_id = getattr(block, "id", "")
+
+            data_part = DataPart(
+                data={
+                    "id": tool_id,
+                    "name": tool_name,
+                    "args": tool_input,
+                },
+                metadata={
+                    get_kagent_metadata_key(A2A_DATA_PART_METADATA_TYPE_KEY): A2A_DATA_PART_METADATA_TYPE_FUNCTION_CALL,
+                },
+            )
+            parts.append(Part(data_part))
+
+        elif block_type == "text" or (hasattr(block, "text") and isinstance(getattr(block, "text", None), str)):
+            text = getattr(block, "text", "")
+            if text:
+                parts.append(Part(TextPart(text=text)))
+
+    return parts if parts else None
+
+
+def convert_tool_result_message(message) -> list[Part] | None:
+    """
+    Convert a tool result message to A2A Parts.
+
+    In the Claude Agent SDK, tool results appear as content blocks with
+    type="tool_result" containing the output.
+    """
+    content = getattr(message, "content", None)
+    if not content:
+        return None
+
+    parts: list[Part] = []
+
+    for block in content:
+        block_type = getattr(block, "type", None)
+
+        if block_type == "tool_result":
+            tool_use_id = getattr(block, "tool_use_id", "")
+            tool_name = getattr(block, "name", None) or "tool_result"
+            result_content = getattr(block, "content", "")
+
+            # Result content can be a string or a list of content blocks
+            if isinstance(result_content, list):
+                text_parts = []
+                for sub in result_content:
+                    if hasattr(sub, "text"):
+                        text_parts.append(sub.text)
+                result_text = "\n".join(text_parts)
+            else:
+                result_text = str(result_content) if result_content else ""
+
+            # Truncate very long results for the dashboard
+            display_text = result_text[:2000] + "..." if len(result_text) > 2000 else result_text
+
+            data_part = DataPart(
+                data={
+                    "id": tool_use_id,
+                    "name": tool_name,
+                    "response": {"result": display_text},
+                },
+                metadata={
+                    get_kagent_metadata_key(A2A_DATA_PART_METADATA_TYPE_KEY): A2A_DATA_PART_METADATA_TYPE_FUNCTION_RESPONSE,
+                },
+            )
+            parts.append(Part(data_part))
+
+    return parts if parts else None
+
+
+def classify_sdk_message(message) -> str:
+    """
+    Classify a Claude Agent SDK message by type.
+
+    Returns one of: "system", "assistant", "user", "result", "unknown"
+    """
+    type_name = type(message).__name__
+
+    if type_name == "SystemMessage":
+        return "system"
+    elif type_name == "AssistantMessage":
+        return "assistant"
+    elif type_name == "UserMessage":
+        return "user"
+    elif type_name == "ResultMessage":
+        return "result"
+    else:
+        return "unknown"
+
+
+def convert_message_to_parts(message) -> list[Part] | None:
+    """
+    Convert any Claude Agent SDK message to A2A Parts for streaming.
+
+    Returns None if the message shouldn't be streamed (e.g., system init,
+    final result which is handled separately).
+    """
+    msg_type = classify_sdk_message(message)
+
+    if msg_type == "assistant":
+        return convert_assistant_message(message)
+    elif msg_type == "user":
+        # User messages in the SDK are typically tool results
+        return convert_tool_result_message(message)
+    elif msg_type == "system":
+        # System messages (init, etc.) — don't stream
+        return None
+    elif msg_type == "result":
+        # Final result — handled by the main executor flow
+        return None
+    else:
+        return None
+
+
+def make_message_id(message, index: int) -> str:
+    """Generate a deterministic message ID for deduplication."""
+    # Use message type + index for a stable ID
+    type_name = type(message).__name__
+    content_hash = hashlib.md5(
+        f"{type_name}:{index}".encode(), usedforsecurity=False
+    ).hexdigest()[:12]
+    return f"msg-{content_hash}"
+
+
+class StreamingEventEmitter:
+    """
+    Manages streaming of intermediate events to the A2A event queue.
+
+    Handles deduplication (won't re-emit the same message) and provides
+    a clean interface for the executor to stream events.
+    """
+
+    def __init__(self, task_id: str, context_id: str):
+        self.task_id = task_id
+        self.context_id = context_id
+        self._sent_ids: set[str] = set()
+
+    def should_emit(self, message_id: str) -> bool:
+        """Check if this message has already been emitted."""
+        if message_id in self._sent_ids:
+            return False
+        self._sent_ids.add(message_id)
+        return True
+
+    def build_streaming_event(
+        self,
+        parts: list[Part],
+        message_id: str,
+        metadata: dict[str, Any] | None = None,
+    ) -> TaskStatusUpdateEvent:
+        """Build a TaskStatusUpdateEvent for streaming intermediate progress."""
+        return TaskStatusUpdateEvent(
+            task_id=self.task_id,
+            status=TaskStatus(
+                state=TaskState.working,
+                timestamp=datetime.now(timezone.utc).isoformat(),
+                message=Message(
+                    message_id=message_id,
+                    role=Role.agent,
+                    parts=parts,
+                ),
+            ),
+            context_id=self.context_id,
+            final=False,
+            metadata=metadata,
+        )

kagent/claude/_error_mappings.py

@@ -0,0 +1,186 @@
+"""Error classification and user-friendly error messages for Claude Agent SDK errors."""
+
+import asyncio
+import logging
+from dataclasses import dataclass
+
+logger = logging.getLogger(__name__)
+
+# Claude Agent SDK specific error patterns
+_ANTHROPIC_RATE_LIMIT_PATTERNS = (
+    "rate_limit",
+    "429",
+    "too many requests",
+    "overloaded",
+)
+
+_ANTHROPIC_AUTH_PATTERNS = (
+    "authentication",
+    "unauthorized",
+    "invalid api key",
+    "401",
+    "invalid x-api-key",
+)
+
+_ANTHROPIC_CONTEXT_PATTERNS = (
+    "context window",
+    "too many tokens",
+    "maximum context length",
+    "prompt is too long",
+)
+
+_NETWORK_PATTERNS = (
+    "connection",
+    "timeout",
+    "dns",
+    "ssl",
+    "certificate",
+    "network",
+)
+
+_PERMISSION_PATTERNS = (
+    "permission denied",
+    "not allowed",
+    "forbidden",
+    "403",
+)
+
+_CLI_NOT_FOUND_PATTERNS = (
+    "cli not found",
+    "command not found",
+    "no such file or directory",
+    "claude: not found",
+)
+
+
+@dataclass
+class ClassifiedError:
+    """A classified error with user-friendly message and structured metadata."""
+
+    error_type: str
+    user_message: str
+    detail: str
+    is_transient: bool = False
+
+
+def classify_error(exception: Exception) -> ClassifiedError:
+    """
+    Classify an exception into a user-friendly error with structured metadata.
+
+    Returns a ClassifiedError with:
+    - error_type: machine-readable category (e.g., "rate_limit", "auth", "timeout")
+    - user_message: what to show the user
+    - detail: raw exception info for debugging
+    - is_transient: whether this error might succeed on retry
+    """
+    error_str = str(exception).lower()
+    error_class = type(exception).__name__
+    raw_detail = f"{error_class}: {exception}"
+
+    # Rate limiting
+    if any(p in error_str for p in _ANTHROPIC_RATE_LIMIT_PATTERNS):
+        return ClassifiedError(
+            error_type="rate_limit",
+            user_message="Claude is currently rate-limited. The request will be retried automatically.",
+            detail=raw_detail,
+            is_transient=True,
+        )
+
+    # Authentication errors
+    if any(p in error_str for p in _ANTHROPIC_AUTH_PATTERNS):
+        return ClassifiedError(
+            error_type="auth",
+            user_message="Authentication failed. Please verify the Anthropic API key is valid.",
+            detail=raw_detail,
+            is_transient=False,
+        )
+
+    # Context window exceeded
+    if any(p in error_str for p in _ANTHROPIC_CONTEXT_PATTERNS):
+        return ClassifiedError(
+            error_type="context_overflow",
+            user_message="The conversation exceeded Claude's context window. Please start a new conversation.",
+            detail=raw_detail,
+            is_transient=False,
+        )
+
+    # Network / connectivity
+    if any(p in error_str for p in _NETWORK_PATTERNS):
+        return ClassifiedError(
+            error_type="network",
+            user_message="A network error occurred while communicating with Claude. This may be transient.",
+            detail=raw_detail,
+            is_transient=True,
+        )
+
+    # Permission denied (tool execution)
+    if any(p in error_str for p in _PERMISSION_PATTERNS):
+        return ClassifiedError(
+            error_type="permission",
+            user_message="A tool execution was denied due to insufficient permissions.",
+            detail=raw_detail,
+            is_transient=False,
+        )
+
+    # CLI not found
+    if any(p in error_str for p in _CLI_NOT_FOUND_PATTERNS):
+        return ClassifiedError(
+            error_type="cli_not_found",
+            user_message="The Claude Agent SDK CLI binary was not found. Ensure claude-agent-sdk is installed correctly.",
+            detail=raw_detail,
+            is_transient=False,
+        )
+
+    # Timeout (asyncio)
+    if isinstance(exception, (TimeoutError, asyncio.TimeoutError)):
+        return ClassifiedError(
+            error_type="timeout",
+            user_message="The Claude query timed out. The task may be too complex or Claude may be slow to respond.",
+            detail=raw_detail,
+            is_transient=True,
+        )
+
+    # Cancellation
+    if isinstance(exception, asyncio.CancelledError):
+        return ClassifiedError(
+            error_type="cancelled",
+            user_message="The task was cancelled.",
+            detail=raw_detail,
+            is_transient=False,
+        )
+
+    # Process error (CLI exited non-zero)
+    if "exit code" in error_str or "process" in error_str:
+        return ClassifiedError(
+            error_type="process_error",
+            user_message="The Claude process exited unexpectedly. This may indicate a configuration issue.",
+            detail=raw_detail,
+            is_transient=True,
+        )
+
+    # JSON decode error (malformed response from CLI)
+    if "json" in error_str and ("decode" in error_str or "parse" in error_str):
+        return ClassifiedError(
+            error_type="parse_error",
+            user_message="Failed to parse Claude's response. This is usually a transient issue.",
+            detail=raw_detail,
+            is_transient=True,
+        )
+
+    # Unknown / generic
+    return ClassifiedError(
+        error_type="unknown",
+        user_message=f"An unexpected error occurred: {error_class}",
+        detail=raw_detail,
+        is_transient=False,
+    )
+
+
+def get_error_metadata(classified: ClassifiedError) -> dict:
+    """Build structured error metadata for A2A event metadata."""
+    return {
+        "kagent.claude.error_type": classified.error_type,
+        "kagent.claude.error_detail": classified.detail,
+        "kagent.claude.error_transient": classified.is_transient,
+    }
+