> ## Content Index
> Fetch the complete content index at: https://www.hubwiz.com/blog/llms.txt
> Use this file to discover other available public pages before exploring further.

# Streamlit AGENTS.md
- URL: https://www.hubwiz.com/blog/streamlit-agents-md/
- Published: 2026-01-23T02:25:22.000Z
- Updated: 2026-01-23T02:26:32.000Z
- Description: 在这篇文章中，我将向你展示如何AGENTS.md 文件在所有部署目标中构建 Streamlit 应用。
- Author: admin
- Tags: AGENT, STREAMLIT, #Import 2026-10-14 14:41

如果你曾经使用过 Cursor、GitHub Copilot 或 Claude Code 等 AI 编码助手，你知道它们可以非常强大，但也很不一致。有时它能准确把握你的代码风格，有时它会忘记你建立的一切。

这就是 [AGENTS.md](https://agents.md/?ref=hubwiz.com) 的用武之地。它是指导 AI 编码代理的开放标准。把它想象成 AI 的 README，一个专门的文件，提供 AI 助手在你的编码项目上有效工作的上下文、约定和指令。

在这篇文章中，我将向你展示如何使用这个 `AGENTS.md` 文件在所有部署目标中构建 Streamlit 应用：本地开发、Streamlit Community Cloud 和 Streamlit in Snowflake (SiS)。

## 1、简介

AGENTS.md 是一个简单的开放格式，已被超过 60,000 个开源项目采用，包括来自 OpenAI、Apache 和 Google 的仓库。它从 AI 软件开发生态系统中的协作努力中诞生。

关键洞察是 README.md 文件是为人类设计的，而 AGENTS.md 是为 AI 代理设计的。它包含 AI 编码助手需要的详细上下文：构建命令、代码约定、测试模式和特定领域知识。

### 1.1 这些模式来自哪里

Streamlit AGENTS.md 不是理论性的。它是从现实经验中构建的：

- [**30 天 AI**](https://30daysofai.streamlit.app/?ref=hubwiz.com)：一个 30 天学习系列，使用 Streamlit 和 Snowflake Cortex 教学 AI 应用开发（[GitHub](https://github.com/streamlit/30daysofai?ref=hubwiz.com)）。每一天的教训为聊天机器人、RAG 系统、流响应和代理编排贡献了经过战斗测试的模式。
- **Streamlit 开发经验**：从 2024-2025 年构建数十个 Streamlit 应用中提炼的模式，包括数据仪表板、化学信息学工具、ML 应用和部署到 Streamlit in Snowflake 的企业应用。

AGENTS.md 中的每个模式都已在生产中验证。`AI_COMPLETE` 函数、通用连接模式、流式聊天界面：所有这些都来自在不同部署环境中解决现实问题的经验。

### 1.2 为什么这有效

AGENTS.md 方法有效因为：

1. **最小的摩擦**：一个文件引用，几个问题，完整的应用
2. **智能默认**：缓存、错误处理和 UI 组件是推断的
3. **环境感知**：自动处理 SiS vs Community Cloud 差异
4. **完整输出**：每个应用包括 app.py、requirements.txt、README.md
5. **一致模式**：每次相同的经过验证的代码模式

> 要进一步进行，从这个 [GitHub repo](https://github.com/dataprofessor/streamlit/blob/main/AGENTS.md?ref=hubwiz.com) 下载 Streamlit AGENTS.md 文件：

![](https://www.hubwiz.com/blog/content/images/2026/01/image-671.png)

## 2、开始使用 Streamlit AGENTS.md

Streamlit AGENTS.md 支持两种操作模式，使其易于上手。

首先，[下载](https://github.com/dataprofessor/streamlit/blob/main/AGENTS.md?ref=hubwiz.com) 并复制 Streamlit [AGENTS.md](https://github.com/dataprofessor/streamlit/blob/main/AGENTS.md?ref=hubwiz.com) 到你的项目。

### 模式 1：使用指令快速开始

如果你知道你想要什么，就告诉 AI：

```
@AGENTS.md build me a chatbot using Snowflake Cortex

```

这里是在 Cursor 中的样子：

![](https://www.hubwiz.com/blog/content/images/2026/01/image-672.png)

简而言之，AI 会：

- 使用你的指令作为起点
- 推断合理的默认
- 只在关键信息缺失时问 1-2 个澄清问题
- 使用所有文件构建完整的应用

这里是第一个问题和我们相应的答案：

![](https://www.hubwiz.com/blog/content/images/2026/01/image-673.png)

经过片刻，AI 开始工作：

![](https://www.hubwiz.com/blog/content/images/2026/01/image-674.png)

大约一分钟后，完成的应用程序完成，应用结构及其核心功能被总结：

![](https://www.hubwiz.com/blog/content/images/2026/01/image-675.png)

随后是运行应用的说明：

![](https://www.hubwiz.com/blog/content/images/2026/01/image-676.png)

它不止于此，你可以问后续问题来帮助你理解创建的应用：

![](https://www.hubwiz.com/blog/content/images/2026/01/image-677.png)

或者你也可以继续 vibe 代码并对应用进行增量改进。

### 模式 2：引导顺序问题

如果你不确定你需要什么，只引用文件：

```
@AGENTS.md

```

这里是在 Cursor 中的样子：

![](https://www.hubwiz.com/blog/content/images/2026/01/image-678.png)

AI 会**一次一个**引导你通过问题：

- **"你想构建什么？"** → 聊天机器人、仪表板、数据工具
- **"它将在哪里运行？"** → 本地、Community Cloud、Snowflake
- **"你的数据源是什么？"** → CSV、Snowflake、APIs
- **"哪个 LLM？"**（只有当你提到 AI 时） → Cortex 或 OpenAI

然后它构建，从应用类型推断 UI 组件并自动添加缓存。

这里是我们的第一个问题：

![](https://www.hubwiz.com/blog/content/images/2026/01/image-679.png)

第二个问题：

![](https://www.hubwiz.com/blog/content/images/2026/01/image-680.png)

第三个问题：

![](https://www.hubwiz.com/blog/content/images/2026/01/image-681.png)

就这样，它将继续构建应用：

![](https://www.hubwiz.com/blog/content/images/2026/01/image-682.png)

一旦完成，我们得到已构建内容的摘要：

![](https://www.hubwiz.com/blog/content/images/2026/01/image-683.png)

以及部署说明：

![](https://www.hubwiz.com/blog/content/images/2026/01/image-684.png)

## 3、创建什么

当你使用 AGENTS.md 构建应用时，你得到一个完整的、部署就绪的项目：

```
my_app/
├── app.py                      # 主应用
├── requirements.txt            # 带版本的依赖
├── README.md                   # GitHub 就绪文档
└── .streamlit/
    └── secrets.toml.example    # 凭证模板（如果需要）

```

每个应用包括一个 README，其中：

- **TLDR**：一句描述应用的句子
- **功能**：能力的项目符号列表
- **本地运行**：逐步命令
- **部署到 Community Cloud**：5 步指南
- **部署到 SiS**：3 步指南

不再手动创建文档！

## 4、示例应用

两个完整的示例应用使用 AGENTS.md 引导流程构建。两者都在 `examples/` 文件夹中可用。

#### 示例 1：聊天机器人

一个由 Snowflake Cortex 驱动的对话式 AI 聊天机器人。

**问答流程：**

这里是问题和答案：

- **你想构建什么？** 简单聊天机器人
- **它将在哪里运行？** Community Cloud
- **哪个 LLM？** Cortex

**创建了什么：**

```
examples/chatbot_app/
├── app.py              # 带流式的聊天界面
├── requirements.txt    # streamlit, snowflake-snowpark-python
└── README.md           # 部署说明

```

**功能：** 聊天界面、模型选择器（Claude/Llama/Mistral）、对话历史、响应缓存。

几个问题。完整的应用。准备部署。

#### 示例 2：股票仪表板

使用 Yahoo Finance 数据的一个实时股票仪表板。

**问答流程：**

这里是问题和答案：

- **你想构建什么？** 仪表板
- **它将在哪里运行？** Snowflake
- **你的数据源是什么？** yfinance

**创建了什么：**

```
examples/stock_dashboard/
├── app.py              # 带 Plotly 图表的仪表板
├── requirements.txt    # streamlit, yfinance, plotly
└── README.md           # 部署说明

```

**功能：** 烛台图表、体量分析、关键指标、时间段选择器。

三个问题。AI 知道不问 LLM（仪表板不需要它们）并自动省略 `st.set_page_config()` 以实现 SiS 兼容性，因为它是 [SiS 上不支持的功能](https://docs.snowflake.com/en/developer-guide/streamlit/limitations?ref=hubwiz.com#unsupported-streamlit-features)。

## 5、AGENTS.md 教给 AI 的关键模式

### 5.1 通用数据库连接

在所有三个部署环境中工作：

```
@st.cache_resource
def get_session():
    try:
        from snowflake.snowpark.context import get_active_session
        return get_active_session()
    except:
        from snowflake.snowpark import Session
        return Session.builder.configs(
            st.secrets["connections"]["snowflake"]
        ).create()

```

### 5.2 带 AI\_COMPLETE 的 Snowflake Cortex LLM

推荐的通用兼容性模式：

```
import json
from snowflake.snowpark.functions import ai_complete

@st.cache_data(show_spinner=False)
def call_llm(prompt: str, model: str = "claude-3-5-sonnet") -> str:
    df = session.range(1).select(
        ai_complete(model=model, prompt=prompt).alias("response")
    )
    response_raw = df.collect()[0][0]
    response_json = json.loads(response_raw)

    if isinstance(response_json, dict) and "choices" in response_json:
        return response_json["choices"][0]["messages"]
    return str(response_json)

```

### 5.3 带流式的聊天界面

```
st.session_state.setdefault("messages", [])

for msg in st.session_state.messages:
    with st.chat_message(msg["role"]):
        st.markdown(msg["content"])

if prompt := st.chat_input("Your message"):
    st.session_state.messages.append({"role": "user", "content": prompt})
    with st.chat_message("user"):
        st.markdown(prompt)

    with st.chat_message("assistant"):
        response = st.write_stream(stream_response(prompt))

    st.session_state.messages.append({"role": "assistant", "content": response})

```

### 5.4 SiS 感知代码

AI 自动知道：

- **SiS 部署** → 无 `st.set_page_config()`
- **Community Cloud** → 包括 `st.set_page_config()`
- **两者** → 使用通用连接模式

### 5.5 模式选择指南

基于你问什么，AI 选择正确的模式：

```
+-------------------------+---------------------------------------------+
| 你说                     | AI 使用                                      |
+-------------------------+---------------------------------------------+
| 聊天机器人、AI 助手       | 聊天界面 + 流式 + AI_COMPLETE                |
+-------------------------+---------------------------------------------+
| 仪表板、                  | 基本应用 + Plotly/Altair 图表                |
| 可视化                   |                                              |
+-------------------------+---------------------------------------------+
| 数据分析                 | 文件上传 + DataFrame 样式                     |
+-------------------------+---------------------------------------------+
| RAG、搜索文档            | 聊天 + Cortex 搜索 + AI_COMPLETE              |
+-------------------------+---------------------------------------------+
| 多页                     | st.navigation + 会话状态                      |
+-------------------------+---------------------------------------------+
| Snowflake、SiS          | 省略 st.set_page_config + Cortex 模式         |
+-------------------------+---------------------------------------------+

```

缓存自动添加到有益的地方。

### 5.6 防止的常见陷阱

AGENTS.md 教 AI 避免常见错误：

- 重复小部件键

```
# AI 学会总是添加唯一键
st.text_input("Name:", key="first_name")
st.text_input("Name:", key="last_name")

```

- SiS 中的页面配置

```
# AI 在针对 SiS 时省略 st.set_page_config()
# (不支持)

```

- 多页应用中的会话状态

```
# AI 在 main app.py 中初始化，不是单个页面
st.session_state.setdefault("df", None)
pg = st.navigation(...)
pg.run()

```

## 6、结束语

构建 Streamlit 应用再简单不过了。使用 AGENTS.md 文件，你可以真正 vibe 代码。只描述你想要什么，回答几个问题，看着你的应用活起来。

不是详细解释模式，经过几轮提示，希望 AI 正确理解。

使用 AGENTS.md 你得到：

- **两种模式**：快速指令或引导问题
- **顺序流程**：一次一个问题，不压倒
- **智能推断**：UI 组件和缓存自动处理
- **完整项目**：应用、requirements 和 README 准备部署
- **环境感知**：SiS 兼容内置

查看 [repo](https://github.com/dataprofessor/streamlit?ref=hubwiz.com) 中的 `examples/` 文件夹，看看使用这个确切流程创建的聊天机器人和仪表板应用。

---

原文链接：[Vibe code Streamlit apps with AI using AGENTS.md](https://blog.streamlit.io/vibe-code-streamlit-apps-with-ai-using-agents-md-04b7480f754e?ref=hubwiz.com)

汇智网翻译整理，转载请标明出处