AGENT

Streamlit AGENTS.md

在这篇文章中，我将向你展示如何AGENTS.md 文件在所有部署目标中构建 Streamlit 应用。

admin

• 9 min read
Streamlit AGENTS.md

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

这就是 AGENTS.md 的用武之地。它是指导 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：一个 30 天学习系列，使用 Streamlit 和 Snowflake Cortex 教学 AI 应用开发（GitHub）。每一天的教训为聊天机器人、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 下载 Streamlit AGENTS.md 文件：

2、开始使用 Streamlit AGENTS.md

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

首先，下载 并复制 Streamlit AGENTS.md 到你的项目。

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

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

@AGENTS.md build me a chatbot using Snowflake Cortex

这里是在 Cursor 中的样子：

简而言之，AI 会：

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

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

经过片刻，AI 开始工作：

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

随后是运行应用的说明：

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

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

模式 2：引导顺序问题

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

@AGENTS.md

这里是在 Cursor 中的样子：

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

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

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

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

第二个问题：

第三个问题：

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

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

以及部署说明：

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 上不支持的功能。

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 中的 examples/ 文件夹，看看使用这个确切流程创建的聊天机器人和仪表板应用。

原文链接：Vibe code Streamlit apps with AI using AGENTS.md

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