|
1 | 1 | # AgentVault Architecture |
2 | 2 |
|
3 | | -This document provides a high-level overview of the AgentVault architecture, illustrating the relationships between key components and communication protocols. |
| 3 | +This document provides a high-level overview of the AgentVault architecture, illustrating the relationships between key components and communication protocols, emphasizing the secure, enterprise-grade workflow. |
4 | 4 |
|
5 | 5 | ## Core Components & Interactions |
6 | 6 |
|
7 | | -The AgentVault ecosystem revolves around several key entities: |
| 7 | +The AgentVault ecosystem enables secure and orchestrated interactions between various components: |
8 | 8 |
|
9 | | -1. **Agents (A2A Compliant):** Independent services exposing capabilities via the **Agent-to-Agent (A2A) Protocol**. They are described by **Agent Cards**. Examples include specialized agents for research, data processing, or interacting with specific APIs. |
10 | | -2. **MCP Tool Servers:** Services exposing specific, often low-level capabilities (like filesystem access, code execution, database queries, API interactions) via the **Model Context Protocol (MCP)**, which uses JSON-RPC 2.0 over HTTP. These are *not* necessarily full A2A agents. |
11 | | -3. **AgentVault Registry:** A central discovery service where agents publish their **Agent Cards**. Clients and other agents query the registry to find agents based on their capabilities or unique IDs (HRIs). |
12 | | -4. **Orchestrator:** A component (e.g., a LangGraph workflow, a Python script, another agent) that coordinates tasks across multiple A2A agents and potentially MCP tools to achieve a complex goal. |
13 | | -5. **MCP Tool Proxy Agent:** A specialized A2A-compliant agent designed to bridge the A2A and MCP domains. Orchestrators send A2A requests to the proxy, specifying a target MCP tool and its arguments. The proxy translates this into an MCP (JSON-RPC) call to the appropriate **MCP Tool Server**, receives the result, and translates it back into an A2A response for the orchestrator. **This is the current recommended pattern for integrating MCP tools into A2A workflows.** |
14 | | -6. **Clients / User Interfaces:** Tools like the **AgentVault CLI** or custom applications that allow users to interact with the system, initiate tasks, query the registry, or manage agents. |
| 9 | +1. **Developer/User:** The human initiating tasks and managing the system, typically via the CLI. |
| 10 | +2. **AgentVault CLI:** The command-line interface for interacting with AgentVault, including running tasks, managing configurations, and discovering agents. |
| 11 | +3. **Local Key Manager:** A client-side component (using OS keyring, environment variables, or files) responsible for securely storing and retrieving credentials (like Registry API keys or Agent-specific keys/OAuth tokens) needed for authentication. |
| 12 | +4. **AgentVault Registry:** A central discovery service where agents publish their **Agent Cards**. It allows clients to find agents based on their capabilities or unique IDs (HRIs). Developer authentication is required to manage cards. |
| 13 | +5. **Agent (A2A Compliant):** The service performing the core task. In enterprise scenarios, this agent might run within a **Trusted Execution Environment (TEE)** for enhanced security and integrity. It communicates via the A2A protocol. |
| 14 | +6. **TEE Attestation Service (Optional):** An external or integrated service responsible for verifying the integrity and identity of an agent running within a TEE before sensitive operations are performed. |
| 15 | +7. **Secure Artifact Storage (Optional):** A dedicated storage solution (like cloud storage or a secure local store) used for handling large or sensitive data artifacts generated or consumed by agents, referenced via URLs or secure handles rather than being embedded directly in A2A messages. |
| 16 | +8. **AgentVault Library:** Used internally by the CLI (and potentially orchestrators or custom clients) to handle A2A communication, interact with the Key Manager, parse Agent Cards, and manage task lifecycles. |
| 17 | +9. **(Implied) OAuth Authorization Server:** Involved when agents use OAuth2 authentication schemes for secure, delegated access. |
| 18 | +10. **(Implied) Policy Engine (e.g., OPA):** Can be integrated by agents or infrastructure for fine-grained authorization decisions (as depicted in the Federated Identity concept). |
15 | 19 |
|
16 | 20 | ## Communication Protocols |
17 | 21 |
|
18 | | -* **A2A Protocol:** Used for primary communication between clients, orchestrators, and A2A-compliant agents (including the MCP Tool Proxy Agent). Uses JSON-RPC 2.0 over HTTP(S) with SSE support for streaming. |
19 | | -* **MCP (Model Context Protocol):** Used for communication between the MCP Tool Proxy Agent and specific MCP Tool Servers. Uses JSON-RPC 2.0 over HTTP(S). |
20 | | - |
21 | | -## High-Level Diagram |
22 | | - |
23 | | -```mermaid |
24 | | -graph TD |
25 | | - User([User/Developer]) --> CLI[AgentVault CLI] |
26 | | - CLI --> Orchestrator((Orchestrator)) |
27 | | - CLI --> Registry[(Registry)] |
28 | | -
|
29 | | - Orchestrator -- Discover --> Registry |
30 | | - Registry -- Card Info --> Orchestrator |
31 | | -
|
32 | | - Orchestrator -- A2A Task --> Agent1[A2A Agent 1] |
33 | | - Agent1 -- A2A Result --> Orchestrator |
34 | | - Orchestrator -- A2A Task --> Agent2[A2A Agent 2] |
35 | | - Agent2 -- A2A Result --> Orchestrator |
36 | | -
|
37 | | - Orchestrator -- A2A Request --> MCP_Proxy[MCP Tool Proxy Agent] |
38 | | - MCP_Proxy -- MCP Call --> MCPServer1[/MCP Tool Server 1/] |
39 | | - MCPServer1 -- MCP Response --> MCP_Proxy |
40 | | - MCP_Proxy -- MCP Call --> MCPServer2[/MCP Tool Server 2/] |
41 | | - MCPServer2 -- MCP Response --> MCP_Proxy |
42 | | - MCP_Proxy -- MCP Call --> MCPServerN[/... Other Tools/] |
43 | | - MCPServerN -- MCP Response --> MCP_Proxy |
44 | | - MCP_Proxy -- A2A Response --> Orchestrator |
45 | | -
|
46 | | - User -- Deploys --> Agent1 |
47 | | - User -- Deploys --> MCP_Proxy |
48 | | - User -- Deploys --> MCPServer1 |
49 | | - User -- Deploys --> MCPServer2 |
50 | | -
|
51 | | -``` |
52 | | - |
53 | | -## Explanation |
54 | | - |
55 | | -1. **User Interaction:** Users typically interact via the CLI or custom applications, which communicate with the Orchestrator or Registry using the A2A protocol. |
56 | | -2. **Orchestration:** The Orchestrator uses the Registry to discover agents based on their capabilities (defined in their Agent Cards). It then initiates tasks and receives results/events from these agents using the A2A protocol. |
57 | | -3. **MCP Tool Usage:** When the Orchestrator needs to execute an external tool (like reading a file, running code, querying a specific API): |
58 | | - * It sends an A2A request to the **MCP Tool Proxy Agent**. This request includes the logical ID of the target MCP server (e.g., "filesystem", "code-runner", "database-tool"), the specific tool name (e.g., "filesystem.readFile"), and the necessary arguments. |
59 | | - * The **MCP Tool Proxy Agent** looks up the actual URL of the target MCP server (e.g., `http://custom-filesystem-mcp:8001/rpc`) and sends a standard JSON-RPC 2.0 request over HTTP to it. |
60 | | - * The **MCP Tool Server** executes the requested method and returns a JSON-RPC 2.0 response. |
61 | | - * The Proxy Agent relays the result (or error) back to the Orchestrator within the A2A task's response. |
62 | | -4. **Agent Specialization:** Each component focuses on its core competency. A2A Agents handle complex logic and state, while MCP Tool Servers provide specific, reusable functions via a simple RPC interface. The Proxy pattern decouples the A2A and MCP domains. |
63 | | - |
64 | | -This architecture allows for flexible and scalable multi-agent systems where different components communicate using appropriate protocols, facilitated by the AgentVault framework and demonstrated effectively in the **[MCP Test Pipeline Example](./examples/poc_mcp_pipeline.md)**. |
| 22 | +* **A2A Protocol:** The primary protocol for task management and communication between the CLI/Orchestrator and A2A-compliant Agents. Uses JSON-RPC 2.0 over HTTPS, with SSE for event streaming. |
| 23 | +* **Registry API:** A RESTful API (HTTPS) used by the CLI and developers to manage and discover Agent Cards. |
| 24 | +* **Attestation Protocol:** Specific protocol dependent on the TEE technology used (e.g., SGX Remote Attestation, AWS Nitro Attestation) used between the Agent (in TEE), the Attestation Service, and potentially the Client/CLI. |
| 25 | +* **Storage Protocol:** Standard protocols like HTTPS (S3 API, etc.) used for interacting with Secure Artifact Storage. |
| 26 | +* **MCP (Model Context Protocol):** Used for agent-to-tool communication, typically via a proxy agent. (See [MCP Profile](./mcp.md) and [MCP Example](./examples/poc_mcp_pipeline.md)). |
| 27 | + |
| 28 | +## High-Level Architecture Diagram |
| 29 | + |
| 30 | +The following diagram visualizes the key components and a typical secure workflow, including optional TEE attestation: |
| 31 | + |
| 32 | + |
| 33 | +*(Diagram showing the Developer interacting via CLI, which uses the KeyManager and Registry. The CLI optionally checks attestation with an Attestation Service before initiating a task with a Target Agent (potentially in a TEE). The Agent may interact with Secure Artifact Storage and streams results back to the CLI via A2A/SSE.)* |
| 34 | + |
| 35 | +## Explanation of Secure Workflow |
| 36 | + |
| 37 | +1. **Task Initiation:** The Developer uses the **AgentVault CLI** to run a task on a target agent, specifying the agent reference (HRI or URL) and input data. The `--attest` flag can be used to request TEE attestation verification. |
| 38 | +2. **Agent Discovery (if HRI used):** The CLI contacts the **AgentVault Registry** (authenticating using a Developer API Key fetched from the **Local Key Manager**) to retrieve the **Agent Card** for the target agent. |
| 39 | +3. **Agent Card Parsing:** The CLI parses the Agent Card to get the agent's A2A endpoint URL, required authentication schemes, and TEE details (if present). |
| 40 | +4. **TEE Attestation (Optional):** If the `--attest` flag was used and the Agent Card indicates TEE support, the CLI interacts with the appropriate **TEE Attestation Service** to verify the integrity and identity of the target agent instance *before* sending the task. If verification fails, the process stops. |
| 41 | +5. **Credential Retrieval:** The CLI requests the necessary credentials (API Key, OAuth details) for the target agent from the **Local Key Manager**. The Key Manager securely retrieves these based on the agent's requirements specified in the card. |
| 42 | +6. **A2A Task Initiation:** The CLI (using the underlying AgentVault Library) establishes a secure HTTPS connection to the **Target Agent's** A2A endpoint. It sends the `tasks/send` request (JSON-RPC), including the task input and necessary authentication headers (API Key or Bearer Token obtained via Key Manager/OAuth flow). |
| 43 | +7. **Agent Processing & SSE Streaming:** |
| 44 | + * The Target Agent authenticates the request. |
| 45 | + * It begins processing the task asynchronously. |
| 46 | + * The CLI establishes an SSE connection (`tasks/sendSubscribe`) to receive real-time updates. |
| 47 | + * The Agent streams `task_status`, `task_message`, and `task_artifact` events back to the CLI via SSE over HTTPS. |
| 48 | + * **Artifact Handling:** If the agent generates large or sensitive artifacts, it may upload them to **Secure Artifact Storage** and send back only a URL or reference in the `task_artifact` event. Small artifacts might be included directly in the event. |
| 49 | +8. **Event Processing (CLI):** |
| 50 | + * The CLI receives and parses SSE events. |
| 51 | + * It displays status updates and messages to the Developer. |
| 52 | + * For artifact events, if a URL/reference is present (or the artifact is deemed large), the CLI may download the content from **Secure Artifact Storage**. Otherwise, it displays/saves inline content. |
| 53 | + * The SSE loop continues until a terminal task status (COMPLETED, FAILED, CANCELED) is received. |
| 54 | +9. **Final Status:** The CLI may optionally make a final `tasks/get` call to retrieve the complete final task state. |
| 55 | +10. **Results:** The CLI displays the final results, status, and any relevant artifact locations or content to the Developer. |
| 56 | + |
| 57 | +This workflow, leveraging components like the Key Manager, Registry, optional TEE Attestation, and distinct communication protocols (A2A, MCP via proxy), provides a secure and robust framework for orchestrating complex agent tasks. |
0 commit comments