基于 openai-agents-python 与 Daytona 沙箱构建 NASA 支出 Text-to-SQL 多轮对话 Agent【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python本篇技术指南围绕仓库examples/sandbox/extensions/daytona/usaspending_text2sql/中的完整示例展开它展示如何用 openai-agents-python 的SandboxAgent、自定义Capability、Daytona 云端沙箱构建一个能把自然语言问题翻译成 SQL、在只读 SQLite 上执行并返回结构化表格的多轮对话 Agent。读完本文你将掌握沙箱 Agent 的 Manifest 构建、带纵深防御护栏的 SQL 工具封装、会话暂停/恢复、Compaction 长会话压缩与 Memory 跨会话记忆等一整套可复用的工程模式。一、示例概览一个文本转 SQL沙箱 Agent 的完整骨架1.1 示例是什么该示例实现了一个多轮对话式数据分析 Agent用户用自然语言提问如What are NASAs top 10 contractors by total spending?Agent 将其翻译为 SQL在一个本地沙箱内SQLite 数据库上执行并返回结构化的表格结果。数据源为美国联邦政府公开支出平台 USAspending.gov 上的 NASA 支出数据。其核心价值在于LLM 只负责写 SQL执行与安全由沙箱与自定义工具保证——这是生产级 text-to-SQL 应用的标准分工。1.2 目录结构与架构原文档给出了清晰的架构图对应的仓库目录结构为examples/sandbox/extensions/daytona/usaspending_text2sql/ ├── agent.py — SandboxAgent 定义 交互式 REPL 入口 ├── sql_capability.py — SqlCapabilityCapability 子类提供 run_sql 工具与护栏 ├── setup_db.py — 在沙箱内运行从 USAspending API 拉取数据、构建 SQLite 库 ├── schema/ │ ├── overview.md — 精简 schema 摘要注入到 instructions 中 │ ├── glossary.md — USAspending 官方术语表setup_db.py 自动抓取 │ └── tables/ │ └── spending.md — spending 表的逐列说明按需通过 Shell 读取 └── README.md三个核心文件各自承担独立职责见 agent.py、sql_capability.py、setup_db.py。二、工作原理六大关键机制原文档总结了该 Agent 的六条工作原理这里结合源码逐一展开Schema 知识注入Agent 的系统提示词instructions中直接嵌入精简的 schema 摘要即 schema/overview.md 的全部内容同时在 Manifest 中挂载schema目录Agent 可按需读取 schema/tables/spending.md 获取逐列文档、读取 schema/glossary.md 获取官方术语定义。这避免了把整份表结构塞进提示词导致 token 浪费实现精要进提示词、细节按需取。SQL 执行与护栏自定义SqlCapability提供run_sql工具具备只读模式、语句校验、行数限制、查询超时等护栏详见第五节。多轮对话Agent 跨轮保留上下文通过Runner.run_streamed与result.to_input_list()维护会话历史因此可以追问break that down by year或just the top 5。Compaction使用Compactioncapability 自动把较早的对话上下文总结压缩使长会话保持在模型上下文窗口内。暂停/恢复Pause/Resume输入exit暂停沙箱并退出再次运行脚本会重连同一暂停沙箱无需重新下载数据。若沙箱无法重连被删除或过期自动新建沙箱并重建数据库。跨会话记忆Memory使用Memorycapability 从每次对话中提取经验如好用的 SQL 模式、数据注意事项整合为结构化文件后续会话开始时 Agent 自动带上此前对话的上下文。2.1 从源码看 Agent 的组装在 agent.py 的build_agent()中Agent 被组装为SandboxAgent默认模型为gpt-5.6-soldefault_manifest声明工作区布局setup_db.py由本地文件映射进沙箱LocalFileschema目录整体映射LocalDirdata为ephemeral临时目录用于存放构建出的 SQLite 库memories/下预置MEMORY.md、memory_summary.md、phase_two_selection.json三个空文件供 Memory capability 使用capabilities依次挂载SqlCapability(db_pathdata/usaspending.db)、Shell()、Compaction()、Memory(...)。Manifest 正是沙箱蓝图它决定了沙箱里一开始有什么文件、哪些目录是临时的是实现可复现工作区的关键抽象。2.2 开发者指令DEVELOPER_INSTRUCTIONSagent.py 中的开发者指令值得逐条细读它本质上是一份SQL 分析 Agent 的行为规范一律使用run_sql查询数据库绝不直接运行 sqlite3需要列细节时读取schema/tables/文档需要术语定义时读取schema/glossary.md例如区分 obligation 与 outlay优先用聚合GROUP BY、SUM、COUNT、AVG而不是返回大量原始行最终回答中金额要用美元符号与千分位格式化如 $1,234,567面对追问时结合上下文理解按年拆分、只看前 5这类指代查询失败时读错误信息并尝试修正 SQL简要解释查询逻辑便于用户验证正确性。另外还内置了数据注意事项data caveats这是 text-to-SQL 应用中容易被忽视却极其重要的一环数据库存的是obligations法律承诺的拨款义务而非 outlays实际支付用户问spending时需澄清是 obligation 金额金额绑定action_date义务签署日而非实际执行时间多年期合同可能整笔落在签署财年部分收款方因隐私被掩码为 MULTIPLE RECIPIENTS 或 REDACTED DUE TO PII做收款方分析时应说明数据不完整。这些 caveats 的存在能让 Agent 的回答显著减少看似正确实则误导的情况。三、运行前准备与快速启动3.1 前置条件原文档列出的前置条件如下均以当前仓库实际内容为准Python 3.12安装带 Daytona 支持的openai-agents在仓库根目录执行uv sync --extra daytonaDaytona 沙箱示例依赖可选 extra见 agent.py 中导入失败时的报错提示设置OPENAI_API_KEY环境变量用于 LLM设置DAYTONA_API_KEY环境变量用于沙箱服务沙箱内需要互联网访问首次运行时要在沙箱内建库。agent.py 中的_require_env()会在缺少任一必需环境变量时直接以清晰报错退出。3.2 启动命令从仓库根目录执行export OPENAI_API_KEYsk-... export DAYTONA_API_KEY... uv run python -m examples.sandbox.extensions.daytona.usaspending_text2sql.agent启动流程对应 agent.py 的main()校验两个 API Key构建 Agent 蓝图build_agent()创建DaytonaSandboxClient并配置DaytonaSandboxClientOptions(pause_on_exitTrue, exposed_ports(8080,))尝试从本地.session_state.json恢复上次暂停的沙箱client.resume()失败则新建在沙箱内执行python3 setup_db.py首次建库可耗时数分钟执行超时上限 1800 秒在沙箱内启动results目录上的 HTTP 文件服务器nohup python3 -m http.server 8080 ...并通过sandbox.resolve_exposed_port(8080)解析出可下载的签名 URL进入交互式 REPL。3.3 首次运行的自动建库数据库在首次运行时于沙箱内自动构建要求沙箱有网络后续运行直接复用已有数据库。建库由 setup_db.py 完成其设计是幂等的数据库已存在且覆盖全部请求财年时直接跳过除非传--force详见下文第四节。3.4 示例提问进入 REPL 后可直接尝试原文档给出的示例问题 What are NASAs top 10 contractors by total spending? Break that down by fiscal year Which NASA centers award the most contracts? Show me grants to universities in California How has NASA spending changed over time? What are the largest individual awards in the last 3 years? Compare contract vs grant spending by year终端还支持两个控制命令输入exit暂停沙箱并退出输入destroy则删除沙箱会跳过内存刷新、删除本地 session state。此外设置EXAMPLES_INTERACTIVE_MODEauto可让示例以自动化模式运行自动输入默认问题后退出相关实现见 examples/auto_mode.py。四、数据层USAspending 数据库的构建与结构4.1 setup_db.py 如何工作setup_db.py 被设计为在只有 Python 标准库的沙箱环境中运行通过 USAspending bulk download API 拉取数据、解析 CSV、构建本地 SQLite 库。其命令行参数python setup_db.py [--force] [--start-fy 2021] [--end-fy 2025]--start-fy/--end-fy首/末财年默认 2021–2025--start-fy --end-fy时报错--force即使库已存在也强制重建。关键实现细节财年换算联邦财年为 10 月 1 日至次年 9 月 30 日fiscal_year_dates()负责换算如 FY2024 2023-10-01 至 2024-09-30分年并发拉取bulk download API 的日期范围限制为 1 年因此脚本按财年逐个提交请求且一次性并发提交全部财年ThreadPoolExecutor让服务端打包最慢环节并行进行再统一轮询状态、下载解压奖助类型代码映射setup_db.py合同类代码 A/B/C/D →contract援助类 02–05 →grantIDV_* →idv兜底按award_id前缀CONT_IDV_判断或归为otherCSV 类型探测依据表头中contract_award_unique_key/assistance_award_unique_key区分合同与援助 CSV两类 CSV 的列名映射独立维护合同列含recipient_parent_name、extent_competed等援助列含cfda_number、business_types_description等见 setup_db.py自动抓取术语表通过 glossary API 拉取 USAspending 官方术语示例当前为 149 条写入 schema/glossary.md索引优化建表 SQL 中为award_id、fiscal_year、award_type、recipient_name、recipient_parent_name、recipient_state、action_date、naics_code、federal_action_obligation、extent_competed、period_of_perf_start、awarding_office等列创建索引保障聚合查询性能见 setup_db.py完整性校验建库完成后校验库中是否覆盖全部请求财年缺失则报错并清理。4.2 spending 表结构数据库使用单张spending表每一行是一条交易记录obligation、modification 或 de-obligation同一联邦 award 的多条交易共享award_id。核心列完整逐列文档见 schema/tables/spending.md列含义award_id唯一 award 标识多条交易共享award_piid_fain可读的合同号PIID或援助号FAINparent_award_piid父级 IDV 合同号任务单关联合同载体仅合同award_typecontract/grant/idv/otheraction_date交易日期YYYY-MM-DDfiscal_year联邦财年10 月–次年 9 月federal_action_obligation本笔交易金额de-obligation 为负total_obligation交易时点的 award 累计义务额base_and_all_options_value含未行使选项的合同总上限仅合同recipient_name/recipient_parent_name收款方 / 母公司子公司归并仅合同recipient_state/city/country收款方位置awarding_office/funding_officeNASA 中心/办公室如 GODDARD SPACE FLIGHT CENTERnaics_code/psc_code及描述行业 / 产品服务分类extent_competed/type_of_set_aside/number_of_offers/contract_pricing_type竞争程度、小企业预留、报价数、定价类型仅合同business_types援助类收款方类型仅 grantsdescription交易自由文本描述该文档还标注了几条对写 SQL 至关重要的坑Notes按 award 聚合要用GROUP BY award_idSUM(federal_action_obligation)而非直接读total_obligation快照base_and_all_options_value是上限而total_obligation才是实际承诺额母公司归并使用COALESCE(NULLIF(recipient_parent_name, ), recipient_name)recipient_name同一实体可能存在拼写差异需用LIKE或UPPER()模糊匹配psc_code一列同时存放合同 PSC 与援助 CFDA 两套分类系统。4.3 常见查询模式schema/overview.md 提供了可直接复用的参考 SQL-- 按财年统计总支出 SELECT fiscal_year, SUM(federal_action_obligation) AS total FROM spending GROUP BY fiscal_year ORDER BY fiscal_year; -- 头部收款方按母公司归并 SELECT COALESCE(NULLIF(recipient_parent_name, ), recipient_name) AS entity, SUM(federal_action_obligation) AS total FROM spending GROUP BY entity ORDER BY total DESC LIMIT 10; -- 按 award 类型统计 SELECT award_type, COUNT(*), SUM(federal_action_obligation) AS total FROM spending GROUP BY award_type; -- 竞争 vs 单一来源合同 SELECT extent_competed, COUNT(DISTINCT award_id) AS awards, SUM(federal_action_obligation) AS total FROM spending WHERE award_type contract GROUP BY extent_competed ORDER BY total DESC; -- 按 NASA 中心统计 SELECT awarding_office, SUM(federal_action_obligation) AS total FROM spending GROUP BY awarding_office ORDER BY total DESC;这些模式正是被注入提示词的精华 schema让 Agent 一上来就掌握正确的聚合口径。五、SqlCapability带纵深防御护栏的 SQL 执行工具5.1 Capability 机制SqlCapability继承自 SDK 的Capability基类src/agents/sandbox/capabilities/capability.py。从 sql_capability.py 可见其结构type: Literal[sql] sql声明能力类型可配置字段db_path默认data/usaspending.db、max_display_rows默认 100、max_csv_rows默认 10,000、timeout_seconds默认 30.0、results_dir默认resultsbind(session)在运行时绑定沙箱会话tools()返回run_sql工具instructions(manifest)返回注入给 Agent 的能力级指令强调一律用run_sql、写标准 SQLite SQL、优先聚合、最多展示 100 行但最多 10,000 行存入可下载 CSV、金额以 REAL 美元存储等。这种能力即插即用的抽象让 SQL 能力可以在不同沙箱后端、不同 Agent 之间复用——这正是原文档强调agent 与 capability 定义与后端无关的含义。5.2 run_sql 工具_make_run_sql_tool()sql_capability.py通过tool装饰器name_overriderun_sql构造一个FunctionTool其执行方式很有意思不在 SDK 进程内连数据库而是把查询通过session.exec()送进沙箱内执行命令形如printf %s query | python3 -c query runner 脚本 db_path display_limit max_csv_rows results_dirlimit参数取max(1, min(limit or max_display_rows, max_display_rows))即 0 与 None 都走默认值查询超时ExecTimeoutError/TimeoutError会返回Query timed out after 30s. Try a simpler query or add a LIMIT.这样的模型可读错误促使 Agent 自我修正。5.3 五层纵深防御护栏这是本示例最值得借鉴的部分——纵深防御defense in depth。原文档列出 5 层结合 sql_capability.py 中沙箱内执行的_QUERY_RUNNER_SCRIPT可逐一对应连接级只读SQLite 以 URIfile:{db_path}?modero打开——连接层面即为只读PRAGMA 兜底连接后立即PRAGMA query_only ON即使绕过语句校验也无法写入语句级校验只允许SELECT、WITH、EXPLAIN、PRAGMA开头的语句按首个 token 判断其余直接拒绝并返回错误行数硬上限默认展示上限 100 行同时最多 10,000 行写入 CSVfetchmany(csv_limit 1)探测是否截断返回 JSON 中的truncated字段标记截断超时查询在 30 秒后被终止session.exec的 timeout 参数。最终工具返回结构化的 JSON{columns: [...], rows: [...], row_count: N, display_count: M, truncated: bool, csv_file: query_ts_pid.csv, note: ...}。展示给模型的行数被严格限制但完整结果以 CSV 形式落盘供下载——兼顾模型上下文省 token与用户拿全量数据两个诉求。5.4 超时、截断与 CSV 下载当结果超过展示上限时工具返回的note会明确告知Showing X of Y rows. Full result saved to CSV.CSV 文件写入results/目录文件名带时间戳与 PID再由 agent.py 中沙箱内的 HTTP 文件服务器通过 Daytona 暴露端口提供给用户浏览器下载。终端若判定表格过宽超出os.get_terminal_size()也会提示too wide to print in terminal, download below并附上下载链接。六、多轮对话 REPL 与流式输出6.1 流式运行与会话历史REPL 核心在run_turn()agent.py每轮把conversation历史与新的用户问题拼成input_items调用Runner.run_streamed(agent, input_items, run_configrun_config)用result.stream_events()消费事件流raw_response_event中的ResponseTextDeltaEvent直接打印增量文本实现打字机效果tool_called/tool_output事件则交给格式化函数展示轮末用result.to_input_list()生成下一轮输入——SDK 内置的序列化能正确处理各类 item 类型这是多轮对话上下文不丢失的关键。6.2 工具调用与结果的终端格式化agent.py 中的格式化助手很有工程参考价值_highlight_sql()用正则给 SQL 做 ANSI 语法高亮——关键字、函数、字符串分别着色先暂存字符串字面量避免内部内容被误染_format_tool_args()对run_sql的调用参数做 pretty-print显示[SQL]与可选(limit N)_format_tool_result()解析工具返回的 JSON把结果渲染成对齐的 ASCII 表格列宽按内容自适应并在展示行数少于总行数或 CSV 被截断时给出摘要说明。这套输出层设计让用户在终端里就能获得类似数据库客户端的阅读体验而 Agent 模型拿到的则是紧凑的 JSON——展示层与模型输入层解耦。6.3 交互命令REPL 循环agent.py支持exit暂停沙箱、保存会话状态与记忆、退出destroy删除沙箱、跳过内存刷新空输入直接跳过单轮异常捕获后继续会话。自动模式下EXAMPLES_INTERACTIVE_MODEauto使用默认问题What are NASAs top 5 contractors by total obligations?单轮运行后退出。七、Compaction 与 Memory长会话与跨会话记忆7.1 Compaction长会话压缩Compaction()能力用于在会话过长时自动总结较早的上下文从而把长对话维持在模型上下文窗口内。其默认压缩阈值为 240,000 token见 src/agents/sandbox/capabilities/compaction.py 中_DEFAULT_COMPACT_THRESHOLD并内置常见模型的上下文窗口映射表用于判断何时需要压缩。对本示例而言用户可能连续追问几十轮分析Compaction 保证了会话可持续而不溢出。7.2 Memory跨会话经验沉淀Memory能力实现见 src/agents/sandbox/capabilities/memory.py在本示例中的配置agent.py为readMemoryReadConfig(live_updateFalse)会话开始时读取memories/memory_summary.md注入上下文generateMemoryGenerateConfig(extra_prompt...)每次会话结束后在后台从对话中提取经验并写入memories/MEMORY.md汇总文件上限 15,000 token见 memory.py 中_MEMORY_SUMMARY_MAX_TOKENS。extra_prompt明确引导模型沉淀哪些 SQL 模式在 USAspending 数据上最好用、列的特殊性如按 recipient_parent_name 而不是 recipient_name 分组、用户发现的数据注意事项负 obligation、掩码收款方。这使 Agent 在多次会话后越来越懂这份数据——新会话无需从零摸索。八、会话暂停/恢复与审计日志8.1 会话状态持久化暂停/恢复通过把DaytonaSandboxSessionState序列化到本地文件实现agent.py_save_session_state()把sandbox.state.model_dump_json(indent2)写入.session_state.json启动时_load_session_state()读取并model_validate_json还原随后client.resume(saved_state)重连若sandbox.state.sandbox_id与旧 ID 不一致说明旧沙箱已不存在则自动新建状态在沙箱启动后立即持久化避免崩溃导致沙箱成为孤儿资源。退出时若为destroy模式会置pause_on_exitFalse并删除本地状态文件后停机否则保存状态并调用sandbox.aclose()内部先保存记忆再暂停可能耗时数分钟。8.2 审计日志所有沙箱操作exec 调用、启动/停止、SQL 查询及其结果通过 SDK 的Instrumentation与JsonlOutboxSink以结构化 JSONL 事件追加写入.audit_log.jsonlagent.pyinstrumentation Instrumentation( sinks[JsonlOutboxSink(AUDIT_LOG_PATH)], payload_policyEventPayloadPolicy(include_exec_outputTrue), )include_exec_outputTrue意味着连执行输出都记录在内。这对调试、回放会话、或审计Agent 到底执行了哪些 SQL极为有用——在需要合规与可追溯的 text-to-SQL 场景中这条日志是标配。九、沙箱后端Daytona 集成本示例以 Daytona 作为沙箱后端。agent与capability的定义是后端无关的但入口 agent.py 硬编码了DaytonaSandboxClient与 Daytona 特有功能pause/resume、exposed ports、签名下载 URL。相关组件DaytonaSandboxClient沙箱生命周期管理create/resume/start/stop/shutdown/aclose来自agents.extensions.sandboxDaytonaSandboxClientOptions(pause_on_exitTrue, exposed_ports(RESULTS_PORT,))配置暂停策略与暴露端口8080 用于结果文件下载WORKSPACE_ROOT DEFAULT_DAYTONA_WORKSPACE_ROOT沙箱工作区根目录沙箱内执行setup_db.py时要求沙箱具备网络访问能力。仓库另有一个最小化的 Daytona 沙箱验证示例 examples/sandbox/extensions/daytona/daytona_runner.py展示了更基础的用法Manifest构建含可选 S3 云桶挂载、SandboxAgentWorkspaceShellCapability、以及--pause-on-exit/--stream等 CLI 参数可作为理解本示例的入门对照。Daytona 扩展的完整实现位于 src/agents/extensions/sandbox 下。十、扩展思路把该模式复用到其他数据集该示例的最大价值在于其可迁移的工程模式。将其改造成其他数据集的 text-to-SQL Agent通常只需四步换数据替换setup_db.py或直接挂载已有的 SQLite 文件保持幂等建库约定换 schema 文档重写 schema/overview.md 与 schema/tables/ 下的逐表文档并同步更新 instructions 中的数据 caveats——这是 Agent 查询质量的命脉调工具参数按数据规模调整SqlCapability的max_display_rows、max_csv_rows、timeout_seconds换后端可选SqlCapability只依赖BaseSandboxSession接口若不用 Daytona可接入仓库支持的其他沙箱后端仅需重写入口层的 client 与状态持久化逻辑。总结本示例完整示范了沙箱化 text-to-SQL Agent的端到端实现——从 Manifest 工作区蓝图、带五层护栏的 SQL 执行能力到多轮流式 REPL、Compaction/Memory 双记忆机制、暂停恢复与审计日志。它的每一处设计schema 分层注入、展示层与模型输入解耦、纵深防御、幂等建库都值得在实际项目中直接借鉴。【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
基于 openai-agents-python 与 Daytona 沙箱构建 NASA 支出 Text-to-SQL 多轮对话 Agent【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python本篇技术指南围绕仓库examples/sandbox/extensions/daytona/usaspending_text2sql/中的完整示例展开它展示如何用 openai-agents-python 的SandboxAgent、自定义Capability、Daytona 云端沙箱构建一个能把自然语言问题翻译成 SQL、在只读 SQLite 上执行并返回结构化表格的多轮对话 Agent。读完本文你将掌握沙箱 Agent 的 Manifest 构建、带纵深防御护栏的 SQL 工具封装、会话暂停/恢复、Compaction 长会话压缩与 Memory 跨会话记忆等一整套可复用的工程模式。一、示例概览一个文本转 SQL沙箱 Agent 的完整骨架1.1 示例是什么该示例实现了一个多轮对话式数据分析 Agent用户用自然语言提问如What are NASAs top 10 contractors by total spending?Agent 将其翻译为 SQL在一个本地沙箱内SQLite 数据库上执行并返回结构化的表格结果。数据源为美国联邦政府公开支出平台 USAspending.gov 上的 NASA 支出数据。其核心价值在于LLM 只负责写 SQL执行与安全由沙箱与自定义工具保证——这是生产级 text-to-SQL 应用的标准分工。1.2 目录结构与架构原文档给出了清晰的架构图对应的仓库目录结构为examples/sandbox/extensions/daytona/usaspending_text2sql/ ├── agent.py — SandboxAgent 定义 交互式 REPL 入口 ├── sql_capability.py — SqlCapabilityCapability 子类提供 run_sql 工具与护栏 ├── setup_db.py — 在沙箱内运行从 USAspending API 拉取数据、构建 SQLite 库 ├── schema/ │ ├── overview.md — 精简 schema 摘要注入到 instructions 中 │ ├── glossary.md — USAspending 官方术语表setup_db.py 自动抓取 │ └── tables/ │ └── spending.md — spending 表的逐列说明按需通过 Shell 读取 └── README.md三个核心文件各自承担独立职责见 agent.py、sql_capability.py、setup_db.py。二、工作原理六大关键机制原文档总结了该 Agent 的六条工作原理这里结合源码逐一展开Schema 知识注入Agent 的系统提示词instructions中直接嵌入精简的 schema 摘要即 schema/overview.md 的全部内容同时在 Manifest 中挂载schema目录Agent 可按需读取 schema/tables/spending.md 获取逐列文档、读取 schema/glossary.md 获取官方术语定义。这避免了把整份表结构塞进提示词导致 token 浪费实现精要进提示词、细节按需取。SQL 执行与护栏自定义SqlCapability提供run_sql工具具备只读模式、语句校验、行数限制、查询超时等护栏详见第五节。多轮对话Agent 跨轮保留上下文通过Runner.run_streamed与result.to_input_list()维护会话历史因此可以追问break that down by year或just the top 5。Compaction使用Compactioncapability 自动把较早的对话上下文总结压缩使长会话保持在模型上下文窗口内。暂停/恢复Pause/Resume输入exit暂停沙箱并退出再次运行脚本会重连同一暂停沙箱无需重新下载数据。若沙箱无法重连被删除或过期自动新建沙箱并重建数据库。跨会话记忆Memory使用Memorycapability 从每次对话中提取经验如好用的 SQL 模式、数据注意事项整合为结构化文件后续会话开始时 Agent 自动带上此前对话的上下文。2.1 从源码看 Agent 的组装在 agent.py 的build_agent()中Agent 被组装为SandboxAgent默认模型为gpt-5.6-soldefault_manifest声明工作区布局setup_db.py由本地文件映射进沙箱LocalFileschema目录整体映射LocalDirdata为ephemeral临时目录用于存放构建出的 SQLite 库memories/下预置MEMORY.md、memory_summary.md、phase_two_selection.json三个空文件供 Memory capability 使用capabilities依次挂载SqlCapability(db_pathdata/usaspending.db)、Shell()、Compaction()、Memory(...)。Manifest 正是沙箱蓝图它决定了沙箱里一开始有什么文件、哪些目录是临时的是实现可复现工作区的关键抽象。2.2 开发者指令DEVELOPER_INSTRUCTIONSagent.py 中的开发者指令值得逐条细读它本质上是一份SQL 分析 Agent 的行为规范一律使用run_sql查询数据库绝不直接运行 sqlite3需要列细节时读取schema/tables/文档需要术语定义时读取schema/glossary.md例如区分 obligation 与 outlay优先用聚合GROUP BY、SUM、COUNT、AVG而不是返回大量原始行最终回答中金额要用美元符号与千分位格式化如 $1,234,567面对追问时结合上下文理解按年拆分、只看前 5这类指代查询失败时读错误信息并尝试修正 SQL简要解释查询逻辑便于用户验证正确性。另外还内置了数据注意事项data caveats这是 text-to-SQL 应用中容易被忽视却极其重要的一环数据库存的是obligations法律承诺的拨款义务而非 outlays实际支付用户问spending时需澄清是 obligation 金额金额绑定action_date义务签署日而非实际执行时间多年期合同可能整笔落在签署财年部分收款方因隐私被掩码为 MULTIPLE RECIPIENTS 或 REDACTED DUE TO PII做收款方分析时应说明数据不完整。这些 caveats 的存在能让 Agent 的回答显著减少看似正确实则误导的情况。三、运行前准备与快速启动3.1 前置条件原文档列出的前置条件如下均以当前仓库实际内容为准Python 3.12安装带 Daytona 支持的openai-agents在仓库根目录执行uv sync --extra daytonaDaytona 沙箱示例依赖可选 extra见 agent.py 中导入失败时的报错提示设置OPENAI_API_KEY环境变量用于 LLM设置DAYTONA_API_KEY环境变量用于沙箱服务沙箱内需要互联网访问首次运行时要在沙箱内建库。agent.py 中的_require_env()会在缺少任一必需环境变量时直接以清晰报错退出。3.2 启动命令从仓库根目录执行export OPENAI_API_KEYsk-... export DAYTONA_API_KEY... uv run python -m examples.sandbox.extensions.daytona.usaspending_text2sql.agent启动流程对应 agent.py 的main()校验两个 API Key构建 Agent 蓝图build_agent()创建DaytonaSandboxClient并配置DaytonaSandboxClientOptions(pause_on_exitTrue, exposed_ports(8080,))尝试从本地.session_state.json恢复上次暂停的沙箱client.resume()失败则新建在沙箱内执行python3 setup_db.py首次建库可耗时数分钟执行超时上限 1800 秒在沙箱内启动results目录上的 HTTP 文件服务器nohup python3 -m http.server 8080 ...并通过sandbox.resolve_exposed_port(8080)解析出可下载的签名 URL进入交互式 REPL。3.3 首次运行的自动建库数据库在首次运行时于沙箱内自动构建要求沙箱有网络后续运行直接复用已有数据库。建库由 setup_db.py 完成其设计是幂等的数据库已存在且覆盖全部请求财年时直接跳过除非传--force详见下文第四节。3.4 示例提问进入 REPL 后可直接尝试原文档给出的示例问题 What are NASAs top 10 contractors by total spending? Break that down by fiscal year Which NASA centers award the most contracts? Show me grants to universities in California How has NASA spending changed over time? What are the largest individual awards in the last 3 years? Compare contract vs grant spending by year终端还支持两个控制命令输入exit暂停沙箱并退出输入destroy则删除沙箱会跳过内存刷新、删除本地 session state。此外设置EXAMPLES_INTERACTIVE_MODEauto可让示例以自动化模式运行自动输入默认问题后退出相关实现见 examples/auto_mode.py。四、数据层USAspending 数据库的构建与结构4.1 setup_db.py 如何工作setup_db.py 被设计为在只有 Python 标准库的沙箱环境中运行通过 USAspending bulk download API 拉取数据、解析 CSV、构建本地 SQLite 库。其命令行参数python setup_db.py [--force] [--start-fy 2021] [--end-fy 2025]--start-fy/--end-fy首/末财年默认 2021–2025--start-fy --end-fy时报错--force即使库已存在也强制重建。关键实现细节财年换算联邦财年为 10 月 1 日至次年 9 月 30 日fiscal_year_dates()负责换算如 FY2024 2023-10-01 至 2024-09-30分年并发拉取bulk download API 的日期范围限制为 1 年因此脚本按财年逐个提交请求且一次性并发提交全部财年ThreadPoolExecutor让服务端打包最慢环节并行进行再统一轮询状态、下载解压奖助类型代码映射setup_db.py合同类代码 A/B/C/D →contract援助类 02–05 →grantIDV_* →idv兜底按award_id前缀CONT_IDV_判断或归为otherCSV 类型探测依据表头中contract_award_unique_key/assistance_award_unique_key区分合同与援助 CSV两类 CSV 的列名映射独立维护合同列含recipient_parent_name、extent_competed等援助列含cfda_number、business_types_description等见 setup_db.py自动抓取术语表通过 glossary API 拉取 USAspending 官方术语示例当前为 149 条写入 schema/glossary.md索引优化建表 SQL 中为award_id、fiscal_year、award_type、recipient_name、recipient_parent_name、recipient_state、action_date、naics_code、federal_action_obligation、extent_competed、period_of_perf_start、awarding_office等列创建索引保障聚合查询性能见 setup_db.py完整性校验建库完成后校验库中是否覆盖全部请求财年缺失则报错并清理。4.2 spending 表结构数据库使用单张spending表每一行是一条交易记录obligation、modification 或 de-obligation同一联邦 award 的多条交易共享award_id。核心列完整逐列文档见 schema/tables/spending.md列含义award_id唯一 award 标识多条交易共享award_piid_fain可读的合同号PIID或援助号FAINparent_award_piid父级 IDV 合同号任务单关联合同载体仅合同award_typecontract/grant/idv/otheraction_date交易日期YYYY-MM-DDfiscal_year联邦财年10 月–次年 9 月federal_action_obligation本笔交易金额de-obligation 为负total_obligation交易时点的 award 累计义务额base_and_all_options_value含未行使选项的合同总上限仅合同recipient_name/recipient_parent_name收款方 / 母公司子公司归并仅合同recipient_state/city/country收款方位置awarding_office/funding_officeNASA 中心/办公室如 GODDARD SPACE FLIGHT CENTERnaics_code/psc_code及描述行业 / 产品服务分类extent_competed/type_of_set_aside/number_of_offers/contract_pricing_type竞争程度、小企业预留、报价数、定价类型仅合同business_types援助类收款方类型仅 grantsdescription交易自由文本描述该文档还标注了几条对写 SQL 至关重要的坑Notes按 award 聚合要用GROUP BY award_idSUM(federal_action_obligation)而非直接读total_obligation快照base_and_all_options_value是上限而total_obligation才是实际承诺额母公司归并使用COALESCE(NULLIF(recipient_parent_name, ), recipient_name)recipient_name同一实体可能存在拼写差异需用LIKE或UPPER()模糊匹配psc_code一列同时存放合同 PSC 与援助 CFDA 两套分类系统。4.3 常见查询模式schema/overview.md 提供了可直接复用的参考 SQL-- 按财年统计总支出 SELECT fiscal_year, SUM(federal_action_obligation) AS total FROM spending GROUP BY fiscal_year ORDER BY fiscal_year; -- 头部收款方按母公司归并 SELECT COALESCE(NULLIF(recipient_parent_name, ), recipient_name) AS entity, SUM(federal_action_obligation) AS total FROM spending GROUP BY entity ORDER BY total DESC LIMIT 10; -- 按 award 类型统计 SELECT award_type, COUNT(*), SUM(federal_action_obligation) AS total FROM spending GROUP BY award_type; -- 竞争 vs 单一来源合同 SELECT extent_competed, COUNT(DISTINCT award_id) AS awards, SUM(federal_action_obligation) AS total FROM spending WHERE award_type contract GROUP BY extent_competed ORDER BY total DESC; -- 按 NASA 中心统计 SELECT awarding_office, SUM(federal_action_obligation) AS total FROM spending GROUP BY awarding_office ORDER BY total DESC;这些模式正是被注入提示词的精华 schema让 Agent 一上来就掌握正确的聚合口径。五、SqlCapability带纵深防御护栏的 SQL 执行工具5.1 Capability 机制SqlCapability继承自 SDK 的Capability基类src/agents/sandbox/capabilities/capability.py。从 sql_capability.py 可见其结构type: Literal[sql] sql声明能力类型可配置字段db_path默认data/usaspending.db、max_display_rows默认 100、max_csv_rows默认 10,000、timeout_seconds默认 30.0、results_dir默认resultsbind(session)在运行时绑定沙箱会话tools()返回run_sql工具instructions(manifest)返回注入给 Agent 的能力级指令强调一律用run_sql、写标准 SQLite SQL、优先聚合、最多展示 100 行但最多 10,000 行存入可下载 CSV、金额以 REAL 美元存储等。这种能力即插即用的抽象让 SQL 能力可以在不同沙箱后端、不同 Agent 之间复用——这正是原文档强调agent 与 capability 定义与后端无关的含义。5.2 run_sql 工具_make_run_sql_tool()sql_capability.py通过tool装饰器name_overriderun_sql构造一个FunctionTool其执行方式很有意思不在 SDK 进程内连数据库而是把查询通过session.exec()送进沙箱内执行命令形如printf %s query | python3 -c query runner 脚本 db_path display_limit max_csv_rows results_dirlimit参数取max(1, min(limit or max_display_rows, max_display_rows))即 0 与 None 都走默认值查询超时ExecTimeoutError/TimeoutError会返回Query timed out after 30s. Try a simpler query or add a LIMIT.这样的模型可读错误促使 Agent 自我修正。5.3 五层纵深防御护栏这是本示例最值得借鉴的部分——纵深防御defense in depth。原文档列出 5 层结合 sql_capability.py 中沙箱内执行的_QUERY_RUNNER_SCRIPT可逐一对应连接级只读SQLite 以 URIfile:{db_path}?modero打开——连接层面即为只读PRAGMA 兜底连接后立即PRAGMA query_only ON即使绕过语句校验也无法写入语句级校验只允许SELECT、WITH、EXPLAIN、PRAGMA开头的语句按首个 token 判断其余直接拒绝并返回错误行数硬上限默认展示上限 100 行同时最多 10,000 行写入 CSVfetchmany(csv_limit 1)探测是否截断返回 JSON 中的truncated字段标记截断超时查询在 30 秒后被终止session.exec的 timeout 参数。最终工具返回结构化的 JSON{columns: [...], rows: [...], row_count: N, display_count: M, truncated: bool, csv_file: query_ts_pid.csv, note: ...}。展示给模型的行数被严格限制但完整结果以 CSV 形式落盘供下载——兼顾模型上下文省 token与用户拿全量数据两个诉求。5.4 超时、截断与 CSV 下载当结果超过展示上限时工具返回的note会明确告知Showing X of Y rows. Full result saved to CSV.CSV 文件写入results/目录文件名带时间戳与 PID再由 agent.py 中沙箱内的 HTTP 文件服务器通过 Daytona 暴露端口提供给用户浏览器下载。终端若判定表格过宽超出os.get_terminal_size()也会提示too wide to print in terminal, download below并附上下载链接。六、多轮对话 REPL 与流式输出6.1 流式运行与会话历史REPL 核心在run_turn()agent.py每轮把conversation历史与新的用户问题拼成input_items调用Runner.run_streamed(agent, input_items, run_configrun_config)用result.stream_events()消费事件流raw_response_event中的ResponseTextDeltaEvent直接打印增量文本实现打字机效果tool_called/tool_output事件则交给格式化函数展示轮末用result.to_input_list()生成下一轮输入——SDK 内置的序列化能正确处理各类 item 类型这是多轮对话上下文不丢失的关键。6.2 工具调用与结果的终端格式化agent.py 中的格式化助手很有工程参考价值_highlight_sql()用正则给 SQL 做 ANSI 语法高亮——关键字、函数、字符串分别着色先暂存字符串字面量避免内部内容被误染_format_tool_args()对run_sql的调用参数做 pretty-print显示[SQL]与可选(limit N)_format_tool_result()解析工具返回的 JSON把结果渲染成对齐的 ASCII 表格列宽按内容自适应并在展示行数少于总行数或 CSV 被截断时给出摘要说明。这套输出层设计让用户在终端里就能获得类似数据库客户端的阅读体验而 Agent 模型拿到的则是紧凑的 JSON——展示层与模型输入层解耦。6.3 交互命令REPL 循环agent.py支持exit暂停沙箱、保存会话状态与记忆、退出destroy删除沙箱、跳过内存刷新空输入直接跳过单轮异常捕获后继续会话。自动模式下EXAMPLES_INTERACTIVE_MODEauto使用默认问题What are NASAs top 5 contractors by total obligations?单轮运行后退出。七、Compaction 与 Memory长会话与跨会话记忆7.1 Compaction长会话压缩Compaction()能力用于在会话过长时自动总结较早的上下文从而把长对话维持在模型上下文窗口内。其默认压缩阈值为 240,000 token见 src/agents/sandbox/capabilities/compaction.py 中_DEFAULT_COMPACT_THRESHOLD并内置常见模型的上下文窗口映射表用于判断何时需要压缩。对本示例而言用户可能连续追问几十轮分析Compaction 保证了会话可持续而不溢出。7.2 Memory跨会话经验沉淀Memory能力实现见 src/agents/sandbox/capabilities/memory.py在本示例中的配置agent.py为readMemoryReadConfig(live_updateFalse)会话开始时读取memories/memory_summary.md注入上下文generateMemoryGenerateConfig(extra_prompt...)每次会话结束后在后台从对话中提取经验并写入memories/MEMORY.md汇总文件上限 15,000 token见 memory.py 中_MEMORY_SUMMARY_MAX_TOKENS。extra_prompt明确引导模型沉淀哪些 SQL 模式在 USAspending 数据上最好用、列的特殊性如按 recipient_parent_name 而不是 recipient_name 分组、用户发现的数据注意事项负 obligation、掩码收款方。这使 Agent 在多次会话后越来越懂这份数据——新会话无需从零摸索。八、会话暂停/恢复与审计日志8.1 会话状态持久化暂停/恢复通过把DaytonaSandboxSessionState序列化到本地文件实现agent.py_save_session_state()把sandbox.state.model_dump_json(indent2)写入.session_state.json启动时_load_session_state()读取并model_validate_json还原随后client.resume(saved_state)重连若sandbox.state.sandbox_id与旧 ID 不一致说明旧沙箱已不存在则自动新建状态在沙箱启动后立即持久化避免崩溃导致沙箱成为孤儿资源。退出时若为destroy模式会置pause_on_exitFalse并删除本地状态文件后停机否则保存状态并调用sandbox.aclose()内部先保存记忆再暂停可能耗时数分钟。8.2 审计日志所有沙箱操作exec 调用、启动/停止、SQL 查询及其结果通过 SDK 的Instrumentation与JsonlOutboxSink以结构化 JSONL 事件追加写入.audit_log.jsonlagent.pyinstrumentation Instrumentation( sinks[JsonlOutboxSink(AUDIT_LOG_PATH)], payload_policyEventPayloadPolicy(include_exec_outputTrue), )include_exec_outputTrue意味着连执行输出都记录在内。这对调试、回放会话、或审计Agent 到底执行了哪些 SQL极为有用——在需要合规与可追溯的 text-to-SQL 场景中这条日志是标配。九、沙箱后端Daytona 集成本示例以 Daytona 作为沙箱后端。agent与capability的定义是后端无关的但入口 agent.py 硬编码了DaytonaSandboxClient与 Daytona 特有功能pause/resume、exposed ports、签名下载 URL。相关组件DaytonaSandboxClient沙箱生命周期管理create/resume/start/stop/shutdown/aclose来自agents.extensions.sandboxDaytonaSandboxClientOptions(pause_on_exitTrue, exposed_ports(RESULTS_PORT,))配置暂停策略与暴露端口8080 用于结果文件下载WORKSPACE_ROOT DEFAULT_DAYTONA_WORKSPACE_ROOT沙箱工作区根目录沙箱内执行setup_db.py时要求沙箱具备网络访问能力。仓库另有一个最小化的 Daytona 沙箱验证示例 examples/sandbox/extensions/daytona/daytona_runner.py展示了更基础的用法Manifest构建含可选 S3 云桶挂载、SandboxAgentWorkspaceShellCapability、以及--pause-on-exit/--stream等 CLI 参数可作为理解本示例的入门对照。Daytona 扩展的完整实现位于 src/agents/extensions/sandbox 下。十、扩展思路把该模式复用到其他数据集该示例的最大价值在于其可迁移的工程模式。将其改造成其他数据集的 text-to-SQL Agent通常只需四步换数据替换setup_db.py或直接挂载已有的 SQLite 文件保持幂等建库约定换 schema 文档重写 schema/overview.md 与 schema/tables/ 下的逐表文档并同步更新 instructions 中的数据 caveats——这是 Agent 查询质量的命脉调工具参数按数据规模调整SqlCapability的max_display_rows、max_csv_rows、timeout_seconds换后端可选SqlCapability只依赖BaseSandboxSession接口若不用 Daytona可接入仓库支持的其他沙箱后端仅需重写入口层的 client 与状态持久化逻辑。总结本示例完整示范了沙箱化 text-to-SQL Agent的端到端实现——从 Manifest 工作区蓝图、带五层护栏的 SQL 执行能力到多轮流式 REPL、Compaction/Memory 双记忆机制、暂停恢复与审计日志。它的每一处设计schema 分层注入、展示层与模型输入解耦、纵深防御、幂等建库都值得在实际项目中直接借鉴。【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
