aigency 0.0.1rc238211992__tar.gz → 0.1.0__tar.gz

aigency-0.1.0/PKG-INFO

@@ -0,0 +1,171 @@
+Metadata-Version: 2.4
+Name: aigency
+Version: 0.1.0
+Summary: Add your description here
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: google-adk>=1.11.0
+Requires-Dist: a2a-sdk>=0.3.0
+Requires-Dist: litellm<1.73.0,>=1.72.6
+Requires-Dist: pyyaml==6.0.2
+Requires-Dist: PyJWT==2.10.1
+
+# Aigency
+
+AI Agent Development Acceleration Kit — build, run, and orchestrate intelligent agents with a production‑ready Agent‑to‑Agent (A2A) runtime.
+
+Aigency provides primitives and utilities to define agents via simple YAML, instantiate them programmatically, and serve them over HTTP using the A2A server. It is designed to be modular, observable, and extensible.
+
+- Python: >= 3.12
+- PyPI package: `aigency`
+- Core deps: `a2a-sdk`, `pyyaml`, `litellm`, `PyJWT`, `google-adk`
+
+## Features
+- Config‑first agents: define agent behavior, skills, tools, and model in YAML
+- Agent generator: instantiate agents, build agent cards, and executors programmatically
+- A2A integration: serve agents over HTTP with Starlette‑based A2A server
+- MCP‑friendly: integrate external tools/services via Model Context Protocol (optional)
+- Observability: compatible with Phoenix and A2A Inspector for tracing and debugging
+- Docker‑friendly: used across example demos and containers
+
+## Installation
+```bash
+pip install aigency
+```
+Requires Python 3.12+.
+
+## Quickstart
+Minimal example for a single agent (no MCP) that responds in the user’s language.
+
+1) Create an agent config file (e.g., `agent_config.yaml`):
+```yaml
+metadata:
+  name: hello_agent
+  description: A simple example agent that greets and answers briefly.
+  version: 1.0.0
+
+service:
+  url: http://hello-agent:8080
+  capabilities:
+    streaming: true
+  interface:
+    default_input_modes: [text, text/plain]
+    default_output_modes: [text, text/plain]
+
+agent:
+  model:
+    name: gemini-2.0-flash
+
+  instruction: |
+      """
+      You are a friendly, concise assistant. Always reply in the same language as the user.
+      Keep responses short and helpful.
+      """
+
+  skills:
+    - id: greet
+      name: Greet
+      description: Greets users and offers help
+      examples:
+        - "Hello! How can I help you today?"
+```
+
+2) Run a tiny A2A app (e.g., `app.py`):
+```python
+import os
+import uvicorn
+from a2a.server.apps import A2AStarletteApplication
+from a2a.server.request_handlers import DefaultRequestHandler
+from a2a.server.tasks import InMemoryTaskStore
+from aigency.agents.generator import AgentA2AGenerator
+from aigency.utils.config_service import ConfigService
+
+CONFIG_PATH = os.path.join(os.path.dirname(__file__), "agent_config.yaml")
+
+config_service = ConfigService(config_file=CONFIG_PATH)
+agent_config = config_service.config
+
+agent = AgentA2AGenerator.create_agent(agent_config=agent_config)
+agent_card = AgentA2AGenerator.build_agent_card(agent_config=agent_config)
+executor = AgentA2AGenerator.build_executor(agent=agent, agent_card=agent_card)
+
+request_handler = DefaultRequestHandler(
+    agent_executor=executor,
+    task_store=InMemoryTaskStore(),
+)
+app = A2AStarletteApplication(
+    agent_card=agent_card,
+    http_handler=request_handler,
+).build()
+
+if __name__ == "__main__":
+    uvicorn.run(app, host="0.0.0.0", port=8080)
+```
+
+3) Start the server:
+```bash
+python app.py
+```
+Then open http://localhost:8080 to interact via the A2A HTTP interface or connect a compatible client.
+
+## Using Models & Providers
+Aigency integrates with LLM providers via its dependencies. For Google Gemini models:
+
+- Use API key (Google AI Studio):
+  - `GEMINI_API_KEY=your_gemini_api_key`
+  - `GOOGLE_GENAI_USE_VERTEXAI=FALSE`
+- Or use Vertex AI (requires additional env like project/region and credentials):
+  - `GOOGLE_GENAI_USE_VERTEXAI=TRUE`
+
+Set these environment variables before running your app if you use Gemini‑based models.
+
+## Configuration Reference (YAML)
+Common top‑level sections:
+
+- `metadata`: name, description, version
+- `service`: url, capabilities, interface defaults
+- `agent`:
+  - `model`: model name (e.g., `gemini-2.0-flash`)
+  - `instruction`: system prompt/persona
+  - `skills`: list of skills with `id`, `name`, `description`, and `examples`
+  - `tools`: optional integrations (e.g., MCP tools)
+- `observability`: optional Phoenix/A2A Inspector configuration
+
+Example of adding an MCP tool:
+```yaml
+tools:
+  - type: mcp
+    name: sample_mcp
+    description: Example MCP tool
+    mcp_config:
+      url: sample-mcp-service
+      port: 8080
+      path: /mcp/
+```
+
+## Examples & Demos
+Explore ready‑to‑run demos built with Aigency:
+
+- Reception Agent (single agent, no MCP):
+  https://aigency-project.github.io/get_started/demos/reception_aigent
+- Gossip Agent (single agent + MCP tools):
+  https://aigency-project.github.io/get_started/demos/gossip_agent
+- Detective Aigency (multi‑agent system):
+  https://aigency-project.github.io/get_started/demos/detective_aigency/
+
+Documentation site:
+- https://aigency-project.github.io/
+
+## Observability
+Aigency‑based apps can be observed with:
+- Phoenix dashboard (tracing/metrics)
+- A2A Inspector (agent/task introspection)
+
+Refer to the demo repositories for docker‑compose setups that launch these services.
+
+## Development
+- Python 3.12+
+- Install dev deps and run tests as usual; for versioning helpers, see `scripts/version_manager.py` in this repo.
+
+## License
+This project’s license is provided in the `LICENSE` file.

aigency-0.1.0/README.md

@@ -0,0 +1,159 @@
+# Aigency
+
+AI Agent Development Acceleration Kit — build, run, and orchestrate intelligent agents with a production‑ready Agent‑to‑Agent (A2A) runtime.
+
+Aigency provides primitives and utilities to define agents via simple YAML, instantiate them programmatically, and serve them over HTTP using the A2A server. It is designed to be modular, observable, and extensible.
+
+- Python: >= 3.12
+- PyPI package: `aigency`
+- Core deps: `a2a-sdk`, `pyyaml`, `litellm`, `PyJWT`, `google-adk`
+
+## Features
+- Config‑first agents: define agent behavior, skills, tools, and model in YAML
+- Agent generator: instantiate agents, build agent cards, and executors programmatically
+- A2A integration: serve agents over HTTP with Starlette‑based A2A server
+- MCP‑friendly: integrate external tools/services via Model Context Protocol (optional)
+- Observability: compatible with Phoenix and A2A Inspector for tracing and debugging
+- Docker‑friendly: used across example demos and containers
+
+## Installation
+```bash
+pip install aigency
+```
+Requires Python 3.12+.
+
+## Quickstart
+Minimal example for a single agent (no MCP) that responds in the user’s language.
+
+1) Create an agent config file (e.g., `agent_config.yaml`):
+```yaml
+metadata:
+  name: hello_agent
+  description: A simple example agent that greets and answers briefly.
+  version: 1.0.0
+
+service:
+  url: http://hello-agent:8080
+  capabilities:
+    streaming: true
+  interface:
+    default_input_modes: [text, text/plain]
+    default_output_modes: [text, text/plain]
+
+agent:
+  model:
+    name: gemini-2.0-flash
+
+  instruction: |
+      """
+      You are a friendly, concise assistant. Always reply in the same language as the user.
+      Keep responses short and helpful.
+      """
+
+  skills:
+    - id: greet
+      name: Greet
+      description: Greets users and offers help
+      examples:
+        - "Hello! How can I help you today?"
+```
+
+2) Run a tiny A2A app (e.g., `app.py`):
+```python
+import os
+import uvicorn
+from a2a.server.apps import A2AStarletteApplication
+from a2a.server.request_handlers import DefaultRequestHandler
+from a2a.server.tasks import InMemoryTaskStore
+from aigency.agents.generator import AgentA2AGenerator
+from aigency.utils.config_service import ConfigService
+
+CONFIG_PATH = os.path.join(os.path.dirname(__file__), "agent_config.yaml")
+
+config_service = ConfigService(config_file=CONFIG_PATH)
+agent_config = config_service.config
+
+agent = AgentA2AGenerator.create_agent(agent_config=agent_config)
+agent_card = AgentA2AGenerator.build_agent_card(agent_config=agent_config)
+executor = AgentA2AGenerator.build_executor(agent=agent, agent_card=agent_card)
+
+request_handler = DefaultRequestHandler(
+    agent_executor=executor,
+    task_store=InMemoryTaskStore(),
+)
+app = A2AStarletteApplication(
+    agent_card=agent_card,
+    http_handler=request_handler,
+).build()
+
+if __name__ == "__main__":
+    uvicorn.run(app, host="0.0.0.0", port=8080)
+```
+
+3) Start the server:
+```bash
+python app.py
+```
+Then open http://localhost:8080 to interact via the A2A HTTP interface or connect a compatible client.
+
+## Using Models & Providers
+Aigency integrates with LLM providers via its dependencies. For Google Gemini models:
+
+- Use API key (Google AI Studio):
+  - `GEMINI_API_KEY=your_gemini_api_key`
+  - `GOOGLE_GENAI_USE_VERTEXAI=FALSE`
+- Or use Vertex AI (requires additional env like project/region and credentials):
+  - `GOOGLE_GENAI_USE_VERTEXAI=TRUE`
+
+Set these environment variables before running your app if you use Gemini‑based models.
+
+## Configuration Reference (YAML)
+Common top‑level sections:
+
+- `metadata`: name, description, version
+- `service`: url, capabilities, interface defaults
+- `agent`:
+  - `model`: model name (e.g., `gemini-2.0-flash`)
+  - `instruction`: system prompt/persona
+  - `skills`: list of skills with `id`, `name`, `description`, and `examples`
+  - `tools`: optional integrations (e.g., MCP tools)
+- `observability`: optional Phoenix/A2A Inspector configuration
+
+Example of adding an MCP tool:
+```yaml
+tools:
+  - type: mcp
+    name: sample_mcp
+    description: Example MCP tool
+    mcp_config:
+      url: sample-mcp-service
+      port: 8080
+      path: /mcp/
+```
+
+## Examples & Demos
+Explore ready‑to‑run demos built with Aigency:
+
+- Reception Agent (single agent, no MCP):
+  https://aigency-project.github.io/get_started/demos/reception_aigent
+- Gossip Agent (single agent + MCP tools):
+  https://aigency-project.github.io/get_started/demos/gossip_agent
+- Detective Aigency (multi‑agent system):
+  https://aigency-project.github.io/get_started/demos/detective_aigency/
+
+Documentation site:
+- https://aigency-project.github.io/
+
+## Observability
+Aigency‑based apps can be observed with:
+- Phoenix dashboard (tracing/metrics)
+- A2A Inspector (agent/task introspection)
+
+Refer to the demo repositories for docker‑compose setups that launch these services.
+
+## Development
+- Python 3.12+
+- Install dev deps and run tests as usual; for versioning helpers, see `scripts/version_manager.py` in this repo.
+
+## License
+This project’s license is provided in the `LICENSE` file.

{aigency-0.0.1rc238211992 → aigency-0.1.0}/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-0.1.0/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-0.0.1rc238211992 → aigency-0.1.0}/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)