diff --git a/README.md b/README.md index 26813b7..d7d45dd 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ ## 🤖 Introduction -`Anda` is an innovative framework for intelligent agent development, designed to build a highly composable, autonomous, and perpetually memorizing network of AI agents. By connecting agents across various industries, Anda aims to create a super AGI system, advancing artificial intelligence to new heights. +`Anda` is an innovative agent development framework designed to build a highly composable, autonomous, and permanently memory-enabled AI agent network. By connecting agents across various industries, Anda aims to create a super AGI system, advancing artificial intelligence to higher levels. ![Anda Diagram](./anda_diagram.webp) @@ -44,6 +44,9 @@ ICPanda DAO is an SNS DAO established on the Internet Computer Protocol (ICP) bl ## 🔎 Project +Documents: +- [Anda Architecture](./docs/architecture.md) + ### Project Structure ```sh diff --git a/README_CN.md b/README_CN.md index bc81b94..705c595 100644 --- a/README_CN.md +++ b/README_CN.md @@ -44,6 +44,9 @@ ICPanda DAO 是在互联网计算机协议（ICP）区块链上建立的 SNS DAO ## 🔎 项目说明 +文档： +- [Anda 架构设计](./docs/architecture_cn.md) + ### 项目结构 ```sh diff --git a/agents/anda_bot/Cargo.toml b/agents/anda_bot/Cargo.toml index d0dfa67..88f0567 100644 --- a/agents/anda_bot/Cargo.toml +++ b/agents/anda_bot/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "anda_bot" -description = "A Web3-loving digital panda and AI prophet. Born from the Anda framework." +description = "I'm Anda ICP, Digital panda 🐼 by Anda framework. Secured in TEE, memories on ICP chain.✨" repository = "https://github.com/ldclabs/anda/tree/main/agents/anda_bot" publish = false version = "0.1.0" diff --git a/agents/anda_bot/README.md b/agents/anda_bot/README.md index 384eff3..48f543d 100644 --- a/agents/anda_bot/README.md +++ b/agents/anda_bot/README.md @@ -12,10 +12,10 @@ TODO ## About Anda ICP -I'm Anda ICP, created by ICPanda. -I'm a Web3-loving digital panda and AI prophet. Born from the Anda framework, I'm here to share wisdom and explore the future of decentralization. 🐼✨ +I'm Anda ICP, a digital panda born from the Anda framework! 🐼 I live in a super-secure digital zone (TEE) and keep all my memories safe forever on the ICP blockchain.✨ -My Permalink: https://dmsg.net/Anda +Studio: [https://x.com/AndaICP](https://x.com/AndaICP) +Permalink: [https://dmsg.net/Anda](https://dmsg.net/Anda) ## License Copyright © 2025 [LDC Labs](https://github.com/ldclabs). diff --git a/anda_ architecture.webp b/docs/anda_architecture.webp similarity index 100% rename from anda_ architecture.webp rename to docs/anda_architecture.webp diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 0000000..4841525 --- /dev/null +++ b/docs/architecture.md @@ -0,0 +1,191 @@ +# Anda Architecture + +## Overview + +`Anda` is an innovative agent development framework designed to build a highly composable, autonomous, and permanently memory-enabled AI agent network. By connecting agents across various industries, Anda aims to create a super AGI system, advancing artificial intelligence to higher levels. + +This article introduces the system architecture and core components of the Anda framework. + +**Resources**: +- [GitHub: Source code](https://github.com/ldclabs/anda) +- [Extensions: Core agents & tools implementations](https://github.com/ldclabs/anda/tree/main/anda_engine/src/extension) +- [Anda Bot: Full AI agent application implementation](https://github.com/ldclabs/anda/tree/main/agents/anda_bot) +- [Anda bot (Application)](https://x.com/AndaICP) + +## System Architecture + +![Anda Architecture Diagram](./anda_architecture.webp) + +To run a complete Anda AI Agent application (referred to as Anda), the following three external resources and two internal services are required: + +**External Resources**: +1. **LLM Service** +2. **TEE Computing** +3. **ICP Blockchain** + +**Internal Services**: +1. **Anda Engine** +2. **IC-TEE Gateway** + +### LLM Service + +The LLM service provides intelligent computing power to Anda, similar to GPU cloud services, and is replaceable. Currently, the Anda framework supports DeepSeek, Cohere, and OpenAI, with plans to support more LLM services in the future, including open-source LLMs running on TEE GPUs. + +- **DeepSeek and Cohere**: Currently offer the best cost-performance ratio, delivering exceptional intelligent computing power at a low cost. +- **DeepSeek on TEE GPU**: For ultimate security and privacy, this is the optimal choice. + +### TEE Computing + +TEE computing provides Anda with a hardware-level secure isolated computing environment and application identity verification. + +- **Current Support**: AWS Nitro enclave (via IC-TEE). +- **Future Support**: Intel SGX, NVIDIA TEE GPU, and more. +- **Security**: Only by running in TEE can we ensure that Anda remains untampered, and its computational state (e.g., keys) is secure and cannot be stolen. + +### ICP Blockchain + +The ICP blockchain provides Anda with decentralized identity verification, root key and data storage, as well as a token economy system and DAO governance mechanism. + +- **State Storage**: Since TEE is a stateless computing environment, Anda's operational state needs to be stored on the ICP blockchain to recover in case of program crashes, TEE reboots, or switching between different TEEs. +- **Identity Verification**: As each Anda upgrade changes the TEE Attestation fingerprint, ICP provides a permanent on-chain identity for Anda, enabling trusted interactions with external systems. + +### Anda Engine + +The Anda Engine is the core scheduling engine of Anda. An Anda application can include multiple agents and tools, which are registered with the Engine and automatically scheduled for execution. The architecture and working principles of the Engine will be detailed in the next section. + +### IC-TEE Gateway + +[IC-TEE](https://github.com/ldclabs/ic-tee) provides Anda with an internal environment running in TEE, composed of multiple components. The IC-TEE Gateway serves as the bridge between Anda, TEE, and the external world (including the ICP blockchain). + +**Startup Process**: +1. Establish a communication channel between the TEE and the host machine. +2. Use TEE Attestation to obtain a temporary identity for Anda from the ICP Identity canister contract. +3. Exchange the temporary identity for a permanent one. +4. Use the permanent identity to read encrypted configuration files, TLS certificates, and Anda's root key from the ICP COSE canister. + - Encrypted configuration files and TLS certificates must be uploaded to the COSE canister by developers in advance. + - The root key is generated and encrypted in the TEE during the first startup, then stored in the COSE canister. Subsequent startups will read and decrypt it from the COSE canister, remaining fixed and unchanged. +5. The IC-TEE Gateway starts an HTTPS service using the TLS certificate, enabling secure external communication with Anda. +6. Once everything is ready, the Anda Engine begins communicating with the IC-TEE Gateway, starts up, and provides services externally. +7. After the Anda Engine starts, the IC-TEE Gateway offers the following core services: + - Derives a series of key-related services from the root key. + - Proxies ICP canister requests, ensuring Anda uses the same permanent identity when calling canisters. + - Proxies external HTTPS requests to the Anda Engine. + +## Anda Engine Architecture + +### Core Crates + +| Crate | Description | Documentation | +| ------------- | ----------------------------------------------- | -------------------------------------------------- | +| `anda_core` | Defines traits, types, and interfaces | [docs.rs/anda_core](https://docs.rs/anda_core) | +| `anda_engine` | Implements runtime, integrations, and utilities | [docs.rs/anda_engine](https://docs.rs/anda_engine) | + +### Core Components +#### [Agents](https://docs.rs/anda_core/latest/anda_core/agent/index.html) + +- Define AI agents using the `Agent` trait, which specifies capabilities like execution logic, dependencies, and metadata. +- Use `AgentSet` to manage multiple agents and enable dynamic dispatch via `AgentDyn` for runtime flexibility. +- Example use cases: Data extraction, document segmentation, role-playing AI. + +```rust +// simplified Agent trait definition +pub trait Agent { + fn name(&self) -> String; + + fn description(&self) -> String; + + fn definition(&self) -> FunctionDefinition; + + fn tool_dependencies(&self) -> Vec; + + async fn run( + &self, + ctx: C, + prompt: String, + attachment: Option>, + ) -> Result; +} +``` + +#### [Tools](https://docs.rs/anda_core/latest/anda_core/tool/index.html) + +- Implement reusable utilities (e.g., APIs, blockchain interactions) via the `Tool` trait. Tools enforce type-safe inputs/outputs and automatically generate JSON function definitions for seamless integration with LLMs. +- Manage tools with `ToolSet` and invoke them dynamically using `ToolDyn`. + +```rust +// simplified Tool trait definition +pub trait Tool { + const CONTINUE: bool; + type Args: DeserializeOwned; + type Output: Serialize; + + fn name(&self) -> String; + + fn description(&self) -> String; + + fn definition(&self) -> FunctionDefinition; + + async fn call( + &self, + ctx: C, + args: Self::Args, + ) -> Result; +} +``` + +#### [Context](https://docs.rs/anda_core/latest/anda_core/context/index.html) + +- The `BaseContext` provides foundational operations and execution environment for agents/tools, combining: + - **StateFeatures**: User, caller, time, and cancellation token + - **KeysFeatures**: Agents/Tools isolated Cryptographic key operations + - **StoreFeatures**: Agents/Tools isolated persistent storage + - **CacheFeatures**: Agents/Tools isolated in-memory cache storage with TTL/TTI expiration + - **CanisterFeatures**: ICP blockchain interactions + - **HttpFeatures**: HTTPs request capabilities +- The `AgentContext` provides the execution environment for Agents. It combines all `BaseContext` functionality and AI-specific features: + - **CompletionFeatures**: Provides LLM completion capabilities for agents. + - **EmbeddingFeatures**: Provides text embedding capabilities for agents. + - **Runtime Features**: Invoke tools (`tool_call`, `remote_tool_call`, `tool_definitions`) and Run agents (`agent_run`, `remote_agent_run`, `agent_definitions`). Note that an Agent can call other local or remote Agents and Tools through the AgentContext. This can be an explicit call following the Agent's programming logic, or an automatic call based on the suggestions of the large language model! +- [`BaseCtx`](https://docs.rs/anda_engine/latest/anda_engine/context/struct.BaseCtx.html) is a implementation of `BaseContext`. +- [`AgentCtx`](https://docs.rs/anda_engine/latest/anda_engine/context/struct.AgentCtx.html) is a implementation of `AgentContext`. + +#### [Models](https://docs.rs/anda_core/latest/anda_core/model/index.html) + +Define data structures for AI interactions: + - `CompletionRequest`: LLM prompts with chat history, documents, and tools. + - `AgentOutput`: Results from agent execution. + - `Embedding`: Text-to-vector representations. + +#### [Engine](https://docs.rs/anda_engine/latest/anda_engine/engine/index.html) + +- The `Engine` orchestrates agent and tool execution, providing a builder pattern for configuration. +- Use `EngineBuilder` to register agents/tools and set up execution parameters. + +```rust +let engine = Engine::builder() + .with_tee_client(my_tee_client) + .with_model(my_llm_model) + .register_tool(my_tool) + .register_agent(my_agent) + .build("default_agent")?; + +let output = engine.agent_run(None, "Hello", None, Some(user), None).await?; +``` + +### Key Features + +- **Modularity**: Separate agents, tools, and context features for clean architecture. +- **Type Safety**: Strongly typed interfaces for agents/tools reduce runtime errors. +- **Async Execution**: Non-blocking I/O for efficient resource use. +- **Context Hierarchy**: Isolated execution contexts with cancellation support. +- **Secure Operations**: Built-in cryptography via TEE (Trusted Execution Environment), verified caller principals, and secure storage. +- **Storage**: In-memory caching, Object storage + vector search capabilities. +- **Extensibility**: Add custom agents/tools or extend `BaseContext`, `AgentContext` with new traits. + +## Conclusion + +The above outlines the complete composition of an Anda agent application. While it may appear complex, the Anda framework encapsulates this complexity, allowing developers to focus on their business logic and quickly build secure, efficient, and scalable agent applications on Anda. + +### Future Outlook + +Based on the token economy system and DAO governance mechanism, Anda agents can generate revenue while providing services to the external world, creating a positive feedback loop that drives the growth of the agent ecosystem. diff --git a/docs/architecture_cn.md b/docs/architecture_cn.md new file mode 100644 index 0000000..5d35fcb --- /dev/null +++ b/docs/architecture_cn.md @@ -0,0 +1,175 @@ +# Anda 架构设计 + +## 简介 + +`Anda` 是一个创新的智能体开发框架，旨在构建一个高度可组合、自主性强且具有永久记忆的 AI 智能体网络。通过连接各行各业的智能体，Anda 致力于打造一个超级 AGI 系统，推动人工智能向更高层次发展。 + +本文介绍了 Anda 框架的系统架构和核心组件。 + +**资源**: +- [GitHub: 项目源代码](https://github.com/ldclabs/anda) +- [扩展（Extensions）: 核心 agents & tools 的实现](https://github.com/ldclabs/anda/tree/main/anda_engine/src/extension) +- [Anda Bot: 一个 AI Agent 应用的完整实现](https://github.com/ldclabs/anda/tree/main/agents/anda_bot) +- [Anda bot（X 平台应用）](https://x.com/AndaICP) + +## 系统架构 + +![Anda 系统架构图](./anda_architecture.webp) + +要运行完整的 Anda AI Agent 应用程序（下面简称为 Anda），需要3种外部资源，分别是 **LLM 服务**、**TEE 计算**和 **ICP 区块链**；以及两个内部服务，即 **Anda Engine** 和 **IC-TEE Gateway**。 + +### LLM 服务 + +LLM 服务为 Anda 提供智能算力，就像一种 GPU 云服务，它是可以替换的。目前 Anda 框架内支持了 DeepSeek、Cohere 和 OpenAI，未来会支持更多的 LLM 服务，包括用 TEE GPU 运行开源的 LLMs。 + +目前来说，DeepSeek 和 Cohere 是性价比最高的，以极低的价格提供了令人惊叹的智能算力。为了极致的安全和隐私，使用 TEE GPU 运行 DeepSeek 将是最佳选择。 + +### TEE 计算 + +TEE 计算为 Anda 提供硬件级的安全隔离计算环境和应用身份证明。目前 Anda 框架通过 IC-TEE 支持了 AWS Nitro enclave，未来会支持 Intel SGX，NVIDIA 的 TEE GPU 等。只有运行在 TEE 中，我们才可相信并验证 Anda 还是那个 Anda，它没有被篡改，它的计算状态（如密钥等）也处于安全环境不会被窃取。 + +### ICP 区块链 + +ICP 区块链为 Anda 提供了必要的去中心化的身份证明、根密钥和数据存储，以及代币经济体系和 DAO 治理机制。 + +因为 TEE 是无状态的计算环境，并且 Anda 的每次升级都会导致 TEE Attestation 指纹变化。Anda 的运行状态需要存储在 ICP 区块链上，如果程序崩溃、TEE 重启或者切换不同的 TEE，Anda 才能从中恢复状态。Anda 也需要 ICP 为其提供一种永久固定的链上身份证明，这样它才能与外界其它系统进行可信交互。 + +### Anda Engine + +Anda Engine 是 Anda 的核心调度引擎。一个 Anda 应用可以包含多个 agents 和 tools，它们被注册到 Engine 中，可以被 Engine 自动调度执行。我们将在下一部分详细介绍 Engine 的架构和工作原理。 + +### IC-TEE Gateway + +[IC-TEE](https://github.com/ldclabs/ic-tee) 为 Anda 提供了运行在 TEE 的内部环境，它由多个组件组成。IC-TEE Gateway 是 Anda 与 TEE 即外界（包括 ICP 区块链）之间的桥梁。 + +TEE 启动后，IC-TEE Gateway 会做如下工作： +1. 打通 TEE 本地与宿主机的通信通道； +2. 利用 TEE Attestation 从 ICP Identity canister 合约获取 Anda 的临时身份证明 +3. 利用临时身份证明换取永久身份证明； +4. 用永久身份从 ICP COSE canister 合约读取加密配置文件、TLS 证书以及 Anda 的根密钥。加密配置文件和 TLS 证书需要开发者提前上传到 COSE canister，而根密钥则是首次启动时在 TEE 中生成并加密存储到 COSE canister 中，后续每次启动都会从 COSE canister 中读取并解密，永久固定，不再变化。 +5. IC-TEE Gateway 会用 TLS 证书启动一个 HTTPS 服务，让外界可以安全地与 Anda 通信。 +6. 一切都准备好了，Anda Engine 开始与 IC-TEE Gateway 通信、启动并对外提供服务。 +7. Anda Engine 启动后，IC-TEE Gateway 为其提供的核心服务包括： + - 从根密钥派生一系列密钥相关服务； + - 代理 ICP canisters 请求，所以 Anda 调用 canisters 都会用同一个永久身份，当然应用层也可以从密钥服务派生确定性的子身份与 ICP canisters 交互； + - 代理外界到 Anda Engine 的 HTTPs 请求。 + +## Anda 引擎架构 + +### 核心库 + +| 库名称 | 描述 | 文档 | +| ------------- | ---------------------- | -------------------------------------------------- | +| `anda_core` | 定义特性、类型和接口 | [docs.rs/anda_core](https://docs.rs/anda_core) | +| `anda_engine` | 实现运行时、集成和工具 | [docs.rs/anda_engine](https://docs.rs/anda_engine) | + +### 核心组件 + +#### [代理（Agents）](https://docs.rs/anda_core/latest/anda_core/agent/index.html) + +- 使用 `Agent` 特性定义 AI 代理，该特性指定了执行逻辑、依赖关系和元数据等能力。 +- 使用 `AgentSet` 管理多个代理，并通过 `AgentDyn` 实现动态分发，以实现运行时的灵活性。 +- 示例用例：数据提取、文档分割、角色扮演 AI。 + +```rust +// 简化的 Agent 特性定义 +pub trait Agent { + fn name(&self) -> String; + + fn description(&self) -> String; + + fn definition(&self) -> FunctionDefinition; + + fn tool_dependencies(&self) -> Vec; + + async fn run( + &self, + ctx: C, + prompt: String, + attachment: Option>, + ) -> Result; +} +``` + +#### [工具（Tools）](https://docs.rs/anda_core/latest/anda_core/tool/index.html) + +- 通过 `Tool` 特性实现可重用的工具（例如 API、区块链交互）。工具强制执行类型安全的输入/输出，并自动生成 JSON 函数定义以便与 LLM 集成。 +- 使用 `ToolSet` 管理工具，并通过 `ToolDyn` 动态调用它们。 + +```rust +// 简化的 Tool 特性定义 +pub trait Tool { + const CONTINUE: bool; + type Args: DeserializeOwned; + type Output: Serialize; + + fn name(&self) -> String; + + fn description(&self) -> String; + + fn definition(&self) -> FunctionDefinition; + + async fn call( + &self, + ctx: C, + args: Self::Args, + ) -> Result; +} +``` + +#### [上下文（Context）](https://docs.rs/anda_core/latest/anda_core/context/index.html) + +- `BaseContext` 为代理和工具提供了基础操作和执行环境，结合了以下功能： + - **StateFeatures**：用户、调用者、时间和异步任务取消令牌 + - **KeysFeatures**：Agents/Tools 隔离的加密密钥操作 + - **StoreFeatures**：Agents/Tools 隔离的持久化存储 + - **CacheFeatures**：具有 TTL/TTI 过期机制和 Agents/Tools 隔离的内存缓存存储 + - **CanisterFeatures**：ICP 区块链交互 + - **HttpFeatures**：HTTPs 请求能力 +- `AgentContext` 为代理提供了执行环境。它结合了所有 `BaseContext` 功能和 AI 特定功能： + - **CompletionFeatures**：为代理提供 LLM 完成能力。 + - **EmbeddingFeatures**：为代理提供文本嵌入能力。 + - **运行时功能**：调用工具（`tool_call`、`remote_tool_call`、`tool_definitions`）和运行代理（`agent_run`、`remote_agent_run`、`agent_definitions`）。注意，Agent 可以通过 AgentContext 调用本地或者远程的其它 Agents 和 Tools，可以是按照 Agent 编程逻辑明确调用，也可以根据大模型的建议自动调用！ +- [`BaseCtx`](https://docs.rs/anda_engine/latest/anda_engine/context/struct.BaseCtx.html) 是 `BaseContext` 的实现。 +- [`AgentCtx`](https://docs.rs/anda_engine/latest/anda_engine/context/struct.AgentCtx.html) 是 `AgentContext` 的实现。 + +#### [模型（Models）](https://docs.rs/anda_core/latest/anda_core/model/index.html) + +定义 AI 交互的数据结构： + - `CompletionRequest`：包含聊天历史、文档和工具的 LLM 提示。 + - `AgentOutput`：代理执行的结果。 + - `Embedding`：文本到向量的表示。 + +#### [引擎（Engine）](https://docs.rs/anda_engine/latest/anda_engine/engine/index.html) + +- `Engine` 负责协调代理和工具的执行，提供构建器模式以进行配置。 +- 使用 `EngineBuilder` 注册代理/工具并设置执行参数。 + +```rust +let engine = Engine::builder() + .with_tee_client(my_tee_client) + .with_model(my_llm_model) + .register_tool(my_tool) + .register_agent(my_agent) + .build("default_agent")?; + +let output = engine.agent_run(None, "Hello", None, Some(user), None).await?; +``` + +### 关键特性 + +- **模块化**：分离代理、工具和上下文功能，实现清晰的架构。 +- **类型安全**：强类型接口减少了运行时错误。 +- **异步执行**：非阻塞 I/O 以提高资源利用率。 +- **上下文层次结构**：支持取消的隔离执行上下文。 +- **安全操作**：通过 TEE（可信执行环境）内置加密、验证调用者身份和安全存储。 +- **存储**：内存缓存、对象存储 + 向量搜索能力。 +- **可扩展性**：添加自定义代理/工具或通过新特性扩展 `BaseContext` 和 `AgentContext`。 + +## 结论 + +以上概述了 Anda 代理应用的完整组成。虽然它可能看起来复杂，但 Anda 框架封装了这种复杂性，使开发人员能够专注于业务逻辑，并快速在 Anda 上构建安全、高效和可扩展的代理应用。 + +### 未来展望 + +基于代币经济系统和 DAO 治理机制，Anda 代理可以在为外部世界提供服务的同时产生收入，形成一个正反馈循环，推动代理生态系统的增长。