综合介绍

RunAgent 是一个旨在解决人工智能开发中语言障碍的平台。它让开发者可以一次性地使用Python语言和任意框架编写AI智能体，然后通过平台提供的软件开发工具包（SDK），从Rust、JavaScript、Go等不同编程语言中进行原生调用。这种方式避免了直接处理REST API带来的复杂性，实现了AI智能体在不同技术项目中的无缝集成。RunAgent不仅提供了强大的本地开发环境，还规划了通往生产级别无服务器部署的明确路径。无论是在个人电脑上构建原型，还是需要扩展到支持百万级用户，RunAgent都提供了相应的工具和基础设施，帮助开发者轻松部署他们的AI智能体。它的核心理念是“一次编写，处处使用”，极大地提升了开发效率和团队协作的灵活性。

功能列表

• 通用访问：使用Python编写的AI智能体，可以通过原生SDK在任何编程语言（如Rust, JavaScript, Go）中进行调用，无需处理复杂的API接口。
• 命令行工具：提供一个功能强大的命令行界面（CLI），用于管理智能体的整个生命周期，包括项目初始化、本地开发、环境管理和一键部署。
• 多语言SDK：为Python、Rust、JavaScript/TypeScript和Go等多种语言提供原生体验的SDK，并完整支持类型安全和原生错误处理。
• 原生流式响应：在所有支持的语言中都提供原生的流式（Streaming）响应支持，让AI智能体的实时反馈在各种应用中都显得自然。
• 多种部署选项：目前支持功能齐全的本地开发服务器，具备热重载功能，适合开发、测试和自行托管。未来将推出无服务器云平台，实现自动扩缩容和按使用付费。
• 框架无关性：兼容任何Python AI框架，如LangChain、LangGraph、CrewAI或自定义框架，并为常用框架提供了预置模板。

使用帮助

RunAgent 提供了一套完整的工具集，用于部署AI智能体，并在各种应用程序中使用它们。

1. 安装

首先，通过pip安装RunAgent的命令行工具（CLI）。Python SDK会与CLI一同捆绑安装。

pip install runagent

2. 初始化项目

使用 runagent init 命令从模板创建一个新项目。RunAgent为多种主流AI框架提供了模板。

# 从LangGraph模板创建项目
runagent init my_agent --langgraph
# 从CrewAI模板创建项目
runagent init my_agent --crewai
# 创建一个最简化的项目
runagent init my_agent
```执行后，会生成一个项目目录，结构如下：

my-agent/├── init.py├── email_agent.py├── main.py└── runagent.config.json

### 3. 配置智能体
项目中最核心的文件是 `runagent.config.json`。它定义了项目的元数据和**入口点（entrypoints）**。入口点是RunAgent生态系统中最关键的概念，它指定了代码中哪些函数可以通过SDK被外部调用。
例如，我们有一个 `main.py` 文件，其中包含两个函数：
```python
from .email_agent import MockOpenAIClient
from typing import Iterator
def mock_response(message, role="user"):
"""测试一个非流式的模拟智能体"""
client = MockOpenAIClient()
prompt = [
{ "role": role, "content": message }
]
response = client.create(model="gpt-4", messages=prompt)
print(response.content)
return response.content
def mock_response_stream(message, role="user") -> Iterator[str]:
"""测试一个流式的模拟智能体"""
client = MockOpenAIClient()
prompt = [
{ "role": role, "content": message }
]
for chunk in client.create(
model="gpt-4", messages=prompt, stream=True
):
if not chunk.finished:
yield chunk.delta
else:
yield "\n[STREAM COMPLETE]"

为了让这两个函数能被外部调用，我们需要在 runagent.config.json 中定义它们：

{
"agent_name": "my-agent",
"description": "一个简单的占位智能体",
"framework": "default",
"version": "1.0.0",
"agent_architecture": {
"entrypoints": [
{
"file": "main.py",
"module": "mock_response",
"tag": "minimal"
},
{
"file": "main.py",
"module": "mock_response_stream",
"tag": "minimal_stream"
}
]
},
"env_vars": {}
}

每个入口点记录都包含：

• file: 包含入口点函数的文件的相对路径。
• module: 要暴露的函数名称。
• tag: 此入口点在项目中的唯一标识符。注意：对于流式入口点（如mock_response_stream），tag应包含 _stream 后缀以表明其流式能力。

4. 启动本地服务

配置完成后，使用 runagent serve 命令启动本地开发服务器。

# 切换到项目目录内
cd my-agent
# 启动服务
runagent serve .

该命令会启动一个本地FastAPI服务器，并提供一个agent_id、HTTP访问地址(host:port)以及用于流式传输的WebSocket端点。

5. 使用SDK调用智能体

当本地服务运行后，你可以使用不同语言的SDK来调用智能体的入口点函数。

Python SDK

Python SDK已随CLI一同安装。你可以像调用普通函数一样调用智能体。

from runagent import RunAgentClient
# 使用 agent_id 和 tag 连接到本地服务
# 注意：local=True 表示连接的是本地服务器
ra = RunAgentClient(
agent_id="<your_agent_id>", 
entrypoint_tag="minimal", 
local=True
)
# 调用函数，参数与 main.py 中定义的函数签名一致
agent_results = ra.run(
role="user", 
message="分析远程工作对软件团队的好处"
)
print(agent_results)
# 调用流式API
ra_stream = RunAgentClient(
agent_id="<your_agent_id>", 
entrypoint_tag="minimal_stream", # 注意 tag 后缀
local=True
)
for chunk in ra_stream.run(
role="user", 
message="详细分析一下远程工作的好处"
):
print(chunk, end='')

Rust SDK

use runagent::client::RunAgentClient;
use serde_json::json;
use futures::StreamExt;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
// 非流式调用
let client = RunAgentClient::new("<agent_id>", "minimal", true).await?;
let result = client.run(&[
("message", json!("帮我规划一次去日本的旅行")),
("role", json!("user"))
]).await?;
println!("Result: {}", result);
// 流式调用
let stream_client = RunAgentClient::new("<agent_id>", "minimal_stream", true).await?;
let mut stream = stream_client.run_stream(&[
("message", json!("一步步解释量子计算")),
("role", json!("user"))
]).await?;
while let Some(chunk) = stream.next().await {
print!("{}", chunk?);
}
Ok(())
}

JavaScript/TypeScript SDK

import { RunAgentClient } from 'runagent';
// 非流式调用
const ra = new RunAgentClient({
agentId: "<agent_id>",
entrypointTag: "minimal",
local: true
});
await ra.initialize();
const result = await ra.run({
role: 'user',
message: '分析远程工作对软件团队的好处'
});
console.log(result);
// 流式调用
const raStream = new RunAgentClient({
agentId: "<agent_id>",
entrypointTag: "minimal_stream",
local: true
});
await raStream.initialize();
const stream = await raStream.run({
role: 'user',
message: '写一篇关于远程工作好处的详细分析'
});
for await (const chunk of stream) {
process.stdout.write(chunk);
}

Go SDK

package main
import (
"context"
"fmt"
"log"
"time"
"github.com/runagent-dev/runagent/runagent-go/runagent"
)
func main() {
// 非流式调用
config := runagent.Config{
AgentID:       "<agent_id>",
EntrypointTag: "minimal",
Local:         true,
}
client := runagent.NewRunAgentClient(config)
ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
defer cancel()
if err := client.Initialize(ctx); err != nil {
log.Fatalf("初始化失败: %v", err)
}
result, err := client.Run(ctx, map[string]interface{}{
"role":    "user",
"message": "分析远程工作对软件团队的好处",
})
if err != nil {
log.Fatalf("运行智能体失败: %v", err)
}
fmt.Printf("结果: %v\n", result)
}

应用场景

1. 多语言技术团队在团队中，AI专家可以使用他们熟悉的Python语言来构建和维护核心AI逻辑，而前端（JavaScript/TypeScript）和后端（Rust/Go）的开发者可以通过各自语言的原生SDK直接调用这些AI功能，无需深入了解Python或AI模型的实现细节，实现了高效协作。
2. 微服务架构在一个分布式的微服务系统中，可以将AI逻辑作为一个中心化的服务来部署。其他需要AI能力的服务，无论它们是用何种语言编写的，都可以通过RunAgent方便地访问这个中心化的智能体服务，简化了系统集成。
3. 为现有系统增加AI功能对于一些使用非Python语言编写的旧有应用程序，集成最新的AI功能通常需要重写大量代码。使用RunAgent，可以为这些现有应用无缝地添加前沿的AI能力，而无需进行大规模的架构改造或代码重写。
4. 性能敏感的应用在需要高性能计算的场景中，开发者可以在Python中编写复杂的AI逻辑，然后从一个高性能的语言（如Rust或Go）中调用它。这样既利用了Python丰富的AI生态系统，又保证了应用程序的整体性能。

QA

1. RunAgent是什么？RunAgent是一个AI智能体开发和部署平台，它允许开发者用Python编写智能体，然后通过原生SDK从其他编程语言（如Rust, Go, JS）中调用，解决了AI开发中的语言壁垒问题。
2. RunAgent支持哪些AI框架？RunAgent的设计是框架无关的，可以与任何Python AI框架配合使用。它为LangGraph、CrewAI、Letta和Agno等流行框架提供了预置的项目模板，同时也支持用户自定义的框架。
3. RunAgent是免费的吗？RunAgent项目本身是开源的，并采用Elastic License 2.0 (ELv2)许可证。这意味着你可以免费地将其用于开发、测试和生产环境，也可以自由修改和分发。唯一的限制是，未经许可，不能将RunAgent作为托管服务提供给他人。
4. 什么是“入口点（entrypoint）”？入口点是RunAgent中的一个核心概念。它是在runagent.config.json文件中定义的一个配置项，用来指定你代码中的哪一个函数可以作为AI智能体的可调用接口，通过SDK暴露给外部应用程序。每个入口点都有一个唯一的tag用于识别。