agent-starter-pack 0.3.3__py3-none-any.whl → 0.21.0__py3-none-any.whl

agent_starter_pack/base_template/{{cookiecutter.agent_directory}}/app_utils/{% if cookiecutter.is_a2a and cookiecutter.agent_name == 'langgraph_base' %}converters{% else %}unused_converters{% endif %}/part_converter.py

@@ -0,0 +1,138 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Converters between A2A Parts and LangChain message content."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from a2a.types import FilePart, FileWithBytes, FileWithUri, Part, TextPart
+
+logger = logging.getLogger(__name__)
+
+
+LangChainContent = str | list[str | dict[str, Any]]
+LangChainContentDict = dict[str, Any]
+
+
+def convert_a2a_part_to_langchain_content(part: Part) -> LangChainContentDict | str:
+    """Convert an A2A Part to LangChain message content format."""
+
+    root = part.root
+
+    if isinstance(root, TextPart):
+        return {"type": "text", "text": root.text}
+
+    elif isinstance(root, FilePart):
+        file_data = root.file
+        mime_type = file_data.mime_type if hasattr(file_data, "mime_type") else None
+
+        # Determine media type from mime_type
+        media_type = "image"  # default
+        if mime_type:
+            if mime_type.startswith("audio/"):
+                media_type = "audio"
+            elif mime_type.startswith("video/"):
+                media_type = "video"
+
+        if isinstance(file_data, FileWithUri):
+            return {"type": media_type, "url": file_data.uri}
+        else:
+            # Base64 data should already be encoded
+            return {
+                "type": media_type,
+                "base64": file_data.bytes,
+                "mime_type": mime_type or "application/octet-stream",
+            }
+
+    else:
+        import json
+
+        data_str = json.dumps(root.data, indent=2)
+        return {"type": "text", "text": f"[Structured Data]\n{data_str}"}
+
+
+def convert_langchain_content_to_a2a_part(content: Any) -> Part:
+    """Convert LangChain message content to an A2A Part."""
+
+    if isinstance(content, str):
+        return Part(root=TextPart(text=content))
+
+    if isinstance(content, dict):
+        content_type = content.get("type")
+
+        if content_type == "text":
+            text = content.get("text", "")
+            return Part(root=TextPart(text=text))
+
+        elif content_type in ("image", "audio", "video"):
+            # Handle URL-based media
+            if "url" in content:
+                return Part(root=FilePart(file=FileWithUri(uri=content["url"])))
+
+            # Handle base64-encoded media
+            elif "base64" in content:
+                mime_type = content.get("mime_type")
+                return Part(
+                    root=FilePart(
+                        file=FileWithBytes(bytes=content["base64"], mime_type=mime_type)
+                    )
+                )
+
+            # Handle file_id-based media
+            elif "file_id" in content:
+                return Part(
+                    root=FilePart(file=FileWithUri(uri=f"file://{content['file_id']}"))
+                )
+
+        else:
+            import json
+
+            text = json.dumps(content)
+            logger.warning(f"Unknown content type '{content_type}', converting to text")
+            return Part(root=TextPart(text=text))
+
+    logger.warning(f"Unknown content type: {type(content)}, converting to text")
+    return Part(root=TextPart(text=str(content)))
+
+
+def convert_a2a_parts_to_langchain_content(parts: list[Part]) -> LangChainContent:
+    """Convert a list of A2A Parts to LangChain message content."""
+
+    if not parts:
+        return ""
+
+    converted: list[str | dict[str, Any]] = []
+    for part in parts:
+        result = convert_a2a_part_to_langchain_content(part)
+        converted.append(result)
+
+    if len(converted) == 1 and isinstance(converted[0], str):
+        return converted[0]
+
+    return converted
+
+
+def convert_langchain_content_to_a2a_parts(content: LangChainContent) -> list[Part]:
+    """Convert LangChain message content to a list of A2A Parts."""
+
+    if isinstance(content, str):
+        return [Part(root=TextPart(text=content))]
+
+    result: list[Part] = []
+    for item in content:
+        result.append(convert_langchain_content_to_a2a_part(item))
+    return result

agent_starter_pack/base_template/{{cookiecutter.agent_directory}}/app_utils/{% if cookiecutter.is_a2a and cookiecutter.agent_name == 'langgraph_base' %}executor{% else %}unused_executor{% endif %}/__init__.py

@@ -0,0 +1,13 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.

agent_starter_pack/base_template/{{cookiecutter.agent_directory}}/app_utils/{% if cookiecutter.is_a2a and cookiecutter.agent_name == 'langgraph_base' %}executor{% else %}unused_executor{% endif %}/a2a_agent_executor.py

@@ -0,0 +1,265 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+
+import logging
+import uuid
+from datetime import datetime, timezone
+
+from a2a.server.agent_execution import AgentExecutor, RequestContext
+from a2a.server.events import EventQueue
+from a2a.types import (
+    Artifact,
+    Message,
+    Part,
+    Role,
+    TaskArtifactUpdateEvent,
+    TaskState,
+    TaskStatus,
+    TaskStatusUpdateEvent,
+    TextPart,
+    UnsupportedOperationError,
+)
+from a2a.utils.errors import ServerError
+from langchain_core.messages import AIMessage, HumanMessage, ToolMessage
+from langgraph.graph.state import CompiledStateGraph
+from pydantic import BaseModel
+from typing_extensions import override
+
+from ..converters import (
+    convert_a2a_parts_to_langchain_content,
+    convert_langchain_content_to_a2a_parts,
+)
+from .task_result_aggregator import LangGraphTaskResultAggregator
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+
+class LangGraphAgentExecutorConfig(BaseModel):
+    """Configuration for the LangGraphAgentExecutor."""
+
+    enable_streaming: bool = True
+
+
+class LangGraphAgentExecutor(AgentExecutor):
+    """An AgentExecutor that runs a LangGraph agent against an A2A request and
+    publishes updates to an event queue."""
+
+    def __init__(
+        self,
+        *,
+        graph: CompiledStateGraph,
+        config: LangGraphAgentExecutorConfig | None = None,
+    ):
+        super().__init__()
+        self._graph = graph
+        self._config = config or LangGraphAgentExecutorConfig()
+
+    @override
+    async def cancel(self, context: RequestContext, event_queue: EventQueue) -> None:
+        """Cancel the execution."""
+        # TODO: Implement proper cancellation logic if needed
+        raise ServerError(error=UnsupportedOperationError())
+
+    @override
+    async def execute(
+        self,
+        context: RequestContext,
+        event_queue: EventQueue,
+    ) -> None:
+        """Executes an A2A request and publishes updates to the event queue."""
+
+        if not context.message:
+            raise ValueError("A2A request must have a message")
+
+        if not context.task_id:
+            raise ValueError("task_id is required")
+        if not context.context_id:
+            raise ValueError("context_id is required")
+
+        task_id = context.task_id
+        context_id = context.context_id
+
+        if not context.current_task:
+            await event_queue.enqueue_event(
+                TaskStatusUpdateEvent(
+                    task_id=task_id,
+                    status=TaskStatus(
+                        state=TaskState.submitted,
+                        message=context.message,
+                        timestamp=datetime.now(timezone.utc).isoformat(),
+                    ),
+                    context_id=context_id,
+                    final=False,
+                )
+            )
+
+        try:
+            await self._handle_request(context, event_queue)
+        except Exception as e:
+            logger.error("Error handling A2A request: %s", e, exc_info=True)
+            try:
+                await event_queue.enqueue_event(
+                    TaskStatusUpdateEvent(
+                        task_id=task_id,
+                        status=TaskStatus(
+                            state=TaskState.failed,
+                            timestamp=datetime.now(timezone.utc).isoformat(),
+                            message=Message(
+                                message_id=str(uuid.uuid4()),
+                                role=Role.agent,
+                                parts=[Part(root=TextPart(text=str(e)))],
+                            ),
+                        ),
+                        context_id=context_id,
+                        final=True,
+                    )
+                )
+            except Exception as enqueue_error:
+                logger.error(
+                    "Failed to publish failure event: %s", enqueue_error, exc_info=True
+                )
+
+    async def _handle_request(
+        self,
+        context: RequestContext,
+        event_queue: EventQueue,
+    ) -> None:
+        """Handle the A2A request and publish events."""
+
+        graph = self._graph
+
+        if not context.task_id:
+            raise ValueError("task_id is required")
+        if not context.context_id:
+            raise ValueError("context_id is required")
+
+        task_id = context.task_id
+        context_id = context.context_id
+
+        await event_queue.enqueue_event(
+            TaskStatusUpdateEvent(
+                task_id=task_id,
+                status=TaskStatus(
+                    state=TaskState.working,
+                    timestamp=datetime.now(timezone.utc).isoformat(),
+                ),
+                context_id=context_id,
+                final=False,
+            )
+        )
+
+        # Convert A2A message parts to LangChain content
+        message_content = (
+            convert_a2a_parts_to_langchain_content(context.message.parts)
+            if context.message
+            else ""
+        )
+        messages = [HumanMessage(content=message_content)]
+        input_dict = {"messages": messages}
+
+        task_result_aggregator = LangGraphTaskResultAggregator()
+
+        try:
+            if self._config.enable_streaming:
+                async for chunk in graph.astream(input_dict, stream_mode="messages"):
+                    if isinstance(chunk, tuple) and len(chunk) > 0:
+                        message = chunk[0]
+
+                        # Process AIMessage chunks
+                        if isinstance(message, AIMessage) and message.content:
+                            task_result_aggregator.process_message(message)
+
+                            parts = convert_langchain_content_to_a2a_parts(
+                                message.content
+                            )
+                            await event_queue.enqueue_event(
+                                TaskStatusUpdateEvent(
+                                    task_id=task_id,
+                                    status=TaskStatus(
+                                        state=TaskState.working,
+                                        timestamp=datetime.now(
+                                            timezone.utc
+                                        ).isoformat(),
+                                        message=Message(
+                                            message_id=str(uuid.uuid4()),
+                                            role=Role.agent,
+                                            parts=parts,
+                                        ),
+                                    ),
+                                    context_id=context_id,
+                                    final=False,
+                                )
+                            )
+
+                        # Process ToolMessage chunks (for multimodal content)
+                        elif isinstance(message, ToolMessage):
+                            task_result_aggregator.process_message(message)
+            else:
+                result = await graph.ainvoke(input_dict)
+                if "messages" in result:
+                    for msg in result["messages"]:
+                        if isinstance(msg, (AIMessage, ToolMessage)) and msg.content:
+                            task_result_aggregator.process_message(msg)
+            if (
+                task_result_aggregator.task_state == TaskState.working
+                and task_result_aggregator.task_status_message is not None
+                and task_result_aggregator.task_status_message.parts
+            ):
+                # Publish the artifact update event as the final result
+                await event_queue.enqueue_event(
+                    TaskArtifactUpdateEvent(
+                        task_id=task_id,
+                        last_chunk=True,
+                        context_id=context_id,
+                        artifact=Artifact(
+                            artifact_id=str(uuid.uuid4()),
+                            parts=task_result_aggregator.get_final_parts(),
+                        ),
+                    )
+                )
+                # Publish the final status update event
+                await event_queue.enqueue_event(
+                    TaskStatusUpdateEvent(
+                        task_id=task_id,
+                        status=TaskStatus(
+                            state=TaskState.completed,
+                            timestamp=datetime.now(timezone.utc).isoformat(),
+                        ),
+                        context_id=context_id,
+                        final=True,
+                    )
+                )
+            else:
+                # Publish final status with current task_state and message
+                await event_queue.enqueue_event(
+                    TaskStatusUpdateEvent(
+                        task_id=task_id,
+                        status=TaskStatus(
+                            state=task_result_aggregator.task_state,
+                            timestamp=datetime.now(timezone.utc).isoformat(),
+                            message=task_result_aggregator.task_status_message,
+                        ),
+                        context_id=context_id,
+                        final=True,
+                    )
+                )
+
+        except Exception as e:
+            logger.error("Error during graph execution: %s", e, exc_info=True)
+            # Update task state to failed using aggregator
+            task_result_aggregator.set_failed(str(e))
+            raise

agent_starter_pack/base_template/{{cookiecutter.agent_directory}}/app_utils/{% if cookiecutter.is_a2a and cookiecutter.agent_name == 'langgraph_base' %}executor{% else %}unused_executor{% endif %}/task_result_aggregator.py

@@ -0,0 +1,152 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+
+from a2a.types import (
+    FilePart,
+    FileWithBytes,
+    FileWithUri,
+    Message,
+    Part,
+    Role,
+    TaskState,
+    TextPart,
+)
+from langchain_core.messages import AIMessage, ToolMessage
+
+
+class LangGraphTaskResultAggregator:
+    """Aggregates streaming LangGraph messages into a final consolidated result."""
+
+    def __init__(self) -> None:
+        self._task_state = TaskState.working
+        self._accumulated_content = ""  # Accumulate text content across chunks
+        self._task_status_message: Message | None = None
+        self._media_parts: list[Part] = []  # Track media parts from tool responses
+
+    def process_message(self, message: AIMessage | ToolMessage) -> None:
+        """Process a streaming message chunk from LangGraph."""
+
+        # Handle tool responses to extract media
+        if isinstance(message, ToolMessage):
+            self._extract_media_from_tool_response(message)
+            return
+
+        if not message.content:
+            return
+
+        if isinstance(message.content, str):
+            self._accumulated_content += message.content
+
+        elif isinstance(message.content, list):
+            for item in message.content:
+                if isinstance(item, str):
+                    self._accumulated_content += item
+                elif isinstance(item, dict) and item.get("type") == "text":
+                    self._accumulated_content += item.get("text", "")
+
+        # Update the task status message with current accumulated content
+        if self._accumulated_content or self._media_parts:
+            parts = []
+            if self._accumulated_content:
+                parts.append(Part(root=TextPart(text=self._accumulated_content)))
+            parts.extend(self._media_parts)
+
+            self._task_status_message = Message(
+                message_id="aggregated",
+                role=Role.agent,
+                parts=parts,
+            )
+
+    def _extract_media_from_tool_response(self, message: ToolMessage) -> None:
+        """Extract media parts from a ToolMessage."""
+
+        if not message.content:
+            return
+
+        if isinstance(message.content, list):
+            for item in message.content:
+                if isinstance(item, dict):
+                    content_type = item.get("type")
+                    if content_type == "image":
+                        self._media_parts.append(
+                            self._convert_media_to_a2a_part(item, "image")
+                        )
+                    elif content_type == "audio":
+                        self._media_parts.append(
+                            self._convert_media_to_a2a_part(item, "audio")
+                        )
+                    elif content_type == "video":
+                        self._media_parts.append(
+                            self._convert_media_to_a2a_part(item, "video")
+                        )
+
+    def _convert_media_to_a2a_part(
+        self, content: dict[str, str], media_type: str
+    ) -> Part:
+        """Convert a media content block to an A2A Part."""
+
+        mime_type = content.get("mime_type")
+
+        if "url" in content:
+            return Part(
+                root=FilePart(file=FileWithUri(uri=content["url"], mime_type=mime_type))
+            )
+        elif "base64" in content:
+            return Part(
+                root=FilePart(
+                    file=FileWithBytes(bytes=content["base64"], mime_type=mime_type)
+                )
+            )
+        elif "file_id" in content:
+            # For now, store file_id as a URI
+            return Part(
+                root=FilePart(
+                    file=FileWithUri(
+                        uri=f"file://{content['file_id']}", mime_type=mime_type
+                    )
+                )
+            )
+
+        # Fallback to empty text part
+        return Part(root=TextPart(text=f"[{media_type} content]"))
+
+    def get_final_parts(self) -> list[Part]:
+        """Get the final consolidated parts for the artifact."""
+
+        parts = []
+        if self._accumulated_content:
+            parts.append(Part(root=TextPart(text=self._accumulated_content)))
+        parts.extend(self._media_parts)
+        return parts if parts else []
+
+    @property
+    def task_state(self) -> TaskState:
+        """Get the current task state."""
+        return self._task_state
+
+    @property
+    def task_status_message(self) -> Message | None:
+        """Get the current task status message with accumulated content."""
+        return self._task_status_message
+
+    def set_failed(self, error_message: str) -> None:
+        """Set the task state to failed."""
+        self._task_state = TaskState.failed
+        self._task_status_message = Message(
+            message_id="error",
+            role=Role.agent,
+            parts=[Part(root=TextPart(text=error_message))],
+        )