企业官网建设流程全解析

OpenHands Software Agent SDK是 OpenHands 推出的开源 Python SDK，专为构建「能与代码打交道的 AI Agent」而设计。它提供 Python、TypeScript 和 REST 三层 API，让你可以快速搭建可执行终端命令、编辑文件、追踪任务的智能体。无论你是想给仓库自动生成 README，还是做依赖升级、代码重构，这套 Agent SDK 都能帮你把任务交给 AI 自动完成。本文将带你 10 分钟内跑通第一个 AI Agent。

为什么选择 OpenHands Software Agent SDK

如果你正在寻找一个开源、模块化、可落地的 AI Agent 框架，OpenHands SDK 有几个突出的优势：

• 🧩模块化设计：核心 SDK、内置工具、工作空间、Agent Server 分层清晰，按需取用
• 🐍多语言支持：Python SDK 为主，附带浏览器兼容的 TypeScript 客户端
• 🏃即插即用的工具生态：终端、文件编辑、任务追踪、浏览器操作等工具开箱即用
• ☁️本地或远程运行：Agent 可以直接在你的机器上工作，也可以通过 Agent Server 跑在 Docker/Kubernetes 的临时沙箱里
• 🏆生产级验证：它是 OpenHands CLI 和 OpenHands Cloud 的底层引擎，SWE-bench 得分 77.6

整个仓库是一个 monorepo，结构如下（详见 DEVELOPMENT.md）：

software-agent-sdk/ ├── openhands-sdk/ # 核心 SDK 包（Agent、Conversation、LLM） ├── openhands-tools/ # 内置工具（终端、文件编辑器等） ├── openhands-workspace/ # 工作空间管理（Docker、Apptainer 等） ├── openhands-agent-server/ # Agent 服务器（REST/WebSocket API） ├── examples/ # 官方示例（本次上手的最佳素材） └── tests/ # 测试套件

环境准备：一键安装 SDK 依赖

安装步骤

1. 确保已安装 Python 3.12+ 和 uv 包管理器
2. 克隆仓库（仅本地开发时需要；如果只是调用 API，通过 pip 安装即可）：

git clone https://gitcode.com/gh_mirrors/so/software-agent-sdk cd software-agent-sdk

3. 一条命令配置开发环境（会自动安装所有依赖并配置 pre-commit hooks）：

make build

💡make build等价于执行uv sync --dev，仓库根部的 pyproject.toml 通过uvworkspace 管理四个 Python 包的依赖。

配置 LLM API Key

SDK 通过环境变量读取大模型配置，运行示例前请设置好：

export LLM_API_KEY="你的API密钥" # 必需 export LLM_MODEL="gpt-5.5" # 可选，默认 gpt-5.5 export LLM_BASE_URL="" # 可选，自定义 API 端点

10分钟跑通第一个 AI Agent：Hello World

打开官方示例 01_hello_world.py，完整代码如下：

import os from openhands.sdk import LLM, Agent, Conversation, Tool from openhands.tools.file_editor import FileEditorTool from openhands.tools.task_tracker import TaskTrackerTool from openhands.tools.terminal import TerminalTool llm = LLM( model=os.getenv("LLM_MODEL", "gpt-5.5"), api_key=os.getenv("LLM_API_KEY"), base_url=os.getenv("LLM_BASE_URL", None), ) agent = Agent( llm=llm, tools=[ Tool(name=TerminalTool.name), Tool(name=FileEditorTool.name), Tool(name=TaskTrackerTool.name), ], ) conversation = Conversation(agent=agent, workspace=os.getcwd()) conversation.send_message("Write 3 facts about the current project into FACTS.txt.") conversation.run() print("All done!")

运行它：

uv run python examples/01_standalone_sdk/01_hello_world.py

几分钟后，你会在目录里看到 Agent 自己创建的FACTS.txt—— 恭喜，你的第一个 AI Agent 已经跑起来了！🎉

看懂 SDK 四大核心概念：LLM、Agent、Tool、Conversation

上面的代码只有 30 行，但恰好覆盖了 SDK 的四大核心组件：

1. LLM：大模型配置

LLM对象封装了模型、API Key、端点等配置，基于 LiteLLM 实现，因此兼容 OpenAI、Anthropic、Google 等主流提供商（源码位于 openhands-sdk/openhands/sdk/llm/）。它还内置了重试、超时、成本统计等能力，运行后可以通过llm.metrics.accumulated_cost查看本次对话的累计花费。

2. Agent：智能体的「大脑」

Agent是 LLM 与工具的桥梁，负责决定何时调用哪个工具。它被设计为不可变（frozen）的 Pydantic 模型，同一个 Agent 实例可以被多个 Conversation 安全共享（见 openhands-sdk/openhands/sdk/agent/agent.py）。

3. Tool：Agent 的「双手」

工具赋予 Agent 实际操作的能力。内置工具都放在 openhands-tools/ 下，常用的有：

4. Conversation：对话即工作流

Conversation是任务执行的容器，把 Agent、工作空间（workspace参数指定目录）绑定在一起：

• send_message("...")—— 发送一条用户指令
• run()—— 驱动 Agent 循环执行，直到任务完成
• 可以反复send_message+run，实现多轮迭代

进阶玩法：从 Demo 到生产级 Agent

跑通 Hello World 后，推荐按下面顺序深入官方示例，每个都是可直接运行的完整脚本：

🛠️ 编写自定义工具

参考 02_custom_tools.py，学习如何定义Action/Observation、实现ToolExecutor，并用register_tool()注册一个自己的 Grep 工具。自定义工具是扩展 Agent 能力的核心手段。

✅ 开启确认模式（安全护栏）

让 Agent 执行危险操作前先征得你同意：参考 04_confirmation_mode_example.py，通过conversation.set_confirmation_policy(AlwaysConfirm())开启，Agent 每次执行动作前会暂停等待yes/no，拒绝时调用reject_pending_actions()让 Agent 换思路。

🧠 用 Skills 定制 Agent 行为

03_activate_skill.py 演示了AgentContext的 Skills 机制：可以注入始终生效的指令、按关键词触发的技能，甚至load_public_skills=True一键加载公共技能市场（例如自动识别uv.lock项目并注入 uv 包管理指南）。

🌐 远程 Agent Server：把 Agent 关进沙箱

本地运行适合小任务；生产环境建议把 Agent 跑在隔离沙箱中。参考 01_convo_with_local_agent_server.py，用RemoteConversation连接 Agent Server，通过 WebSocket 实时接收事件流。Agent Server 源码位于 openhands-agent-server/，支持 Docker、Apptainer、Kubernetes（Agent Sandbox）等多种运行方式。

🔄 异步场景集成

如果你的服务基于 FastAPI 等异步框架，11_async.py 演示了如何用回调把同步的conversation.run()平滑嵌入asyncio事件循环。

示例目录导航：按需取用

examples/目录按场景组织了 59+ 个可运行示例，是最有价值的学习材料：

每个示例都能通过uv run pytest tests/examples/test_examples.py --run-examples统一验证，跟着代码注释走一遍即可完成深度学习。

常见问题速查

Q：Agent 运行时花费如何控制？A：LLM 对象内置成本统计，llm.metrics.accumulated_cost返回累计花费；也可通过LLMProfileStore管理多套模型配置（参考 37_llm_profile_store/）。

Q：如何防止 Agent 执行危险命令？A：三管齐下——确认模式（AlwaysConfirm）、LLM 安全分析器（LLMSecurityAnalyzer）、可配置安全策略（参考 32_configurable_security_policy.py 与 47_defense_in_depth_security.py）。

Q：支持哪些模型？A：只要 LiteLLM 支持的模型都可以，常见模型如gpt-5.5、claude-*、gemini-*等，通过LLM(model=...)传入即可；多模型路由见 19_llm_routing.py。

Q：可以恢复中断的对话吗？A：可以。SDK 提供事件持久化机制，参考 10_persistence.py 和 48_conversation_fork.py（对话分叉）。

总结：你的 Agent 开发路线

回顾一下这篇文章的 10 分钟上手路径：

1. ✅make build一键安装依赖
2. ✅ 配置LLM_API_KEY环境变量
3. ✅ 运行 01_hello_world.py 得到第一个 Agent
4. 📖 学习 LLM / Agent / Tool / Conversation 四大概念
5. 🚀 深入examples/目录，按业务场景选型

OpenHands Software Agent SDK 把「让 AI 动手干活」这件事做到了工程化：从本地脚本到云端沙箱，从单 Agent 到多 Agent 委派，都有一套清晰的抽象。现在就动手跑通你的第一个 AI Agent 吧！