安装与配置

环境要求

AgentRun Python SDK 要求 Python 版本在 3.10 或更高。建议使用虚拟环境来管理项目依赖，避免与系统 Python 环境产生冲突。您可以使用 venv、virtualenv 或 conda 等工具创建虚拟环境。

在安装 SDK 之前，请确保您已拥有阿里云账号，并已开通 AgentRun 服务。您需要准备好阿里云的 Access Key ID、Access Key Secret 和账号 ID，这些凭证将用于 SDK 与云端服务的认证。

安装依赖

使用包管理器可以快速安装 AgentRun SDK。在终端中执行以下命令即可完成基础安装：

Python
NodeJS

pip install agentrun-sdk

配置镜像

可以通过配置 PyPI 镜像，更快地安装依赖

pip install agentrun-sdk -i http://mirrors.aliyun.com/pypi/simple/

注意

要求 Python 3.10 或更高版本。

安装可选依赖

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 工具支持，可以执行：

pip install agentrun-sdk[playwright,mcp,agentscope]

对于使用 LangChain 框架并需要 HTTP 服务器功能的场景：

pip install agentrun-sdk[server,langchain]

如果您不确定需要哪些依赖，可以先安装基础版本，在遇到功能缺失时再按需补充安装。

npm
Yarn
pnpm
Bun

npm install @agentrun/sdk

yarn add @agentrun/sdk

pnpm add @agentrun/sdk

bun add @agentrun/sdk

配置镜像

可以通过配置 NPM 镜像，更快地安装依赖

npm
Yarn
pnpm
Bun

npm install @agentrun/sdk --registry=https://registry.npmmirror.com

yarn add @agentrun/sdk --registry=https://registry.npmmirror.com

pnpm add @agentrun/sdk --registry=https://registry.npmmirror.com

bun add @agentrun/sdk --registry https://registry.npmmirror.com

基础安装包含了 SDK 的核心功能，包括 Agent Runtime 管理、模型调用、凭证管理等基础能力。对于大多数简单场景，基础安装已经足够使用。

全局参数配置

安装完成后，您需要进行一些基本配置才能使用 SDK。AgentRun SDK 支持多种配置方式，包括环境变量、代码配置和配置文件，您可以根据实际场景选择合适的方式。

AgentRun SDK 支持如下配置，可以通过多种方式注入程序

Config 配置项	环境变量	说明
`access_key_id`	`AGENTRUN_ACCESS_KEY_ID`、`ALIBABA_CLOUD_ACCESS_KEY_ID`	Access Key ID
`access_key_secret`	`AGENTRUN_ACCESS_KEY_SECRET`、`ALIBABA_CLOUD_ACCESS_KEY_SECRET`	Access Key Secret
`security_token`	`AGENTRUN_SECURITY_TOKEN`、`ALIBABA_CLOUD_SECURITY_TOKEN`	STS Token
`account_id`	`AGENTRUN_ACCOUNT_ID`、`FC_ACCOUNT_ID`	账号 ID
`token`		请求数据链路时，使用的 token
`region_id`	`AGENTRUN_REGION`、`FC_REGION`	区域
`timeout`
`read_timeout`
`control_endpoint`	`AGENTRUN_CONTROL_ENDPOINT`	控制端点
`data_endpoint`	`AGENTRUN_DATA_ENDPOINT`	数据端点
`devs_endpoint`	`DEVS_ENDPOINT`	Devs 端点
	`AGENTRUN_SDK_DEBUG`	开启 DEBUG 日志
`headers`		发送请求时，附加的头部

要访问您在云上的 AgentRun 资源，需要配置阿里云的密钥。通常您的密钥为 ACCESS_KEY_ID 和 ACCESS_KEY_SECRET。当使用 AssumeRole 方式生成临时密钥时，还会存在 SECURITY_TOKEN。如果您只需要访问数据链路，也可以仅配置 AgentRun Token

通过 .env 配置
通过 export 配置
通过代码配置

.env 是一个特殊的文件，用来约定程序运行需要的环境变量。将您的 Agent 需要的环境变量写入在 .env 后，SDK 会自动读取 .env 的配置。这样既方便管理，又避免了在代码中硬编码敏感信息。

注意

请确保将 .env 文件添加到 .gitignore，避免误提交到版本控制系统，导致敏感信息泄漏。

.env
AGENTRUN_ACCESS_KEY_ID="LT*************"
AGENTRUN_ACCESS_KEY_SECRET="DU*************"
AGENTRUN_ACCOUNT_ID="143*********149"
AGENTRUN_REGION="cn-hangzhou"

如果仅仅是一次性配置环境变量，也可以在终端中临时进行配置环境变量

使用该方式，仅有 ./start 可以访问到环境变量

AGENTRUN_ACCESS_KEY_ID="LT*************" AGENTRUN_ACCESS_KEY_SECRET="DU*************" ./start

使用该方式，当前 shell 及子进程中均能访问到环境变量

export AGENTRUN_ACCESS_KEY_ID="LT*************"
export AGENTRUN_ACCESS_KEY_SECRET="DU*************"

./start

您也可以在代码中直接创建 Config 对象来全局参数配置。这种方式适合需要动态切换配置的场景：

创建的 Config 对象可以在调用 SDK API 时作为参数传入。如果同时存在环境变量配置和代码配置，SDK 会优先使用代码中显式传入的配置。

对于需要支持多账号或多区域的应用，可以创建多个 Config 对象并在调用时指定。例如，某些操作在国内区域执行，某些操作在海外区域执行。

Python
NodeJS

from agentrun.utils.config import Config

config = Config(
    access_key_id="LT*************",
    access_key_secret="DU*************",
)

import { Config } from '@agentrun/sdk';

const config = new Config({
  accessKeyId: 'LT*************',
  accessKeySecret: 'DU*************',
});

从本地到云上

在部署到 AgentRun 时，您可以在 Agent Runtime 配置环境变量来替代您在本地 .env。

为了增强安全性，可以通过配置角色的方式来替代 AGENTRUN_ACCESS_KEY_ID 等环境变量，AgentRun 在启动您的 Agent 时，会根据角色权限为您创建临时的密钥并注入在环境变量中。

验证安装

完成安装和配置后，建议运行一个简单的测试脚本来验证 SDK 是否正常工作。创建一个 Python 文件并输入以下代码：

Python
NodeJS

from agentrun.agent_runtime import AgentRuntime

# 列出所有 Agent Runtime
runtimes = AgentRuntime.list()
print(f"找到 {len(runtimes)} 个 Agent Runtime")

import AgentRuntime from '@agentrun/sdk';

// 列出所有 Agent Runtime
const runtimes = AgentRuntime.list();
console.log(`找到 ${runtimes.length} 个 Agent Runtime`);

执行这个脚本,如果能成功输出而没有报错,说明 SDK 已正确安装并配置。如果遇到认证错误,请检查您的 Access Key 配置是否正确;如果遇到网络错误,请检查您的网络连接和防火墙设置。

完成所有验证后,您就可以开始使用 AgentRun SDK 开发 Agent 应用了。

环境要求​

安装依赖​

全局参数配置​

验证安装​

环境要求

安装依赖

全局参数配置

验证安装