Merge pull request #1 from Serverless-Devs/anycodes-patch-1

Add best practice category JSON configuration

Author: OhYee

docs/tutorial/discover/_category_.json

@@ -0,0 +1,5 @@
+{
+  "label": "能力探索",
+  "position": 5,
+  "collapsed": true
+}

docs/tutorial/discover/credential-management.md

@@ -0,0 +1,99 @@
+---
+sidebar_position: 180
+---
+
+# AgentRun 探秘：凭证管理让凭证下发更简单
+
+在构建 Agent 应用时，凭证管理是一个容易被忽视但又极其重要的问题。一个典型的 Agent 应用会面临两个方向的凭证需求：**向内，用户如何安全地调用你的 Agent？向外，Agent 如何安全地调用外部服务？**
+
+传统做法存在诸多问题。硬编码在代码里容易泄露且难以更新，存在配置文件中同样有安全风险，每次都手动传递不仅麻烦还容易出错，让大模型处理凭证更是巨大的安全隐患。更棘手的是，当凭证需要更新时（比如 API Key 过期、权限变更），如何在不重启服务的情况下动态更新？AgentRun 的凭证管理系统就是为了解决这些问题而生。
+
+<img width="2370" height="1452" alt="image" src="https://github.com/user-attachments/assets/2b9911cc-bc80-4654-8014-7d2215ec32b2" />
+
+
+
+## 入站凭证与出站凭证：双向安全保障
+AgentRun 的凭证管理分为两个维度，分别解决"谁能调用我"和"我能调用谁"的问题。
+
+### 入站凭证：控制谁能访问你的 Agent
+
+<img width="1308" height="340" alt="image" src="https://github.com/user-attachments/assets/3980f178-fca3-46e8-aab0-4a6692571396" />
+
+
+入站凭证用于控制外部用户或系统如何访问你的 Agent 应用。当你创建一个 Agent 并对外提供服务时，需要确保只有授权的用户才能调用。AgentRun 提供了灵活的入站凭证管理，可以为不同的调用方生成独立的凭证，设置不同的权限和配额，控制每个凭证能访问哪些 Agent、调用频率限制、有效期等。
+
+**由于所有请求都经过 AgentRun 网关，入站凭证可以实现真正的动态更新。**比如你的 Agent 对外提供客服能力，可以为不同的业务部门生成不同的入站凭证，每个部门只能访问各自授权的 Agent。当某个部门的凭证泄露时，可以立即撤销并重新生成，所有变更在网关层实时生效，不影响其他部门的使用，也无需重启任何服务。
+
+### 出站凭证：安全调用外部服务
+
+<img width="1282" height="316" alt="image" src="https://github.com/user-attachments/assets/cb7cf6ee-53b3-400b-95b7-a2217968e455" />
+
+
+出站凭证用于 Agent 访问外部服务时的身份认证。Agent 应用通常需要调用各种外部服务：大模型 API（OpenAI、Claude、Qwen 等）、数据库、第三方工具、企业内部系统等，每个服务都需要相应的凭证。传统方式下，开发者要么把这些凭证硬编码在代码里，要么通过环境变量传递，不仅不安全，更新时还需要重启服务。
+
+Ag**entRun 采用了一套巧妙的定时查询与缓存机制来管理出站凭证。**所有出站凭证统一存储在加密的凭证库中，代码里不再出现任何敏感信息。Agent 启动时会从凭证库拉取所需的所有凭证并缓存到本地，运行过程中直接使用本地缓存，避免频繁的网络请求带来的性能开销。同时，系统会定期进行健康检查，主动查询凭证是否有更新，发现变更时只更新发生变化的凭证。如果健康检查失败，会自动重试，确保凭证始终可用。
+
+<img width="1374" height="602" alt="image" src="https://github.com/user-attachments/assets/08bb16da-6a23-4133-bb74-6f3a98fc5070" />
+
+
+**这种定时查询方案带来了多重价值。**从性能角度看，本地缓存避免了每次调用都查询凭证库，大幅降低了延迟和网络开销；从可用性角度看，即使凭证服务短暂不可用，缓存的凭证仍然可用，不会影响 Agent 的正常运行；从安全性角度看，定时健康检查确保凭证泄露或过期时能在几分钟内完成更新，而不需要等到下次部署。**最关键的是，整个更新过程对 Agent 代码完全透明，开发者无需编写任何凭证更新逻辑，专注于业务实现即可。**
+
+这种最终一致性的设计在实践中被证明是最优的平衡：既保证了性能和可用性，又实现了凭证的动态更新能力。相比于每次都实时查询（性能差）或者只在启动时加载（更新不及时），定时查询方案在三者之间找到了最佳平衡点。
+
+## 实际应用：工具和模型的凭证配置
+AgentRun 的凭证管理在两个关键场景发挥作用，展示了从理论到实践的完整闭环。
+
+### 场景一：大模型调用的凭证管理
+当你的 Agent 需要调用多个大模型时，每个模型都需要各自的 API Key。以前你可能需要在代码里硬编码这些 Key，或者通过环境变量传递，但这样做存在安全风险且更新困难。**有了 AgentRun 的凭证管理，你只需要在平台上配置各个模型的出站凭证，给每个凭证命名**（如 `openai_key`、`qwen_key`），**然后在 Agent 配置中引用这些凭证名称。**
+
+运行时系统会自动注入实际的 Key，你的代码里完全看不到任何敏感信息。当某个模型的 Key 过期需要更新时，只需在凭证管理界面更新，几分钟后所有使用该凭证的 Agent 会通过定时健康检查自动获取新的 Key，无需修改代码或重启服务。这种体验就像是有一个智能管家在后台默默地帮你管理所有的钥匙，你只需要告诉他你要开哪扇门。
+
+```yaml
+# Agent 配置示例（伪代码）
+models:
+  - name: gpt-4
+    credential: ${credentials.openai_key}  # 引用凭证名称，不暴露实际Key
+  - name: qwen-max
+    credential: ${credentials.qwen_key}
+```
+
+### 场景二：工具调用的凭证注入
+回到之前提到的 FunctionQ 案例，这是一个更复杂但也更能体现凭证管理价值的场景。Agent 需要通过 MCP 调用 CLI 工具查询用户的函数计算资源，这些工具需要用户的 AccessKey 和 SecretKey。**关键问题是：如何在不暴露凭证给大模型的前提下，让工具能够正确调用 API？**
+
+**AgentRun 通过前置 Hook 实现了优雅的动态凭证注入。**用户在平台上配置自己的出站凭证后，Agent 调用工具时请求中只携带用户 ID，不包含任何凭证信息。前置 Hook 拦截请求，根据用户 ID 从凭证库获取对应的凭证，然后将凭证注入到环境变量或请求参数中。工具使用注入的凭证执行实际操作，后置 Hook 再清理敏感信息并记录审计日志。**整个过程中，凭证从未暴露给大模型，也不会出现在 Agent 的代码中，真正做到了安全可控。**
+
+```mermaid
+sequenceDiagram
+    participant Agent
+    participant Hook as 前置 Hook
+    participant Cache as 凭证缓存
+    participant MCP as MCP 工具
+    participant API as 函数计算 API
+    
+    Agent->>Hook: 调用工具（仅携带用户 ID）
+    Note over Agent,Hook: 请求中不包含任何凭证
+    
+    Hook->>Cache: 根据用户 ID 获取凭证
+    Cache-->>Hook: 返回 AccessKey/SecretKey
+    Note over Hook: 凭证来自定时更新的本地缓存
+    
+    Hook->>Hook: 将凭证注入到环境变量
+    Hook->>MCP: 转发请求（已注入凭证）
+    
+    MCP->>API: 调用函数计算 API
+    Note over MCP,API: 使用注入的凭证
+    
+    API-->>MCP: 返回函数列表
+    MCP-->>Hook: 返回结果
+    
+    Hook->>Hook: 清理敏感信息 + 记录审计日志
+    Hook-->>Agent: 返回安全结果
+    
+    Note over Agent,Hook: Agent 和大模型从未接触凭证
+```
+
+## 核心价值：让开发者专注业务逻辑
+AgentRun 的凭证管理系统带来的价值远不止"管理凭证"这么简单。从安全性角度看，凭证不再出现在代码和日志中，集中加密存储大幅降低泄露风险，即使某个凭证泄露也可以快速撤销和更换。从开发效率角度看，开发者不需要关心凭证如何存储、如何传递、如何更新，只需在配置中引用凭证名称，系统自动处理剩下的事情。从运维角度看，凭证更新不需要修改代码、不需要重新部署、不需要重启服务，在管理界面更新后通过定时机制自动生效。
+
+**更重要的是，凭证管理让 Agent 应用从"能用"变成"敢用"**。企业不再担心凭证泄露的风险，不再为凭证更新而头疼，不再因为安全问题而犹豫是否将 Agent 应用部署到生产环境。这种信心的建立，才是凭证管理最大的价值所在——它消除了企业拥抱 AI Agent 的最后一道顾虑，让技术真正为业务创造价值。
+