Skip to content

Commit db15193

Browse files
OhYeeOhYee
committed
docs: refactor documentation structure and enhance code highlighting
The documentation structure has been reorganized with several tutorial files deleted and new sections added. The docusaurus configuration has been updated to include code highlighting plugins and npm2yarn conversion. New CSS styles have been added for better code block visualization and image handling. The changes include: - Deleted tutorial files (00-10) related to basic concepts and best practices - Added new documentation sections under tutorial/core, tutorial/advanced, and tutorial/quickstart - Enhanced code highlighting with custom CSS styles for error/success/info lines - Added image zoom functionality and improved alt text handling - Integrated npm2yarn conversion plugin for better documentation 删除了从00到10的教程文件，这些文件涉及基本概念和最佳实践。新增了tutorial/core、tutorial/advanced和tutorial/quickstart目录下的文档。增强了代码高亮功能，并添加了自定义CSS样式用于错误/成功/信息行的显示。添加了图片缩放功能并改进了alt文本处理。集成npm2yarn转换插件以改善文档。 Change-Id: Ifff872f0b8e0e54de898f64cde58174264c01cb4 Signed-off-by: OhYee <[email protected]>
1 parent 89da3aa commit db15193

37 files changed

+2524
-527
lines changed

‎docs/_partial/_config.mdx‎

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
import Tabs from '@theme/Tabs';
2+
import TabItem from '@theme/TabItem';
3+
4+
AgentRun SDK 支持如下配置，可以通过多种方式注入程序
5+
6+
| Config 配置项 | 环境变量 | 说明 |
7+
| :-----------------: | :-------------------------------------------------------------: | :--------------------------: |
8+
| `access_key_id` | `AGENTRUN_ACCESS_KEY_ID`、`ALIBABA_CLOUD_ACCESS_KEY_ID` | Access Key ID |
9+
| `access_key_secret` | `AGENTRUN_ACCESS_KEY_SECRET`、`ALIBABA_CLOUD_ACCESS_KEY_SECRET` | Access Key Secret |
10+
| `security_token` | `AGENTRUN_SECURITY_TOKEN`、`ALIBABA_CLOUD_SECURITY_TOKEN` | STS Token |
11+
| `account_id` | `AGENTRUN_ACCOUNT_ID`、`FC_ACCOUNT_ID` | 账号 ID |
12+
| `token` | | 请求数据链路时，使用的 token |
13+
| `region_id` | `AGENTRUN_REGION`、`FC_REGION` | 区域 |
14+
| `timeout` | | |
15+
| `read_timeout` | | |
16+
| `control_endpoint` | `AGENTRUN_CONTROL_ENDPOINT` | 控制端点 |
17+
| `data_endpoint` | `AGENTRUN_DATA_ENDPOINT` | 数据端点 |
18+
| `devs_endpoint` | `DEVS_ENDPOINT` | Devs 端点 |
19+
| | `AGENTRUN_SDK_DEBUG` | 开启 DEBUG 日志 |
20+
| `headers` | | 发送请求时，附加的头部 |
21+
22+
要访问您在云上的 AgentRun 资源，需要配置阿里云的密钥。通常您的密钥为 ACCESS_KEY_ID 和 ACCESS_KEY_SECRET。当使用 AssumeRole 方式生成临时密钥时，还会存在 SECURITY_TOKEN。
23+
如果您只需要访问数据链路，也可以仅配置 AgentRun Token
24+
25+
<Tabs><TabItem value="env" label="通过 .env 配置" default>
26+
27+
`.env` 是一个特殊的文件，用来约定程序运行需要的环境变量。
28+
将您的 Agent 需要的环境变量写入在 `.env` 后，SDK 会自动读取 .env 的配置。这样既方便管理，又避免了在代码中硬编码敏感信息。
29+
30+
:::warning[注意]
31+
请确保将 `.env` 文件添加到 `.gitignore`，避免误提交到版本控制系统，导致敏感信息泄漏。
32+
:::
33+
34+
```bash title=".env"
35+
AGENTRUN_ACCESS_KEY_ID="LT*************"
36+
AGENTRUN_ACCESS_KEY_SECRET="DU*************"
37+
AGENTRUN_ACCOUNT_ID="143*********149"
38+
AGENTRUN_REGION="cn-hangzhou"
39+
```
40+
41+
</TabItem><TabItem value="export" label="通过 export 配置">
42+
43+
如果仅仅是一次性配置环境变量，也可以在终端中临时进行配置环境变量
44+
45+
使用该方式，仅有 ./start 可以访问到环境变量
46+
47+
```bash
48+
AGENTRUN_ACCESS_KEY_ID="LT*************" AGENTRUN_ACCESS_KEY_SECRET="DU*************" ./start
49+
```
50+
51+
使用该方式，当前 shell 及子进程中均能访问到环境变量
52+
53+
```bash
54+
export AGENTRUN_ACCESS_KEY_ID="LT*************"
55+
export AGENTRUN_ACCESS_KEY_SECRET="DU*************"
56+
57+
./start
58+
```
59+
60+
</TabItem><TabItem value="code" label="通过代码配置">
61+
62+
您也可以在代码中直接创建 Config 对象来全局参数配置。这种方式适合需要动态切换配置的场景：
63+
64+
创建的 Config 对象可以在调用 SDK API 时作为参数传入。如果同时存在环境变量配置和代码配置，SDK 会优先使用代码中显式传入的配置。
65+
66+
对于需要支持多账号或多区域的应用，可以创建多个 Config 对象并在调用时指定。例如，某些操作在国内区域执行，某些操作在海外区域执行。
67+
68+
<Tabs groupId="language" queryString><TabItem value="python" label="Python" attributes={{ className: 'python-icon' }}>
69+
70+
```python
71+
from agentrun.utils.config import Config
72+
73+
config = Config(
74+
access_key_id="LT*************",
75+
access_key_secret="DU*************",
76+
)
77+
```
78+
79+
</TabItem><TabItem value="nodejs" label="NodeJS" attributes={{ className: 'nodejs-icon' }}>
80+
81+
```js
82+
import { Config } from '@agentrun/sdk';
83+
84+
const config = new Config({
85+
accessKeyId: 'LT*************',
86+
accessKeySecret: 'DU*************',
87+
});
88+
```
89+
90+
</TabItem></Tabs>
91+
92+
</TabItem></Tabs>
93+
94+
:::info[从本地到云上]
95+
在部署到 AgentRun 时，您可以在 Agent Runtime 配置环境变量来替代您在本地 `.env`。
96+
97+
为了增强安全性，可以通过配置角色的方式来替代 `AGENTRUN_ACCESS_KEY_ID` 等环境变量，AgentRun 在启动您的 Agent 时，会根据角色权限为您创建临时的密钥并注入在环境变量中。
98+
:::

‎docs/_partial/_create_model_service.mdx‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
要创建模型服务，需要进入 AgentRun 控制台 - [模型管理](https://functionai.console.aliyun.com/cn-hangzhou/agent/models/llm)
2+
3+
![点击创建模型](https://img.alicdn.com/imgextra/i2/O1CN017gyJH61RTo0FIamfw_!!6000000002113-2-tps-2712-1068.png)
4+
5+
AgentRun 支持注册第三方的模型，也可以直接在函数计算 FunModel 部署开源/私有大模型
6+
对于注册的第三方模型，需要选择模型的来源（用来确认请求的交互协议以及 BaseURL）
7+
一个模型服务可以配置多个模型，如果通过 SDK 调用且未明确指定模型名时，会使用列表的第一个模型
8+
9+
![填写模型信息](https://img.alicdn.com/imgextra/i1/O1CN01Tvqm831C0kdoFuu30_!!6000000000019-2-tps-1224-3198.png)
10+
11+
创建完成后，您应该可以在模型列表看到您创建的模型
12+
13+
![创建结果](https://img.alicdn.com/imgextra/i3/O1CN01Q0JurV1LqoCVjtgZg_!!6000000001351-2-tps-1134-924.png)

‎docs/_partial/_create_sandbox_browser.mdx‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
要创建 Sandbox，需要进入 AgentRun 控制台 - 运行时与沙箱 - [Sandbox 沙箱](https://functionai.console.aliyun.com/cn-hangzhou/agent/runtime/sandbox)
2+
3+
![点击创建 Sandbox](https://img.alicdn.com/imgextra/i1/O1CN01LjthU51G6wSSNnKty_!!6000000000574-2-tps-3038-1030.png)
4+
5+
AgentRun 提供了多种 Sandbox，这里以浏览器沙箱为例
6+
7+
![选择 Sandbox 类型](https://img.alicdn.com/imgextra/i2/O1CN01QZopcn1aTePXP86EP_!!6000000003331-2-tps-1746-990.png)
8+
9+
如果仅作测试，除去沙箱名称外的其他信息均不需要修改；当您要将沙箱正式对外使用时，除去配置计算资源规格等参数外，建议您正确配置 “入站：访问凭证配置” 避免被第三方请求您的资源造成非预期的费用
10+
11+
![填写沙箱信息](https://img.alicdn.com/imgextra/i1/O1CN01tbqE711vW2PFz54Ut_!!6000000006179-2-tps-1356-3182.png)
12+
13+
创建完成后，您应该可以在模型列表看到您创建的沙箱
14+
15+
![创建结果](https://img.alicdn.com/imgextra/i3/O1CN01zJlyKD1nhvlT5SLdK_!!6000000005122-2-tps-884-898.png)

‎docs/_partial/_install_s.mdx‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
[Serverless Devs](https://serverless-devs.com/) 是一个开源开放的 Serverless 开发者平台，致力于为开发者提供强大的工具链体系。通过该平台，开发者不仅可以一键体验多云 Serverless 产品，极速部署 Serverless 项目，还可以在 Serverless 应用全生命周期进行项目的管理，并且非常简单快速的将 Serverless Devs 与其他工具/平台进行结合，进一步提升研发、运维效能。
2+
3+
通过 Serverless Devs，可以快速创建 AgentRun 应用模板、部署代码到 Agent Runtime。
4+
5+
如果您的本地环境已经安装了 NodeJS，可以通过 npm 快速完成安装：
6+
7+
```bash npm2yarn
8+
npm install -g @serverless-devs/s
9+
```
10+
11+
如果您不希望安装 NodeJS 环境，也可以直接下载 [Serverless Devs 二进制程序](https://github.com/Serverless-Devs/Serverless-Devs/releases)使用。安装完成后，执行 `s --version` 验证安装是否成功。
12+
13+
14+
Serverless Devs 安装完成后，您还需要配置阿里云密钥，授予 Serverless Devs 权限
15+
16+
```bash
17+
# 按照引导输入 Access Key ID 和 Secret，记住密钥对名称（如 agentrun-deploy）
18+
s config add
19+
```

‎docs/_partial/_role.mdx‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
为了提升安全性，您不需要将阿里云密钥配置到环境变量中，取而代之的是通过角色进行授权。当您为 AgentRun/函数计算 配置了角色后，您的程序在启动时将会自动根据角色权限注入临时密钥到环境变量。及时由于意外问题导致密钥泄漏，该临时密钥也会在固定时间后自动过期，减少损失。
2+
3+
通常，在 AgentRun 场景下，您需要为角色配置如下权限
4+
- `AliyunAgentRunFullAccess`: 允许您的代码访问 AgentRuntime、Sandbox、Model、Credential 等能力
5+
- `AliyunDevsFullAccess`: 允许您的代码访问 ToolSet
6+
7+
如果您还需要访问其他云产品，则可以按需增加权限。对于特定业务场景，您也可以进行精确授权，如仅授予某个资源的读权限。更多信息可以参考 [RAM角色概览](https://help.aliyun.com/zh/ram/user-guide/ram-role-overview)
8+
9+
如果您需要快速创建一个拥有 `AliyunAgentRunFullAccess` 和 `AliyunDevsFullAccess` 权限的角色，则可以点击 [快速授权链接](https://ram.console.aliyun.com/authorize?request=%7B%22template%22%3A%22OldRoleCommonAuthorize%22%2C%22referrer%22%3A%22https%3A%2F%2Ffunctionai.console.aliyun.com%2Fcn-hangzhou%2Fexplore%22%2C%22payloads%22%3A%5B%7B%22missionId%22%3A%22OldRoleCommonAuthorize.FC%22%2C%22roleName%22%3A%22AliyunAgentRunDefaultRole%22%2C%22roleDescription%22%3A%22AgentRun%20auto%20created%20role.%22%2C%22rolePolicies%22%3A%5B%7B%22policyName%22%3A%22AliyunAgentRunFullAccess%22%7D%2C%7B%22policyName%22%3A%22AliyunDevsFullAccess%22%7D%5D%7D%5D%2C%22callback%22%3A%22https%3A%2F%2Ffunctionai.console.aliyun.com%22%7D)

‎docs/api/python/utils/config.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -244,10 +244,10 @@ def get_headers(self) -> Dict[str, str]
244244

245245
## 函数
246246

247-
## get_env_with_default
247+
## get_config_with_default
248248

249249
```python
250-
def get_env_with_default(default: str, *key: str) -> str
250+
def get_config_with_default(default: str, *key: str) -> str
251251
```
252252

253253
从环境变量获取值,支持多个候选键 / Get value from environment variables with multiple fallback keys

‎docs/tutorial/00-overview.md‎

Lines changed: 0 additions & 82 deletions
This file was deleted.

0 commit comments

Comments
 (0)