aigency 0.0.1rc238211992__py3-none-any.whl → 0.1.0rc67928564__py3-none-any.whl

aigency/agents/client.py

@@ -1,10 +1,29 @@
+"""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
-#TODO: Enable when auth is implemented
-#from a2a.client.auth.interceptor import AuthInterceptor
 
 
 class AgentClient:

aigency/agents/communicator.py

@@ -1,5 +1,26 @@
+"""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, List
+from typing import Any, Awaitable
 
 from a2a.types import Message, Task
 from google.adk.tools.tool_context import ToolContext
@@ -8,70 +29,82 @@ from aigency.utils.logger import get_logger
 
 logger = get_logger()
 
+
 class Communicator:
-    """Clase base para la comunicación entre agentes (Agent-to-Agent)."""
+    """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):
-        """Inicializa el comunicador con las conexiones a los agentes remotos.
+        """Initialize the communicator with remote agent connections.
 
         Args:
-            remote_agent_connections: Un diccionario que mapea nombres de agentes
-                a sus objetos de conexión de cliente.
+            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]:
-        """Delega una tarea a un agente remoto específico.
+        """Delegate a task to a specific remote agent.
 
-        Este método envía un mensaje a un agente remoto, solicitando que realice una
-        tarea. Gestiona la creación del payload del mensaje y la comunicación.
+        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: Nombre del agente remoto al que se envía la tarea.
-            task: Descripción detallada de la tarea para el agente remoto.
-            tool_context: Objeto de contexto que contiene el estado y otra información.
+            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:
-            Un objeto Task si la comunicación es exitosa, o None en caso contrario.
+            Task | None: A Task object if communication is successful, or None
+                otherwise.
 
         Raises:
-            ValueError: Si el agente especificado no se encuentra en las conexiones.
+            ValueError: If the specified agent is not found in connections.
         """
         logger.info(
-            f"`send_message` iniciado para el agente: '{agent_name}' con la tarea: '{task}'"
+            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"El LLM intentó llamar a '{agent_name}', pero no se encontró. "
-                f"Agentes disponibles: {available_agents}"
+                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}"
             )
-            raise ValueError(f"Agente '{agent_name}' no encontrado. Agentes disponibles: {available_agents}")
 
         state = tool_context.state
 
-        # Simplifica la creación y obtención de contextos de agente usando setdefault
         contexts = state.setdefault("remote_agent_contexts", {})
-        agent_context = contexts.setdefault(agent_name, {"context_id": str(uuid.uuid4())})
+        agent_context = contexts.setdefault(
+            agent_name, {"context_id": str(uuid.uuid4())}
+        )
         context_id = agent_context["context_id"]
 
-        # Obtiene IDs de forma más segura y clara
         task_id = state.get("task_id")
         input_metadata = state.get("input_message_metadata", {})
         message_id = input_metadata.get("message_id")
 
-        # El message_id se pasa directamente al creador del payload
         payload = self.create_send_message_payload(
             text=task, task_id=task_id, context_id=context_id, message_id=message_id
         )
-        logger.debug("`send_message` con el siguiente payload: %s", payload)
+        logger.debug("`send_message` with the following payload: %s", payload)
 
         send_response = None
-        # Este bucle está diseñado para consumir un generador asíncrono y obtener
-        # la última respuesta, que suele ser el resultado final.
+
         async for resp in client.send_message(
             message_request=Message(**payload["message"])
         ):
@@ -82,8 +115,8 @@ class Communicator:
 
         if not isinstance(send_response, Task):
             logger.warning(
-                f"La respuesta recibida del agente '{agent_name}' no es un objeto Task. "
-                f"Tipo recibido: {type(send_response)}"
+                f"The response received from agent '{agent_name}' is not a Task object. "
+                f"Received type: {type(send_response)}"
             )
             return None
 
@@ -96,16 +129,19 @@ class Communicator:
         context_id: str | None = None,
         message_id: str | None = None,
     ) -> dict[str, Any]:
-        """Crea el payload de un mensaje para enviarlo a un agente remoto.
+        """Create a message payload to send to a remote agent.
 
         Args:
-            text: El contenido de texto del mensaje.
-            task_id: ID de tarea opcional para asociar con el mensaje.
-            context_id: ID de contexto opcional para asociar con el mensaje.
-            message_id: ID de mensaje opcional. Si es None, se generará uno nuevo.
+            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:
-            Un diccionario que contiene el payload del mensaje formateado.
+            dict[str, Any]: A dictionary containing the formatted message payload.
         """
         payload: dict[str, Any] = {
             "message": {
@@ -118,4 +154,4 @@ class Communicator:
             payload["message"]["task_id"] = task_id
         if context_id:
             payload["message"]["context_id"] = context_id
-        return payload
+        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,27 @@
-import logging
-import httpx
-from typing import List
-import asyncio
+"""Agent generation and factory module.
+
+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
@@ -14,7 +33,6 @@ 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.schemas.agent.remote_agent import RemoteAgent
 from aigency.tools.generator import ToolGenerator
 from aigency.utils.utils import generate_url, safe_async_run
 from aigency.agents.communicator import Communicator
@@ -22,10 +40,25 @@ from aigency.utils.logger import get_logger
 
 logger = get_logger()
 
+
 class AgentA2AGenerator:
+    """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
@@ -51,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(
@@ -81,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,
@@ -100,8 +150,15 @@ class AgentA2AGenerator:
         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:
-            No exceptions are raised, but errors are logged.
+            Exception: If any critical failure occurs during connection establishment.
         """
 
         if not agent_config.agent.remote_agents:
@@ -135,4 +192,4 @@ class AgentA2AGenerator:
             return safe_async_run(_connect())
         except Exception as e:
             logger.error("--- CRITICAL FAILURE", exc_info=True)
-            raise e
+            raise e

aigency/schemas/agent/agent.py

@@ -1,3 +1,28 @@
+"""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
@@ -7,7 +32,16 @@ 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

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

@@ -1,8 +1,40 @@
+"""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."""
+    """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

aigency/schemas/agent/skills.py

@@ -1,10 +1,42 @@
+"""Agent skill definition and configuration schema.
+
+This module defines the Skill Pydantic model for representing specific capabilities
+or skills that an agent possesses within the Aigency framework. Skills define
+what an agent can do and provide structured metadata about the agent's abilities.
+
+Skills serve as descriptive components that help categorize and communicate an
+agent's capabilities to other agents and systems in the A2A ecosystem.
+
+Example:
+    Defining agent skills:
+
+    >>> skill = Skill(
+    ...     name="data_analysis",
+    ...     description="Analyze datasets and generate insights",
+    ...     tags=["analytics"]
+    ... )
+
+Attributes:
+    None: This module contains only Pydantic model definitions.
+"""
+
 from pydantic import BaseModel
 from typing import List
 
+
 class Skill(BaseModel):
-    """Define una habilidad específica del agente."""
+    """Define a specific skill of the agent.
+
+    Attributes:
+        id (str): Unique identifier for the skill.
+        name (str): Human-readable name of the skill.
+        description (str): Detailed description of what the skill does.
+        tags (List[str]): List of tags for categorizing the skill.
+        examples (List[str]): List of usage examples for the skill.
+    """
+
     id: str
     name: str
     description: str
     tags: List[str]
-    examples: List[str]
+    examples: List[str]