Merge pull request #9 from Serverless-Devs/anycodes-dev

Anycodes dev

Author: OhYee

docs/tutorial/00-overview.md

@@ -0,0 +1,82 @@
+---
+sidebar_position: 10
+---
+
+# SDK 概览与架构介绍
+
+## 什么是 AgentRun
+
+AgentRun 是以高代码为核心，开放生态、灵活组装的一站式 Agentic AI 基础设施平台，为企业级 Agentic 应用提供开发、部署与运维全生命周期管理。平台基于 Serverless 架构提供强隔离的运行时与沙箱环境，深度集成开源生态，为用户提供模型高可用和数据不出域能力。
+
+AgentRun Python SDK 是平台的官方客户端库，提供了完整的 Python API 来管理和调用 AgentRun 服务。通过这个 SDK，开发者可以在本地开发环境中编写、测试 Agent 应用，并无缝部署到云端运行。
+
+<img src="https://github.com/user-attachments/assets/22f1cb98-1e42-47ac-b3c1-3d5d9c8c00f5" />
+
+
+## SDK 的核心价值
+
+AgentRun Python SDK 采用面向对象的设计理念，将云端资源抽象为 Python 对象，使开发者能够像操作本地对象一样管理云端资源。SDK 同时提供同步和异步两套 API，支持多种认证方式，并包含完整的类型注解，为 IDE 提供良好的代码提示支持。
+
+SDK 的一个重要特性是对主流 AI 开发框架的深度集成。您可以继续使用熟悉的框架（如 LangChain、AgentScope、LangGraph、CrewAI 等）编写 Agent 逻辑，SDK 会自动处理与 AgentRun 平台的对接工作，包括模型调用、工具执行、沙箱管理等底层细节。
+
+## 核心概念
+
+### Agent Runtime
+
+Agent Runtime 是 AgentRun 平台上运行 Agent 应用的基本单元。每个 Agent Runtime 封装了您的 Agent 代码、依赖环境和运行配置。SDK 提供了完整的 Agent Runtime 生命周期管理能力，包括创建、更新、删除和监控等操作。
+
+Agent Runtime 支持两种运行方式：代码模式和容器模式。代码模式下，您只需提供 Python 代码和依赖列表，平台会自动构建运行环境；容器模式则允许您使用自定义的容器镜像，适合有特殊环境需求的场景。
+
+每个 Agent Runtime 可以创建多个访问端点（Endpoint），支持不同的路由策略和版本管理。例如，您可以创建一个生产端点和一个测试端点，分别指向不同版本的 Agent 代码，实现灰度发布和 A/B 测试。
+
+### Model
+
+AgentRun 提供了统一的模型管理能力，屏蔽不同模型供应商的 API 差异。SDK 支持两种模型接入方式：Model Service 用于接入自建或第三方模型服务，Model Proxy 则提供模型代理和治理功能，包括负载均衡、故障转移、请求限流等企业级特性。
+
+通过 SDK 的模型 API，您可以使用统一的接口调用不同供应商的模型。SDK 会自动处理请求格式转换、认证、重试等细节，让您专注于业务逻辑的开发。同时，SDK 提供了便捷的转换函数，可以将 AgentRun 模型对象转换为各个框架所需的格式。
+
+### Sandbox
+
+沙箱环境是 AgentRun 的核心安全特性之一。SDK 目前支持两类沙箱：代码解释器沙箱（Code Interpreter）用于执行动态生成的代码，浏览器沙箱（Browser）则提供完整的浏览器自动化能力。
+
+代码解释器沙箱支持 Python 和 Shell 脚本执行，提供了完整的文件系统操作、进程管理和执行上下文管理功能。您可以在沙箱中上传文件、执行代码、下载结果，所有操作都在隔离的容器环境中进行，确保宿主系统的安全。
+
+浏览器沙箱基于 Chromium 内核，集成了 Playwright 自动化框架。SDK 提供了同步和异步两套 Playwright API 封装，支持页面导航、元素操作、截图录制等完整的浏览器控制能力。沙箱还支持远程调试和实时预览，方便开发调试。
+
+### ToolSet
+
+ToolSet 是 AgentRun 的工具管理系统。SDK 支持多种工具定义方式，包括基于 OpenAPI 规范的 HTTP 工具和基于 MCP（Model Context Protocol）的标准化工具。您可以通过 SDK 获取平台上已注册的工具集，并自动转换为各个框架所需的工具格式。
+
+对于 OpenAPI 工具，SDK 会解析 OpenAPI 规范文档，自动生成工具描述和参数定义，并处理 HTTP 请求的构建和发送。对于 MCP 工具，SDK 实现了完整的 MCP 协议客户端，可以与任何符合 MCP 规范的工具服务通信。
+
+### Credential
+
+凭证管理用于存储和管理访问第三方服务所需的密钥。SDK 支持多种凭证类型，包括 API Key、Basic Auth、OAuth Token 等。您可以在 AgentRun 平台上集中管理凭证，Agent 运行时会自动注入所需的凭证，避免在代码中硬编码敏感信息。
+
+### Integration
+
+SDK 的集成模块提供了统一的适配器层，将 AgentRun 的模型、工具、沙箱等能力转换为各个框架的原生对象。目前支持的框架包括 LangChain、LangGraph、AgentScope、CrewAI、Google ADK 和 Pydantic AI。
+
+集成的核心设计是 CommonModel 和 CommonToolSet 抽象。这两个抽象类封装了 AgentRun 的底层 API，并提供了转换方法（如 `to_langchain()`、`to_agentscope()`），可以将对象转换为对应框架的格式。这种设计使得您可以编写框架无关的代码，在需要时轻松切换框架。
+
+### Server
+
+AgentRunServer 是一个轻量级的 HTTP 服务器组件，可以将您的 Agent 封装为 HTTP API。Server 内置了 OpenAI Chat Completions 协议的实现，使您的 Agent 可以直接替换 OpenAI API 使用。
+
+Server 基于 FastAPI 构建，采用插件化的协议设计。除了内置的 OpenAI 协议，您也可以实现自定义协议处理器，支持其他 API 规范。Server 自动处理请求解析、响应格式化、流式输出等细节，让您只需关注 Agent 的业务逻辑。
+
+## 架构设计
+
+AgentRun Python SDK 采用分层架构设计。最底层是 Control API 和 Data API，分别负责资源管理和数据操作。Control API 用于创建、更新、删除云端资源，Data API 则用于与运行中的资源交互，如调用模型、执行沙箱命令等。
+
+在 API 层之上是资源对象层，将云端资源抽象为 Python 类，如 AgentRuntime、ModelService、Sandbox 等。这些类封装了底层 API 调用，提供了面向对象的操作接口。资源对象支持方法链调用，可以流畅地完成复杂操作。
+
+最上层是集成模块和工具类。集成模块提供框架适配器，工具类则包含配置管理、日志记录、异常处理等辅助功能。这种分层设计既保证了底层能力的完整性，又为上层使用提供了便利。
+
+## 适用场景
+
+AgentRun Python SDK 适用于需要构建企业级 AI Agent 应用的场景。典型应用包括智能客服系统、数据分析助手、代码生成工具、网页自动化机器人等。通过 SDK 提供的沙箱环境和工具系统，您可以让 Agent 安全地执行代码、访问外部 API、操作浏览器，完成复杂的任务流程。
+
+对于已经使用某个 AI 开发框架的团队，SDK 的集成能力可以帮助您快速迁移到 AgentRun 平台，享受平台提供的模型高可用、资源弹性伸缩、运维监控等企业级能力，而无需重写已有代码。
+
+对于需要严格数据安全和合规要求的场景，AgentRun 的数据不出域特性和隔离沙箱环境可以确保敏感数据的安全处理。您可以在私有网络环境中部署模型服务和工具服务，通过 SDK 连接到 AgentRun 平台，实现数据和计算的物理隔离。

docs/tutorial/01-installation.md

@@ -0,0 +1,157 @@
+---
+sidebar_position: 11
+---
+
+# 安装与配置
+
+## 环境要求
+
+AgentRun Python SDK 要求 Python 版本在 3.10 或更高。建议使用虚拟环境来管理项目依赖，避免与系统 Python 环境产生冲突。您可以使用 venv、virtualenv 或 conda 等工具创建虚拟环境。
+
+在安装 SDK 之前，请确保您已拥有阿里云账号，并已开通 AgentRun 服务。您需要准备好阿里云的 Access Key ID、Access Key Secret 和账号 ID，这些凭证将用于 SDK 与云端服务的认证。
+
+## 基础安装
+
+使用 pip 包管理器可以快速安装 AgentRun SDK。在终端中执行以下命令即可完成基础安装：
+
+```bash
+pip install agentrun-sdk
+```
+
+基础安装包含了 SDK 的核心功能，包括 Agent Runtime 管理、模型调用、凭证管理等基础能力。对于大多数简单场景，基础安装已经足够使用。
+
+## 可选依赖安装
+
+AgentRun SDK 采用模块化设计，将不同的功能特性作为可选依赖项提供。这样可以避免安装不必要的依赖包，减小环境体积。根据您的实际需求，可以选择安装以下可选依赖：
+
+**server** 依赖用于启用 HTTP 服务器功能。如果您需要使用 AgentRunServer 将 Agent 封装为 HTTP API，需要安装此依赖。该依赖包含 FastAPI 和 Uvicorn 等 Web 框架组件。
+
+**playwright** 依赖用于支持浏览器沙箱功能。当您需要让 Agent 进行网页自动化操作时，需要安装此依赖。安装后还需要运行 Playwright 的初始化命令来下载浏览器驱动。
+
+**mcp** 依赖用于支持 MCP（Model Context Protocol）工具集。如果您的 Agent 需要调用基于 MCP 协议的工具服务，需要安装此依赖。
+
+**框架集成依赖**包括 langchain、agentscope、google-adk、crewai、pydantic-ai 等。这些依赖分别对应不同的 AI 开发框架。如果您使用某个框架进行 Agent 开发，需要安装对应的集成依赖。
+
+安装可选依赖时，在包名后用方括号指定依赖项名称，多个依赖项之间用逗号分隔。例如，如果您需要使用 AgentScope 框架，同时需要浏览器沙箱和 MCP 工具支持，可以执行：
+
+```bash
+pip install agentrun-sdk[playwright,mcp,agentscope]
+```
+
+对于使用 LangChain 框架并需要 HTTP 服务器功能的场景：
+
+```bash
+pip install agentrun-sdk[server,langchain]
+```
+
+如果您不确定需要哪些依赖，可以先安装基础版本，在遇到功能缺失时再按需补充安装。
+
+## 配置认证信息
+
+安装完成后，您需要配置认证信息才能使用 SDK。AgentRun SDK 支持多种配置方式，包括环境变量、代码配置和配置文件，您可以根据实际场景选择合适的方式。
+
+### 使用环境变量配置
+
+环境变量是推荐的配置方式，特别适合生产环境和容器化部署。SDK 会自动读取以下环境变量：
+
+```bash
+export AGENTRUN_ACCESS_KEY_ID="your-access-key-id"
+export AGENTRUN_ACCESS_KEY_SECRET="your-access-key-secret"
+export AGENTRUN_ACCOUNT_ID="your-account-id"
+export AGENTRUN_REGION="cn-hangzhou"
+```
+
+这四个环境变量是必需的，分别对应阿里云的访问密钥 ID、访问密钥 Secret、账号 ID 和服务区域。SDK 还支持以 `ALIBABA_CLOUD_` 为前缀的备用环境变量名，例如 `ALIBABA_CLOUD_ACCESS_KEY_ID` 等，这样可以与其他阿里云 SDK 共享配置。
+
+在开发环境中，建议将环境变量配置写入项目根目录的 `.env` 文件，然后使用 python-dotenv 等工具加载。这样既方便管理，又避免了在代码中硬编码敏感信息。请确保将 `.env` 文件添加到 `.gitignore`，避免误提交到版本控制系统。
+
+对于使用 STS 临时凭证的场景，还需要设置安全令牌：
+
+```bash
+export AGENTRUN_SECURITY_TOKEN="your-sts-token"
+```
+
+如果您需要自定义服务端点或启用调试模式，可以设置以下可选环境变量：
+
+```bash
+export AGENTRUN_CONTROL_ENDPOINT="https://custom-control-endpoint"
+export AGENTRUN_DATA_ENDPOINT="https://custom-data-endpoint"
+export AGENTRUN_SDK_DEBUG="true"
+```
+
+### 使用代码配置
+
+您也可以在代码中直接创建 Config 对象来配置认证信息。这种方式适合需要动态切换配置的场景：
+
+```python
+from agentrun.utils.config import Config
+
+config = Config(
+    access_key_id="your-access-key-id",
+    access_key_secret="your-access-key-secret",
+    account_id="your-account-id",
+    region_id="cn-hangzhou",
+    timeout=30
+)
+```
+
+创建的 Config 对象可以在调用 SDK API 时作为参数传入。如果同时存在环境变量配置和代码配置，SDK 会优先使用代码中显式传入的配置。
+
+对于需要支持多账号或多区域的应用，可以创建多个 Config 对象并在调用时指定。例如，某些操作在国内区域执行，某些操作在海外区域执行：
+
+```python
+cn_config = Config(
+    access_key_id="cn-key-id",
+    access_key_secret="cn-secret",
+    account_id="cn-account-id",
+    region_id="cn-hangzhou"
+)
+
+us_config = Config(
+    access_key_id="us-key-id",
+    access_key_secret="us-secret",
+    account_id="us-account-id",
+    region_id="us-west-1"
+)
+```
+
+### 配置参数说明
+
+除了必需的认证凭证，Config 还支持以下可选参数：
+
+**timeout** 参数控制 HTTP 请求的超时时间，单位为秒，默认值为 600 秒。对于预期执行时间较长的操作，可以适当增大此值。
+
+**headers** 参数允许您为所有请求添加自定义 HTTP 头。这在需要传递额外的元数据或跟踪信息时很有用。
+
+**control_endpoint** 和 **data_endpoint** 参数用于自定义服务端点。一般情况下无需设置，SDK 会根据 region_id 自动选择合适的端点。只有在使用私有部署或特殊网络环境时才需要自定义。
+
+## 验证安装
+
+完成安装和配置后，建议运行一个简单的测试脚本来验证 SDK 是否正常工作。创建一个 Python 文件并输入以下代码：
+
+```python
+from agentrun.agent_runtime import AgentRuntime
+
+# 列出所有 Agent Runtime
+runtimes = AgentRuntime.list()
+print(f"找到 {len(runtimes)} 个 Agent Runtime")
+```
+
+执行这个脚本，如果能成功输出而没有报错，说明 SDK 已正确安装并配置。如果遇到认证错误，请检查您的 Access Key 配置是否正确；如果遇到网络错误，请检查您的网络连接和防火墙设置。
+
+对于需要使用可选依赖的功能，建议先进行单独验证。例如，验证 Playwright 安装：
+
+```python
+from agentrun.sandbox import Sandbox, TemplateType
+
+# 这会检查 Playwright 是否可用
+print("Playwright 支持已启用")
+```
+
+如果提示缺少 Playwright，需要执行 Playwright 的安装命令：
+
+```bash
+playwright install chromium
+```
+
+完成所有验证后，您就可以开始使用 AgentRun SDK 开发 Agent 应用了。