Suna AI：开源通用 AI 代理——打造你的专属智能助手

目前，AI 技术发展正从单纯的信息处理迈向具备实际行动能力的智能体阶段。Suna AI 作为一款引人注目的开源通用 AI 代理应运而生，旨在成为能够理解自然语言指令并代表用户执行复杂现实任务的数字伙伴。

本文将介绍 Suna 的核心功能和架构，并提供了详细的分步教程，以及如何在本地设置和运行自己的实例。

免费使用 Apifox

Suna AI 是什么？

Suna AI 由 Kortix AI 开发，基于宽松的 Apache 2.0 许可证开源，其核心优势在于将强大的工具集与对话界面相结合，搭建起用户意图与实际数字操作之间的桥梁。

区别于单一功能的 AI 工具，Suna 的独特价值在于其通用性——通过对话指令驱动，它能协调多种能力完成复杂任务，从网页浏览、文件管理到代码执行、API 交互等场景均能覆盖。

浏览器自动化（通过 Playwright）：Suna 可在安全环境中启动并控制浏览器实例，支持 URL 导航、网站登录（安全存储凭证）、按钮点击、表单填写、页面滚动及数据提取，将网页资源转化为可自动化操作的智能节点。
文件系统管理：在沙箱环境中，Suna 具备创建、读取、编辑文件及目录管理能力，适用于生成报告、处理本地数据等需要文件交互的任务。
网页爬取与增强搜索：支持深度网页爬取（按链接遍历），并可集成 Tavily 等专用搜索 API，实现比传统搜索引擎更精准的信息检索，满足深度研究需求。
命令行执行：通过安全的 Docker 容器，Suna 可执行 Shell 命令，支持脚本运行、系统资源交互（限于容器权限），可配置实现软件构建、部署等自动化操作。
API 集成：无缝连接第三方 API 生态，获取金融信息等专用服务，亦可直接配置 RESTful API，无限扩展数据获取与操作能力。
代码解释器：支持在安全环境中动态生成并执行 Python 代码，实现复杂计算、数据分析及自定义逻辑处理，突破传统工具的功能边界。
Suna 的核心竞争力在于基于用户指令智能选择并编排工具链。例如，一条指令可能触发“网页搜索→数据提取→代码处理→文件生成”的完整流程，全程由 AI 自主调度，无需人工干预。

Suna 架构：核心组件解析

理解 Suna 的架构是本地部署的基础，其核心模块通过 API 协同工作：

后端 API（Python/FastAPI）：作为系统中枢，负责处理用户请求、维护对话状态、调度工具使用，并通过 LiteLLM 集成 OpenAI、Anthropic 等主流大语言模型，提供灵活的模型适配能力。
前端界面（Next.js/React）：用户交互的入口，提供聊天界面、结果展示及任务监控仪表盘，支持实时查看 AI 代理的操作日志与执行状态。
Agent Docker 环境（基于 Daytona）：每个任务在独立的 Docker 容器中运行，通过 Daytona 实现安全隔离，包含浏览器、代码解释器、文件系统等工具，杜绝与宿主系统的直接交互风险。
Supabase 数据库（PostgreSQL）：负责数据持久化，存储用户账户、对话历史、生成文件、任务状态等信息，支持高可用与安全认证。

如何部署 Suna AI

通过自主部署，你将获得完全可控的隐私保护与功能定制能力。

阶段一：前期准备

在安装 Suna 之前，你需要几个外部服务和凭证：

Supabase 项目配置

注册并创建新项目
在设置中获取 Project URL、Anon 公钥及 Service Role 秘钥
安装 Supabase CLI（安装指南）

Redis 数据库

云端方案（推荐）：使用 Upstash 等免费层级服务，记录端点、端口、密码及 SSL 配置
本地方案：通过 Homebrew（macOS）、APT（Linux）或 Docker（Windows）安装，默认端口 6379，无密码

Daytona 账户与镜像配置

注册 Daytona 并生成 API Key
前往 “Settings -> API Keys” 生成一个新的 API 密钥 。
转到 “Images” 部分，单击 “Add Image” 。
添加镜像：名称adamcohenhillel/kortix-suna:0.0.20，入口点/usr/bin/supervisord -n -c /etc/supervisor/conf.d/supervisord.conf

LLM API 密钥

选择 OpenAI 或 Anthropic，获取对应 API Key
注意特定的模型标识符（如 gpt-4o、claude-3-5-sonnet-latest）
（非必须）Tavily（增强搜索）与 RapidAPI（第三方服务集成）密钥

阶段二：安装与配置

现在，配置 Suna 应用程序组件：

克隆代码仓库

git clone https://github.com/kortix-ai/suna.git  
cd suna

后端配置（.env ）

cd backend
cp .env.example .env （如果示例缺失，则创建 .env ）
使用第一阶段的凭证编辑 .env

NEXT_PUBLIC_URL="http://localhost:3000" # Or your frontend URL if different

# Supabase
SUPABASE_URL=YOUR_SUPABASE_URL
SUPABASE_ANON_KEY=YOUR_SUPABASE_ANON_KEY
SUPABASE_SERVICE_ROLE_KEY=YOUR_SUPABASE_SERVICE_ROLE_KEY

# Redis
REDIS_HOST=YOUR_REDIS_HOST
REDIS_PORT=YOUR_REDIS_PORT
REDIS_PASSWORD=YOUR_REDIS_PASSWORD # Leave blank if none
REDIS_SSL=True # Or False for local non-SSL Redis

# Daytona
DAYTONA_API_KEY=YOUR_DAYTONA_API_KEY
DAYTONA_SERVER_URL="https://app.daytona.io/api"
DAYTONA_TARGET="us" # Or your region

# --- LLM Configuration (FILL ONLY ONE SET) ---
# Anthropic Example:
ANTHROPIC_API_KEY=YOUR_ANTHROPIC_API_KEY
MODEL_TO_USE="anthropic/claude-3-5-sonnet-latest" # Or other Claude model
OPENAI_API_KEY=
# OpenAI Example:
# ANTHROPIC_API_KEY=
# OPENAI_API_KEY=YOUR_OPENAI_API_KEY
# MODEL_TO_USE="gpt-4o" # Or other OpenAI model
# -----------------------------------------

# Optional
TAVILY_API_KEY=YOUR_TAVILY_API_KEY # Optional
RAPID_API_KEY=YOUR_RAPID_API_KEY # Optional

关键： 仅为一个 LLM 提供商（Anthropic 或 OpenAI）提供密钥。

设置 Supabase 数据库模式：

确保位于 backend 目录中
链接项目： supabase link --project-ref YOUR_PROJECT_REF_ID （从 Supabase 仪表板获取 ID）
应用迁移： supabase db push
验证 Schema： 前往 Supabase 项目仪表盘 -> Project Settings -> API -> Schema。确保 basejump 已列在“公开的 Schema”中。如果缺少，请添加并保存。

前端配置 (.env.local)

cd ../frontend
cp .env.example .env.local （或创建 .env.local ）
编辑.env.local

NEXT_PUBLIC_SUPABASE_URL=YOUR_SUPABASE_URL # 和 backend .env 里一样
NEXT_PUBLIC_SUPABASE_ANON_KEY=YOUR_SUPABASE_ANON_KEY # 和 backend .env 里一样
NEXT_PUBLIC_BACKEND_URL="http://localhost:8000/api" # 后端默认地址
NEXT_PUBLIC_URL="http://localhost:3000" # 后端默认地址

安装依赖

前端（Node.js 环境）：npm install
后端（Python 3.11+，建议虚拟环境）：

# In backend directory (use a virtual environment!)
# python -m venv venv
# source venv/bin/activate  OR .\venv\Scripts\activate (Windows)
pip install -r requirements.txt

阶段三：运行 Suna

运行后端

打开终端
导航到 path/to/suna/backend
如果使用虚拟环境，请激活（ source venv/bin/activate ）
运行： python api.py
确认服务器正在运行（端口 8000）

运行前端

打开第二个终端
导航到 path/to/suna/frontend
运行： npm run dev
确认服务器正在运行（端口 3000）

访问实例

打开浏览器访问http://localhost:3000
使用注册选项创建用户帐户（由 Supabase Auth 提供支持）
登录后即可向你的专属 Suna 代理下达指令

开发必备：API 全流程管理神器 Apifox

Suna AI 的出现标志着 AI 代理从理论走向实践的重要一步。其开源特性、强大工具集与模块化架构，为开发者和普通用户提供了可定制、可自托管的智能助手解决方案。

在部署和定制Suna的过程中，若您需要高效管理API开发、调试与协作，不妨结合 Apifox 使用。无论是开发 Suna 的自定义工具，还是优化现有 API 集成流程，Apifox都能成为提升效率的得力助手。建议在配置 Suna 的 API 交互模块（如backend/agent/tools/data_providers/目录下的代码）时，同步使用 Apifox 进行接口管理，让智能代理的开发与调试更加便捷高效。

免费使用 Apifox

通过 Suna 的开源能力与 Apifox 的工具优势相结合，开发者能更专注于构建智能化、自动化的数字工作流，真正实现“AI代理+高效工具”的生产力倍增。

Apifox 作为一个集 API 文档、API 调试、API 设计、API 测试、API Mock、自动化测试等功能于一体的 API 管理工具，Apifox 可以说是开发者提升效率的必备工具之一。

如果你正在开发项目需要进行接口调试，不妨试试 Apifox。注册过程非常简单，你可以直接在这里注册使用。

立即体验 Apifox

注册成功后可以先看看官方提供的示例项目，这些案例都是经过精心设计的，能帮助你快速了解 Apifox 的主要功能。

使用 Apifox 的一大优势是它完全兼容 Postman 和 Swagger 数据格式，如果你之前使用过这些工具，数据导入会非常方便。而且它的界面设计非常友好，即使是第一次接触的新手也能很快上手，快去试试吧！

免费使用 Apifox