aigency 0.0.1rc235167702__py3-none-any.whl → 0.1.0__py3-none-any.whl

aigency/agents/client.py

@@ -0,0 +1,78 @@
+"""Remote agent client module.
+
+This module provides client functionality for connecting to and communicating with
+remote agents in the A2A (Agent-to-Agent) ecosystem. It encapsulates the HTTP
+client setup and agent card management required for inter-agent communication.
+
+The AgentClient class serves as a wrapper around the A2A client factory and
+provides a simplified interface for sending messages to remote agents while
+handling connection management and protocol details.
+
+Example:
+    Creating and using an agent client:
+
+    >>> agent_card = AgentCard(name="remote_agent", url="http://localhost:8080")
+    >>> client = AgentClient(agent_card)
+    >>> response = await client.send_message(message_request)
+
+Attributes:
+    None: This module contains only class definitions.
+"""
+
+import httpx
+
+from a2a.client.client import ClientConfig
+from a2a.client.client_factory import ClientFactory
+from a2a.types import AgentCard, Message, SendMessageResponse
+
+
+class AgentClient:
+    """A class to hold the connections to the remote agents.
+
+    This class manages connections to remote agents using the A2A protocol.
+    It provides methods for retrieving agent information and sending messages
+    to remote agents.
+
+    Attributes:
+        _httpx_client (httpx.AsyncClient): The HTTP client used for asynchronous requests.
+        agent_card (AgentCard): The agent card containing metadata about the remote agent.
+    """
+
+    def __init__(self, agent_card: AgentCard):
+        """Initialize a connection to a remote agent.
+
+        Args:
+            agent_card (AgentCard): The agent card containing metadata about the remote agent.
+
+        Raises:
+            None
+
+        Returns:
+            None
+        """
+        self._httpx_client = httpx.AsyncClient(timeout=60)
+        self.card = agent_card
+
+        config = ClientConfig(httpx_client=self._httpx_client)
+        factory = ClientFactory(config=config)
+        self.agent_client = factory.create(agent_card)
+
+    def get_agent(self) -> AgentCard:
+        """Get the agent card for this remote agent connection.
+
+        Returns:
+            AgentCard: The agent card containing metadata about the remote agent.
+        """
+        return self.card
+
+    async def send_message(self, message_request: Message) -> SendMessageResponse:
+        """Send a message to the remote agent.
+
+        Args:
+            message_request (Message): The message request to send to the remote agent.
+
+        Returns:
+            SendMessageResponse: The response from the remote agent.
+        """
+        async for response in self.agent_client.send_message(message_request):
+            yield response

aigency/agents/communicator.py

@@ -0,0 +1,157 @@
+"""Agent-to-Agent communication module.
+
+This module provides the core communication infrastructure for agents to interact
+with each other using the A2A (Agent-to-Agent) protocol. It handles message
+creation, payload formatting, and remote agent connection management.
+
+The main component is the Communicator class which manages connections to remote
+agents and provides methods for delegating tasks and sending messages between
+agents in a distributed system.
+
+Example:
+    Basic usage for agent communication:
+
+    >>> connections = {"agent1": client1, "agent2": client2}
+    >>> communicator = Communicator(connections)
+    >>> task_result = await communicator.send_message("agent1", "task description", context)
+
+Attributes:
+    logger: Module-level logger instance for communication events.
+"""
+
+import uuid
+from typing import Any, Awaitable
+
+from a2a.types import Message, Task
+from google.adk.tools.tool_context import ToolContext
+
+from aigency.utils.logger import get_logger
+
+logger = get_logger()
+
+
+class Communicator:
+    """Base class for agent-to-agent communication.
+
+    This class manages connections to remote agents and provides methods for
+    sending messages and delegating tasks to them.
+
+    Attributes:
+        remote_agent_connections (dict[str, Any]): Dictionary mapping agent names
+            to their client connection objects.
+    """
+
+    def __init__(self, remote_agent_connections: dict[str, Any] | None = None):
+        """Initialize the communicator with remote agent connections.
+
+        Args:
+            remote_agent_connections (dict[str, Any] | None, optional): A dictionary
+                that maps agent names to their client connection objects.
+                Defaults to None.
+        """
+        self.remote_agent_connections: dict[str, Any] = remote_agent_connections or {}
+
+    async def send_message(
+        self, agent_name: str, task: str, tool_context: ToolContext
+    ) -> Awaitable[Task | None]:
+        """Delegate a task to a specific remote agent.
+
+        This method sends a message to a remote agent, requesting it to perform a
+        task. It handles message payload creation and communication.
+
+        Args:
+            agent_name (str): Name of the remote agent to send the task to.
+            task (str): Detailed description of the task for the remote agent.
+            tool_context (ToolContext): Context object containing state and other
+                information.
+
+        Returns:
+            Task | None: A Task object if communication is successful, or None
+                otherwise.
+
+        Raises:
+            ValueError: If the specified agent is not found in connections.
+        """
+        logger.info(
+            f"`send_message` started for agent: '{agent_name}' with task: '{task}'"
+        )
+        client = self.remote_agent_connections.get(agent_name)
+        if not client:
+            available_agents = list(self.remote_agent_connections.keys())
+            logger.error(
+                f"The LLM tried to call '{agent_name}', but it was not found. "
+                f"Available agents: {available_agents}"
+            )
+            raise ValueError(
+                f"Agent '{agent_name}' not found. Available agents: {available_agents}"
+            )
+
+        state = tool_context.state
+
+        contexts = state.setdefault("remote_agent_contexts", {})
+        agent_context = contexts.setdefault(
+            agent_name, {"context_id": str(uuid.uuid4())}
+        )
+        context_id = agent_context["context_id"]
+
+        task_id = state.get("task_id")
+        input_metadata = state.get("input_message_metadata", {})
+        message_id = input_metadata.get("message_id")
+
+        payload = self.create_send_message_payload(
+            text=task, task_id=task_id, context_id=context_id, message_id=message_id
+        )
+        logger.debug("`send_message` with the following payload: %s", payload)
+
+        send_response = None
+
+        async for resp in client.send_message(
+            message_request=Message(**payload["message"])
+        ):
+            send_response = resp
+
+        if isinstance(send_response, tuple):
+            send_response, _ = send_response
+
+        if not isinstance(send_response, Task):
+            logger.warning(
+                f"The response received from agent '{agent_name}' is not a Task object. "
+                f"Received type: {type(send_response)}"
+            )
+            return None
+
+        return send_response
+
+    @staticmethod
+    def create_send_message_payload(
+        text: str,
+        task_id: str | None = None,
+        context_id: str | None = None,
+        message_id: str | None = None,
+    ) -> dict[str, Any]:
+        """Create a message payload to send to a remote agent.
+
+        Args:
+            text (str): The text content of the message.
+            task_id (str | None, optional): Task ID to associate with the message.
+                Defaults to None.
+            context_id (str | None, optional): Context ID to associate with the
+                message. Defaults to None.
+            message_id (str | None, optional): Message ID. If None, a new one will
+                be generated. Defaults to None.
+
+        Returns:
+            dict[str, Any]: A dictionary containing the formatted message payload.
+        """
+        payload: dict[str, Any] = {
+            "message": {
+                "role": "user",
+                "parts": [{"type": "text", "text": text}],
+                "message_id": message_id or uuid.uuid4().hex,
+            },
+        }
+        if task_id:
+            payload["message"]["task_id"] = task_id
+        if context_id:
+            payload["message"]["context_id"] = context_id
+        return payload

aigency/agents/executor.py

@@ -1,4 +1,27 @@
-"""Agent executor module for A2A integration."""
+"""Agent executor module for A2A integration.
+
+This module provides the execution engine for agents within the A2A (Agent-to-Agent)
+protocol framework. It handles the lifecycle of agent tasks, session management,
+and integration with Google ADK runners for processing agent requests.
+
+The AgentA2AExecutor class manages the execution flow from task submission through
+completion, handling streaming responses, function calls, and error conditions
+while maintaining compatibility with the A2A protocol specifications.
+
+Example:
+    Creating and using an agent executor:
+
+    >>> runner = Runner(app_name="my_agent", agent=agent)
+    >>> executor = AgentA2AExecutor(runner, agent_card)
+    >>> await executor.execute(context, event_queue)
+
+Attributes:
+    logger: Module-level logger instance for execution events.
+    DEFAULT_USER_ID (str): Default user identifier for session management.
+
+Todo:
+    * Replace DEFAULT_USER_ID with proper user management system.
+"""
 
 from a2a.server.agent_execution import AgentExecutor
 from a2a.server.agent_execution.context import RequestContext
@@ -20,13 +43,24 @@ logger = get_logger()
 # TODO: This needs to be changed
 DEFAULT_USER_ID = "self"
 
+
 class AgentA2AExecutor(AgentExecutor):
-    """Agent executor for A2A integration with Google ADK runners."""
+    """Agent executor for A2A integration with Google ADK runners.
+
+    This class handles the execution of agent tasks within the A2A protocol,
+    managing sessions, processing requests, and handling task lifecycle.
+
+    Attributes:
+        _card (AgentCard): The agent card containing metadata about the agent.
+        _active_sessions (set[str]): Set of active session IDs for tracking.
+        runner (Runner): The Google ADK runner instance for executing agent logic.
+    """
 
     def __init__(self, runner: Runner, card: AgentCard):
         """Initialize the BaseAgentA2AExecutor.
 
         Args:
+            runner (Runner): The Google ADK runner instance.
             card (AgentCard): The agent card containing metadata about the agent.
         """
         self._card = card
@@ -65,6 +99,13 @@ class AgentA2AExecutor(AgentExecutor):
         session_id: str,
         task_updater: TaskUpdater,
     ) -> None:
+        """Process a request through the agent runner.
+
+        Args:
+            new_message (types.Content): The message content to process.
+            session_id (str): The session ID for this request.
+            task_updater (TaskUpdater): Task updater for reporting progress.
+        """
         session_obj = await self._upsert_session(session_id)
         session_id = session_obj.id
 
@@ -112,6 +153,12 @@ class AgentA2AExecutor(AgentExecutor):
         context: RequestContext,
         event_queue: EventQueue,
     ):
+        """Execute an agent task.
+
+        Args:
+            context (RequestContext): The request context containing task information.
+            event_queue (EventQueue): Event queue for task updates.
+        """
         # Run the agent until either complete or the task is suspended.
         updater = TaskUpdater(event_queue, context.task_id, context.context_id)
         # Immediately notify that the task is submitted.
@@ -131,6 +178,15 @@ class AgentA2AExecutor(AgentExecutor):
         logger.debug("[ADKAgentA2AExecutor] execute exiting")
 
     async def cancel(self, context: RequestContext, event_queue: EventQueue):
+        """Cancel an active agent task.
+
+        Args:
+            context (RequestContext): The request context for the task to cancel.
+            event_queue (EventQueue): Event queue for task updates.
+
+        Raises:
+            ServerError: Always raised as cancellation is not currently supported.
+        """
         session_id = context.context_id
         if session_id in self._active_sessions:
             logger.info("Cancellation requested for active session: %s", session_id)

aigency/agents/generator.py

@@ -1,8 +1,29 @@
-"""Agent generator module for creating A2A agents."""
+"""Agent generation and factory module.
 
-from typing import Any, Dict, List
+This module provides factory methods for creating A2A-compatible agents and their
+associated components. It handles the complete agent lifecycle from configuration
+parsing to executable agent creation, including remote agent connection management.
 
+The AgentA2AGenerator class uses static factory methods to create agents, agent cards,
+executors, and establish connections to remote agents. It integrates with various
+components like tools, models, and communication systems to produce fully functional
+agents ready for deployment in the A2A ecosystem.
+
+Example:
+    Creating a complete agent from configuration:
+
+    >>> config = AigencyConfig.from_yaml("agent_config.yaml")
+    >>> agent = AgentA2AGenerator.create_agent(config)
+    >>> agent_card = AgentA2AGenerator.build_agent_card(config)
+    >>> executor = AgentA2AGenerator.build_executor(agent, agent_card)
+
+Attributes:
+    logger: Module-level logger instance for generation events.
+"""
+
+import httpx
 from a2a.types import AgentCapabilities, AgentCard, AgentSkill
+from a2a.client import A2ACardResolver
 from google.adk.agents import Agent
 from google.adk.artifacts import InMemoryArtifactService
 from google.adk.memory.in_memory_memory_service import InMemoryMemoryService
@@ -10,20 +31,50 @@ from google.adk.runners import Runner
 from google.adk.sessions import InMemorySessionService
 
 from aigency.agents.executor import AgentA2AExecutor
+from aigency.agents.client import AgentClient
 from aigency.schemas.aigency_config import AigencyConfig
 from aigency.tools.generator import ToolGenerator
+from aigency.utils.utils import generate_url, safe_async_run
+from aigency.agents.communicator import Communicator
+from aigency.utils.logger import get_logger
+
+logger = get_logger()
 
 
 class AgentA2AGenerator:
-    """Generator for creating A2A agents and related components."""
+    """Generator for creating A2A-compatible agents and their components.
+
+    This class provides static methods to create agents, agent cards, executors,
+    and manage remote agent connections for the A2A (Agent-to-Agent) protocol.
+    """
 
     @staticmethod
     def create_agent(agent_config: AigencyConfig) -> Agent:
+        """Create an Agent instance from configuration.
+
+        Args:
+            agent_config (AigencyConfig): Complete agent configuration containing
+                metadata, service, agent, and observability settings.
+
+        Returns:
+            Agent: Configured Agent instance ready for execution.
+        """
 
         tools = [
             ToolGenerator.create_tool(tool_cfg) for tool_cfg in agent_config.agent.tools
         ]
 
+        remote_agents = agent_config.agent.remote_agents
+        if remote_agents:
+            remote_agent_connections = AgentA2AGenerator.build_remote_agent_connections(
+                agent_config
+            )
+            logger.info(f"Remote agent connections: {remote_agent_connections}")
+            communicator = Communicator(
+                remote_agent_connections=remote_agent_connections
+            )
+            tools.append(communicator.send_message)
+
         return Agent(
             name=agent_config.metadata.name,
             model=agent_config.agent.model.name,
@@ -33,6 +84,14 @@ class AgentA2AGenerator:
 
     @staticmethod
     def build_agent_card(agent_config: AigencyConfig) -> AgentCard:
+        """Build an AgentCard from configuration.
+
+        Args:
+            agent_config (AigencyConfig): Complete agent configuration.
+
+        Returns:
+            AgentCard: Agent card containing metadata and capabilities for A2A protocol.
+        """
 
         # TODO: Parse properly
         capabilities = AgentCapabilities(
@@ -63,6 +122,15 @@ class AgentA2AGenerator:
 
     @staticmethod
     def build_executor(agent: Agent, agent_card: AgentCard) -> AgentA2AExecutor:
+        """Build an AgentA2AExecutor for the given agent.
+
+        Args:
+            agent (Agent): The agent instance to create an executor for.
+            agent_card (AgentCard): The agent card containing metadata.
+
+        Returns:
+            AgentA2AExecutor: Configured executor ready to handle A2A requests.
+        """
 
         runner = Runner(
             app_name=agent.name,
@@ -73,3 +141,55 @@ class AgentA2AGenerator:
         )
 
         return AgentA2AExecutor(runner=runner, card=agent_card)
+
+    @staticmethod
+    def build_remote_agent_connections(agent_config: AigencyConfig):
+        """Initialize connections to all remote agents asynchronously.
+
+        Tests each connection individually with detailed logging to help identify
+        any connection issues. It attempts to connect to each remote agent address,
+        retrieve its agent card, and store the connection for later use.
+
+        Args:
+            agent_config (AigencyConfig): Configuration containing remote agent details.
+
+        Returns:
+            dict[str, AgentClient]: Dictionary mapping agent names to their client
+                connections.
+
+        Raises:
+            Exception: If any critical failure occurs during connection establishment.
+        """
+
+        if not agent_config.agent.remote_agents:
+            return {}
+
+        remote_agent_configs = [
+            {"url": generate_url(host=remote_agent.host, port=remote_agent.port)}
+            for remote_agent in agent_config.agent.remote_agents
+        ]
+
+        async def _connect():
+            remote_agent_connections = {}
+            async with httpx.AsyncClient(timeout=60) as client:
+                for config in remote_agent_configs:
+                    address = config.get("url")
+                    logger.debug(f"--- Attempting connection to: {address} ---")
+                    try:
+                        card_resolver = A2ACardResolver(client, address)
+                        card = await card_resolver.get_agent_card()
+                        remote_connection = AgentClient(agent_card=card)
+                        remote_agent_connections[card.name] = remote_connection
+                    except Exception as e:
+                        logger.error(
+                            f"--- CRITICAL FAILURE for address: {address} ---",
+                            exc_info=True,
+                        )
+                        raise e
+            return remote_agent_connections
+
+        try:
+            return safe_async_run(_connect())
+        except Exception as e:
+            logger.error("--- CRITICAL FAILURE", exc_info=True)
+            raise e

aigency/schemas/agent/agent.py

@@ -1,12 +1,50 @@
+"""Agent core logic and capabilities schema definition.
+
+This module defines the Agent Pydantic model that represents the core logic,
+AI model configuration, and capabilities of an Aigency agent. It serves as
+the central configuration for an agent's behavior, skills, tools, and
+communication capabilities with other agents.
+
+The Agent class encapsulates all the essential components needed to define
+an intelligent agent including its instruction set, model configuration,
+available skills, tools, and connections to remote agents.
+
+Example:
+    Creating an agent configuration:
+
+    >>> agent = Agent(
+    ...     model=AgentModel(name="gpt-4", provider="openai"),
+    ...     instruction="You are a helpful assistant",
+    ...     skills=[Skill(name="math", description="Mathematical operations")],
+    ...     tools=[Tool(name="calculator", type=ToolType.FUNCTION)]
+    ... )
+
+Attributes:
+    None: This module contains only Pydantic model definitions.
+"""
+
 from pydantic import BaseModel
 from typing import List, Optional
 from aigency.schemas.agent.model import AgentModel
 from aigency.schemas.agent.skills import Skill
-from aigency.schemas.agent.tools import FunctionTool, McpTool
+from aigency.schemas.agent.tools import Tool
+from aigency.schemas.agent.remote_agent import RemoteAgent
+
 
 class Agent(BaseModel):
-    """El 'cerebro' del agente: su lógica, modelo y capacidades."""
+    """The agent's 'brain': its logic, model and capabilities.
+
+    Attributes:
+        model (AgentModel): Configuration for the AI model to use.
+        instruction (str): System instruction that defines the agent's behavior.
+        skills (List[Skill]): List of skills the agent possesses.
+        tools (List[Tool], optional): List of tools available to the agent.
+        remote_agents (List[RemoteAgent], optional): List of remote agents this
+            agent can communicate with.
+    """
+
     model: AgentModel
     instruction: str
     skills: List[Skill]
-    tools: Optional[List[FunctionTool | McpTool]] = []
+    tools: Optional[List[Tool]] = []
+    remote_agents: Optional[List[RemoteAgent]] = []

aigency/schemas/agent/model.py

@@ -1,12 +1,46 @@
+"""AI model configuration schemas for agent setup.
+
+This module defines Pydantic models for configuring AI models and their providers
+within the Aigency framework. It provides structured configuration for different
+AI model providers and their specific parameters, enabling flexible model
+selection and configuration for agents.
+
+The models support various AI providers and allow for extensible configuration
+of model-specific parameters, API keys, and other provider-specific settings.
+
+Example:
+    Creating model configurations:
+
+    >>> provider_config = ProviderConfig(name="openai", endpoint="https://api.openai.com")
+    >>> model = AgentModel(name="gpt-4", provider=provider_config)
+
+Attributes:
+    None: This module contains only Pydantic model definitions.
+"""
+
 from typing import Optional
 from pydantic import BaseModel
 
+
 class ProviderConfig(BaseModel):
-    """Configuration for AI model provider."""
+    """Configuration for AI model provider.
+
+    Attributes:
+        name (str): Name of the AI provider.
+        endpoint (str, optional): Custom endpoint URL for the provider.
+    """
+
     name: str
     endpoint: Optional[str] = None
 
+
 class AgentModel(BaseModel):
-    """Configuration for AI model."""
+    """Configuration for AI model.
+
+    Attributes:
+        name (str): Name of the AI model to use.
+        provider (ProviderConfig, optional): Provider configuration details.
+    """
+
     name: str
-    provider: Optional[ProviderConfig] = None
+    provider: Optional[ProviderConfig] = None

aigency/schemas/agent/remote_agent.py

@@ -0,0 +1,41 @@
+"""Remote agent connection configuration schema.
+
+This module defines the RemoteAgent Pydantic model for configuring connections
+to remote agents in the Aigency framework. It provides the necessary structure
+for establishing communication with agents running on different services or
+locations within the A2A ecosystem.
+
+The RemoteAgent configuration enables agents to discover and communicate with
+other agents, facilitating distributed agent architectures and collaborative
+agent workflows.
+
+Example:
+    Configuring a remote agent connection:
+
+    >>> remote_agent = RemoteAgent(
+    ...     name="data_processor",
+    ...     host="agent-data-processor",
+    ...     port=8080
+    ... )
+
+Attributes:
+    None: This module contains only Pydantic model definitions.
+"""
+
+from pydantic import BaseModel, Field
+
+
+class RemoteAgent(BaseModel):
+    """Remote agent configuration.
+
+    Configuration for connecting to remote agents in the A2A protocol.
+
+    Attributes:
+        name (str): Name identifier for the remote agent.
+        host (str): Hostname or IP address of the remote agent.
+        port (int): Port number for the remote agent connection (1-65535).
+    """
+
+    name: str
+    host: str
+    port: int = Field(..., ge=1, le=65535)