AI 原生开放教材

外观

openai-cookbook-docs官方文档·英文原文 ↗原件 ↓仓库 ↗

Notes, Assumptions, and Extension Points ​

What This Cookbook Is Designed For ​

This cookbook is a compact, self-contained demonstration of an agentic database-change workflow. It is meant to show how to combine:

  • staged agent orchestration
  • typed intermediate outputs
  • optional retrieval context
  • deterministic guardrails
  • trace instrumentation
  • artifact generation
  • Promptfoo evals

The workflow is intentionally portable and does not depend on external project-specific modules, local vector databases, graph databases, or a live data warehouse connection. The retail example is deliberately concrete, but the same staged pattern can be adapted to other domains where schema changes need analysis, implementation planning, and review.

What This Cookbook Does Not Do ​

This notebook does not:

  • execute SQL against a database
  • inspect a live schema catalog
  • open pull requests
  • modify production infrastructure
  • validate SQL with a database parser
  • enforce organization-specific migration standards
  • replace human code review

The generated SQL should be treated as a draft for review.

Tracing and Sensitive Data ​

The notebook defaults to redacted traces for publication hygiene. Set OPENAI_AGENTS_TRACE_INCLUDE_SENSITIVE_DATA=true only for non-sensitive demo runs where retaining prompt and output payloads is intentional.

Before adapting this for sensitive enterprise data, review:

  • OPENAI_AGENTS_TRACE_INCLUDE_SENSITIVE_DATA
  • API key handling
  • PDF upload policy
  • data retention expectations
  • access controls around generated artifacts

Optional PDF RAG ​

The optional RAG path uses OpenAI Vector Stores and the Agents SDK FileSearchTool.

This is useful when impact analysis should be grounded in a reference PDF such as:

  • an interface design document
  • an implementation field definition
  • schema documentation
  • lineage documentation
  • downstream dependency notes

The vector store is configured to expire automatically after one day of inactivity. You can also delete it immediately in the cleanup section.

Promptfoo Eval Path ​

The Promptfoo section generates runtime files under:

text
artifacts/promptfoo/

The generated core module injects the current notebook prompt strings, so prompt edits and CHANGE_TEXT edits are reflected after rerunning the generation cells.

By default, the eval flow includes:

  • deterministic input preflight
  • one parse-only eval for the current request
  • one full-flow eval for the current request

Set RUN_EXTRA_REGRESSION_CASES = True to include the optional regression fixtures.

Suggested Production Extensions ​

For a production-grade implementation, consider adding:

  • schema catalog lookup
  • database-specific SQL validation
  • SQL formatting and linting
  • migration framework integration
  • pull request creation
  • data lineage graph integration
  • approval workflows
  • policy checks for destructive changes
  • richer eval suites
  • golden test fixtures
  • organization-specific SQL templates
  • environment-specific deployment plans

Before using generated output for real implementation, review:

  • parsed target schema and table
  • parsed operations
  • data type and nullability
  • backfill logic
  • index strategy
  • downstream propagation assumptions
  • prechecks and postchecks
  • rollback feasibility
  • generated SQL dialect compatibility
  • validation issues
  • trace output
  • saved artifact contents
  • Promptfoo eval results