企业官网建设流程全解析

Stirrup 是一个用于构建智能体（AI Agent）的轻量级 Python 框架。本教程面向零基础新手，带你用 10 分钟完成 Stirrup 的安装与配置，创建你的第一个 AI Agent，并让它联网搜索数据、自动生成图表图片。无需复杂配置，跟着做就能跑通 🚀

Stirrup 简介：构建 AI Agent 的轻量级框架

Stirrup 由 Artificial Analysis 团队开发，定位是"与模型协作而非对抗模型"——它不强制死板的工作流，而是让大模型自主选择完成任务的方式，同时内置了业界领先智能体（如 Claude Code、Codex）沉淀下来的最佳实践。

对新手来说，Stirrup 有几个非常友好的特点：

核心源码位于 src/stirrup/，其中 src/stirrup/core/agent.py 定义了 Agent 主循环，src/stirrup/tools/web.py 实现了联网搜索工具。

一键安装：Stirrup 快速安装步骤

环境要求：Python 3.12 或以上 + 一个大模型 API Key（如 OpenRouter、OpenAI、DeepSeek 等）。

安装核心框架只需一条命令：

pip install stirrup # 或使用 uv add stirrup

如果想体验全部可选组件（多模型支持、Docker 代码执行、MCP 等），可以安装完整版：

pip install 'stirrup[all]'

常用可选组件速查：

10分钟搭建你的第一个 AI Agent

完整示例见 examples/getting_started.py，核心代码不到 30 行。下面是最小可运行版本：

import asyncio from stirrup import Agent from stirrup.clients.chat_completions_client import ChatCompletionsClient async def main() -> None: # 1. 创建大模型客户端（自动读取 OPENROUTER_API_KEY 环境变量） client = ChatCompletionsClient( base_url="https://openrouter.ai/api/v1", model="anthropic/claude-opus-5", max_tokens=8_192, context_window_tokens=1_000_000, ) # 2. 创建 Agent，不传 tools 参数时自动使用内置默认工具 agent = Agent(client=client, name="agent", max_turns=15) # 3. 指定输出目录并运行任务 async with agent.session(output_dir="output/getting_started_example") as session: _finish, _history, _meta = await session.run( "查询过去3年的人口数据，联网搜索获取，" "并用 matplotlib 创建一张人口图表。" ) if __name__ == "__main__": asyncio.run(main())

搭建步骤拆解：

1. 创建客户端：ChatCompletionsClient适配所有 OpenAI 兼容 API，只需修改base_url和model即可换成 DeepSeek、OpenAI 等模型；
2. 创建 Agent：只要提供客户端和名称，Agent 就会自动加载默认工具集；
3. 运行会话：agent.session()负责工具生命周期、日志和文件输出的管理，任务完成后生成的文件会自动保存到output_dir。

联网搜索 + 生成图片：Agent 的内置默认工具

这就是 Stirrup 最惊艳的地方——你不写任何工具代码，Agent 就已经"手脚齐全"。默认工具集来自 src/stirrup/tools/init.py 中的default_tools()：

⚠️小提示：联网搜索需要在环境变量中配置BRAVE_API_KEY（从 Brave Search 官网免费申请）。没有它 Agent 依然能运行和画图，只是暂时无法主动搜索网页。

运行时会发生什么？Agent 会自主规划：先调用web_search搜索数据 → 用web_fetch抓取页面确认细节 → 再用code_exec运行 Python 代码画图 → 最后调用 finish 工具收尾。整个过程无需你干预，这就是"让模型自己选择路径"的设计哲学 🐴

解读运行结果：如何拿到生成的图片

session.run()返回三个值：

finish_params, history, metadata = await session.run("你的任务")

• finish_params：Agent 的最终回复，包含reason（完成说明）和paths（生成的文件列表，例如人口图表 PNG）；
• history：完整的对话消息历史，方便复盘 Agent 的思考过程；
• metadata：工具调用统计与 token 用量。

配合output_dir参数（示例中为output/getting_started_example），Agent 生成的图片、数据文件都会被自动落盘，直接打开查看即可。关于文件输入输出的更多细节，参考 docs/getting-started.md。

常见问题速查

Q：如何换成其他大模型？修改ChatCompletionsClient的base_url与model即可接入任意 OpenAI 兼容 API；或使用 src/stirrup/clients/litellm_client.py 中的LiteLLMClient接入 Anthropic、Google 等。

Q：Agent 跑了很多轮还没停？通过max_turns参数限制最大迭代轮数（示例设为 15）。

Q：想要浏览器操作、计算器等更多工具？可以基于default_tools()追加内置工具，或自定义Tool，教程见 docs/guides/tools.md。

下一步：继续你的 Stirrup 学习之旅

跑通第一个 Agent 只是开始，建议按这个顺序深入：

• 📖 核心概念（Agent / Session / Tool 详解）：docs/concepts.md
• 🛠️ 自定义工具指南：docs/guides/tools.md
• 🔌 MCP 服务器接入：docs/guides/mcp.md
• 📂 更多可直接运行的示例：examples/

现在，打开终端，10 分钟后你就能拥有第一个会联网、会画图、会自己干活的 AI Agent 了 🎉