solace-agent-mesh 1.11.2__py3-none-any.whl → 1.12.0__py3-none-any.whl

solace_agent_mesh/agent/agent_llm.txt

@@ -1,369 +0,0 @@
-# DEVELOPER GUIDE for agent directory
-
-## Quick Summary
-The `agent` directory provides a comprehensive framework for hosting Google ADK (Agent Development Kit) agents within the Solace AI Connector ecosystem. It bridges ADK agents with the A2A (Agent-to-Agent) protocol over Solace messaging, enabling distributed agent communication, task delegation, and rich tool functionality.
-
-The architecture is modular, consisting of several key components:
-- **`sac/` (Solace AI Connector):** The main entry point, providing the `SamAgentApp` and `SamAgentComponent` to host the agent and manage its lifecycle and communication over the Solace event mesh.
-- **`adk/` (Agent Development Kit):** The core integration layer with Google's ADK. It defines the custom `AppLlmAgent`, manages asynchronous task execution, and provides a rich set of callbacks to augment agent behavior.
-- **`tools/`:** A comprehensive and extensible library of tools available to the agent, covering data analysis, artifact management, web requests, multimedia processing, and inter-agent communication.
-- **`protocol/`:** The underlying implementation of the A2A (Agent-to-Agent) communication protocol, handling message routing and event processing.
-- **`utils/`:** A collection of helper modules for common tasks like artifact management, configuration parsing, and context handling.
-- **`testing/`:** Utilities to aid in debugging and testing custom agent implementations.
-- **`proxies/`:** Framework for creating proxy applications that enable communication with downstream agents using various protocols.
-
-These components work together to create a robust environment where an ADK agent can be configured with specific instructions and tools, communicate with other agents, and execute complex tasks in a distributed, event-driven manner.
-
-## Files and Subdirectories Overview
-- **Direct files:**
-  - `__init__.py`: Standard Python package initializer that marks the `agent` directory as a Python package
-  - `agent_llm.txt`: Documentation file containing comprehensive developer guide content
-  - `agent_llm_detail.txt`: Concatenated documentation file from all subdirectories
-- **Subdirectories:**
-  - `adk/`: Provides the core integration layer with Google's ADK, including custom agents, services, and callbacks
-  - `protocol/`: Implements the A2A protocol event handlers for message routing and agent communication
-  - `proxies/`: Framework for creating proxy applications that bridge different agent protocols
-  - `sac/`: Contains the Solace AI Connector app and component implementations for hosting ADK agents
-  - `testing/`: Provides utilities for testing the A2A framework and debugging agent behavior
-  - `tools/`: A comprehensive, registry-based tool library for AI agents
-  - `utils/`: Contains helper utilities for configuration, context handling, and artifact management
-
-## Developer API Reference
-
-### Direct Files
-
-#### __init__.py
-**Purpose:** Standard Python package initializer. It allows the `agent` directory to be treated as a package.
-**Import:** `import solace_agent_mesh.agent`
-
-**Classes/Functions/Constants:** [None - empty file]
-
-#### agent_llm.txt
-**Purpose:** Documentation file containing comprehensive developer guide content
-**Import:** Not applicable - this is a documentation file, not a code module
-
-**Classes/Functions/Constants:** [None - documentation file]
-
-#### agent_llm_detail.txt
-**Purpose:** Concatenated documentation file from all subdirectories
-**Import:** Not applicable - this is a documentation file, not a code module
-
-**Classes/Functions/Constants:** [None - documentation file]
-
-### Subdirectory APIs
-
-#### adk/
-**Purpose:** Provides the core integration layer between the Solace AI Connector and Google's ADK
-**Key Exports:** `AppLlmAgent`, `initialize_adk_agent`, `initialize_adk_runner`, `load_adk_tools`, `FilesystemArtifactService`, `S3ArtifactService`, `LiteLlm`
-**Import Examples:**
-```python
-from solace_agent_mesh.agent.adk.setup import load_adk_tools, initialize_adk_agent, initialize_adk_runner
-from solace_agent_mesh.agent.adk.app_llm_agent import AppLlmAgent
-from solace_agent_mesh.agent.adk.artifacts.filesystem_artifact_service import FilesystemArtifactService
-from solace_agent_mesh.agent.adk.artifacts.s3_artifact_service import S3ArtifactService
-from solace_agent_mesh.agent.adk.models.lite_llm import LiteLlm
-from solace_agent_mesh.agent.adk.services import initialize_session_service, initialize_artifact_service
-```
-
-#### protocol/
-**Purpose:** Implements the core logic for Agent-to-Agent (A2A) communication protocol
-**Key Exports:** `process_event`, `handle_a2a_request`, `handle_agent_card_message`, `publish_agent_card`
-**Import Examples:**
-```python
-from solace_agent_mesh.agent.protocol.event_handlers import process_event, publish_agent_card
-```
-
-#### proxies/
-**Purpose:** Framework for creating proxy applications that enable communication with downstream agents using various protocols
-**Key Exports:** `BaseProxyApp`, `BaseProxyComponent`, `A2AProxyApp`, `A2AProxyComponent`, `OAuth2TokenCache`
-**Import Examples:**
-```python
-from solace_agent_mesh.agent.proxies.base.app import BaseProxyApp
-from solace_agent_mesh.agent.proxies.base.component import BaseProxyComponent
-from solace_agent_mesh.agent.proxies.a2a.app import A2AProxyApp
-from solace_agent_mesh.agent.proxies.a2a.component import A2AProxyComponent
-from solace_agent_mesh.agent.proxies.a2a.oauth_token_cache import OAuth2TokenCache
-```
-
-#### sac/
-**Purpose:** Provides the Solace AI Connector app and component implementations for hosting ADK agents
-**Key Exports:** `SamAgentApp`, `SamAgentComponent`, `TaskExecutionContext`
-**Import Examples:**
-```python
-from solace_agent_mesh.agent.sac.app import SamAgentApp
-from solace_agent_mesh.agent.sac.component import SamAgentComponent
-from solace_agent_mesh.agent.sac.task_execution_context import TaskExecutionContext
-```
-
-#### testing/
-**Purpose:** Provides utilities for testing the A2A framework and debugging agent behavior
-**Key Exports:** `pretty_print_event_history`
-**Import Examples:**
-```python
-from solace_agent_mesh.agent.testing.debug_utils import pretty_print_event_history
-```
-
-#### tools/
-**Purpose:** A comprehensive, registry-based tool library for AI agents
-**Key Exports:** `tool_registry`, `BuiltinTool`, `PeerAgentTool`, and various tool functions
-**Import Examples:**
-```python
-from solace_agent_mesh.agent.tools.registry import tool_registry
-from solace_agent_mesh.agent.tools.peer_agent_tool import PeerAgentTool
-from solace_agent_mesh.agent.tools.audio_tools import text_to_speech
-from solace_agent_mesh.agent.tools.builtin_artifact_tools import list_artifacts, load_artifact
-from solace_agent_mesh.agent.tools.image_tools import create_image_from_description
-```
-
-#### utils/
-**Purpose:** Contains helper utilities for configuration, context handling, and artifact management
-**Key Exports:** `save_artifact_with_metadata`, `load_artifact_content_or_metadata`, `resolve_instruction_provider`
-**Import Examples:**
-```python
-from solace_agent_mesh.agent.utils.artifact_helpers import save_artifact_with_metadata, load_artifact_content_or_metadata
-from solace_agent_mesh.agent.utils.config_parser import resolve_instruction_provider
-from solace_agent_mesh.agent.utils.context_helpers import get_session_from_callback_context
-```
-
-## Complete Usage Guide
-
-### 1. Basic Agent Setup and Configuration
-
-```python
-# Import the main SAC components
-from solace_agent_mesh.agent.sac.app import SamAgentApp
-from solace_agent_mesh.agent.sac.component import SamAgentComponent
-
-# The agent is typically configured via YAML and instantiated by the SAC framework
-# Example agent-config.yaml:
-"""
-app:
-  class_name: solace_agent_mesh.agent.sac.app.SamAgentApp
-  app_config:
-    namespace: "my-org/production"
-    agent_name: "customer-support-agent"
-    model: "gemini-1.5-pro-latest"
-    tools:
-      - tool_type: "builtin"
-        tool_name: "text_to_speech"
-      - tool_type: "builtin"
-        tool_name: "list_artifacts"
-    agent_card:
-      description: "An agent that can answer questions about customer accounts."
-    session_service:
-      type: "memory"
-    artifact_service:
-      type: "filesystem"
-      base_path: "/tmp/artifacts"
-"""
-```
-
-### 2. Working with ADK Components
-
-```python
-from solace_agent_mesh.agent.adk.setup import load_adk_tools, initialize_adk_agent, initialize_adk_runner
-from solace_agent_mesh.agent.adk.services import initialize_session_service, initialize_artifact_service
-from solace_agent_mesh.agent.adk.models.lite_llm import LiteLlm
-
-async def setup_adk_agent(component):
-    # Initialize services
-    session_service = initialize_session_service(component)
-    artifact_service = initialize_artifact_service(component)
-    
-    # Load tools
-    loaded_tools, builtin_tools = await load_adk_tools(component)
-    
-    # Initialize agent with LLM
-    agent = initialize_adk_agent(component, loaded_tools, builtin_tools)
-    
-    # Initialize runner
-    runner = initialize_adk_runner(component)
-    
-    return agent, runner
-```
-
-### 3. Custom Tool Development
-
-```python
-from solace_agent_mesh.agent.tools.registry import tool_registry
-from solace_agent_mesh.agent.tools.tool_definition import BuiltinTool
-from google.adk.tools import ToolContext
-
-# Define a custom tool function
-async def my_custom_tool(
-    query: str,
-    tool_context: ToolContext = None,
-    tool_config: dict = None
-) -> dict:
-    """A custom tool that processes queries."""
-    # Access the host component
-    host_component = tool_context._invocation_context.agent.host_component
-    
-    # Use agent state
-    db_connection = host_component.get_agent_specific_state('db_connection')
-    
-    # Process the query
-    result = await process_query(query, db_connection)
-    
-    return {"result": result, "status": "success"}
-
-# Register the tool
-custom_tool = BuiltinTool(
-    name="my_custom_tool",
-    description="Processes custom queries",
-    function=my_custom_tool,
-    category="custom"
-)
-tool_registry.register(custom_tool)
-```
-
-### 4. Artifact Management
-
-```python
-from solace_agent_mesh.agent.utils.artifact_helpers import (
-    save_artifact_with_metadata,
-    load_artifact_content_or_metadata,
-    get_artifact_info_list
-)
-from datetime import datetime, timezone
-
-async def artifact_operations(component, artifact_service):
-    # Save an artifact with metadata
-    content = b"Hello, world!"
-    result = await save_artifact_with_metadata(
-        artifact_service=artifact_service,
-        app_name=component.get_config()["app_name"],
-        user_id="user123",
-        session_id="session456",
-        filename="greeting.txt",
-        content_bytes=content,
-        mime_type="text/plain",
-        metadata_dict={"source": "custom_tool", "description": "A greeting"},
-        timestamp=datetime.now(timezone.utc)
-    )
-    
-    # Load the artifact
-    loaded = await load_artifact_content_or_metadata(
-        artifact_service=artifact_service,
-        app_name=component.get_config()["app_name"],
-        user_id="user123",
-        session_id="session456",
-        filename="greeting.txt",
-        version="latest"
-    )
-    
-    # List all artifacts
-    artifacts = await get_artifact_info_list(
-        artifact_service=artifact_service,
-        app_name=component.get_config()["app_name"],
-        user_id="user123",
-        session_id="session456"
-    )
-    
-    return artifacts
-```
-
-### 5. Inter-Agent Communication
-
-```python
-from solace_agent_mesh.agent.tools.peer_agent_tool import PeerAgentTool
-
-# Create a peer agent tool (typically done automatically by the framework)
-peer_tool = PeerAgentTool("data_analyst_agent", host_component)
-
-# The LLM can then use this tool to delegate tasks:
-# "Please use the data_analyst_agent to analyze the sales data in report.csv"
-
-# The framework handles the A2A protocol communication automatically
-```
-
-### 6. Audio and Multimedia Tools
-
-```python
-from solace_agent_mesh.agent.tools.audio_tools import text_to_speech, multi_speaker_text_to_speech
-from solace_agent_mesh.agent.tools.image_tools import create_image_from_description, describe_image
-
-async def multimedia_example(tool_context):
-    # Generate speech from text
-    tts_result = await text_to_speech(
-        text="Welcome to our service!",
-        output_filename="welcome.mp3",
-        gender="female",
-        tone="friendly",
-        tool_context=tool_context
-    )
-    
-    # Create a multi-speaker conversation
-    conversation_result = await multi_speaker_text_to_speech(
-        conversation_text="Alice: Hello there!\nBob: Hi Alice, how are you?",
-        speaker_configs=[
-            {"name": "Alice", "gender": "female", "tone": "bright"},
-            {"name": "Bob", "gender": "male", "tone": "warm"}
-        ],
-        tool_context=tool_context
-    )
-    
-    # Generate an image
-    image_result = await create_image_from_description(
-        image_description="A futuristic cityscape at sunset",
-        output_filename="cityscape.png",
-        tool_context=tool_context
-    )
-    
-    return tts_result, conversation_result, image_result
-```
-
-### 7. Proxy Applications for External Agents
-
-```python
-from solace_agent_mesh.agent.proxies.a2a.app import A2AProxyApp
-
-# Configure proxy for external A2A-over-HTTPS agents
-proxy_config = {
-    "app_config": {
-        "namespace": "myorg/production",
-        "proxied_agents": [
-            {
-                "name": "external-agent",
-                "url": "https://external-agent.example.com",
-                "authentication": {
-                    "type": "oauth2_client_credentials",
-                    "token_url": "https://auth.example.com/oauth/token",
-                    "client_id": "my-client-id",
-                    "client_secret": "my-client-secret"
-                }
-            }
-        ],
-        "artifact_service": {
-            "type": "gcs",
-            "bucket_name": "my-artifacts-bucket"
-        }
-    }
-}
-
-# Create and run the proxy
-proxy_app = A2AProxyApp(proxy_config)
-# Proxy automatically handles discovery and request forwarding
-```
-
-### 8. Testing and Debugging
-
-```python
-from solace_agent_mesh.agent.testing.debug_utils import pretty_print_event_history
-from solace_agent_mesh.agent.adk.invocation_monitor import InvocationMonitor
-
-# Debug event history in tests
-def test_agent_behavior():
-    event_history = [
-        {"result": {"status": {"state": "EXECUTING"}}},
-        {"result": {"status": {"state": "COMPLETED"}}}
-    ]
-    
-    # Print formatted event history for debugging
-    pretty_print_event_history(event_history)
-
-# Monitor agent invocations
-monitor = InvocationMonitor()
-monitor.log_message_event("
-
-# content_hash: 044545e92d39d61fac8f9bf62598018a7cbee362201bc3a6f0ae74b299fa4374