实验 2 BYOA：CourseContextAgent

CourseContextAgent 是一个单用途 AI 智能体：课程资料研究助手。它会先调用外部工具读取本地课程资料、解析 CSV 阅读清单、抓取网页内容，再生成学习简报，而不是只依赖大语言模型的基础知识。

评分点：System Mechanics & Tooling

本仓库已经把 40 分评分点需要看的内容显式放进代码库：

• 所有提示词都在仓库中：见 prompts/。
• 提示词会被运行时代码加载：见 byoa_agent/prompt_loader.py。
• 工具 schema 可查看：运行 python -m byoa_agent --show-tools。
• 有效系统提示词可查看：运行 python -m byoa_agent --show-prompts。
• 工具调用轨迹可导出：运行 demo 时加 --trace-json trace.json。
• 机制说明文档：见 docs/system_mechanics_tooling.md。

技术要求对应

• Tool Use / Skills：实现了 3 个工具：
  • read_local_file：读取本地 .txt、.md、.csv，可选支持 .pdf。
  • analyze_csv：解析 CSV，返回列、行数、样例行和数值统计。
  • fetch_web_page：抓取 HTTP(S) 网页并提取正文。
• Context Integration：byoa_agent/schemas.py 将工具暴露为 OpenAI 标准 function calling schema；byoa_agent/agent.py 实现 tool-call orchestration loop。
• Vibe Coding Constraint：脚手架、工具 schema、工具函数和调度循环由 AI/Codex 生成，学生可主要调整提示词与编排策略。
• Code Repo Including All Prompts：prompts/system_prompt.md、prompts/tool_selection_policy.md、prompts/demo_brief_template.md 全部纳入仓库并被代码读取。

快速运行

不需要 API key 的本地演示：

python -m byoa_agent --demo "summarize data/sample_reading.txt and analyze data/readings.csv"

查看所有 prompt：

python -m byoa_agent --show-prompts

查看暴露给 LLM 的工具 schema：

python -m byoa_agent --show-tools

导出工具调用 trace：

python -m byoa_agent --demo "summarize data/sample_reading.txt and analyze data/readings.csv" --trace-json trace.json

运行单元测试：

python -m unittest discover -s tests

启动真正的多轮智能体聊天需要 API key：

python -m pip install -r requirements.txt
Copy-Item .env.example .env

然后在 .env 中填入：

OPENAI_API_KEY=你的 key
BYOA_MODEL=gpt-4.1-mini
OPENAI_BASE_URL=

如果学校或代理提供 OpenAI-compatible 地址，把 OPENAI_BASE_URL 改成它的 /v1 地址；如果使用官方 OpenAI，可以留空。

启动交互式智能体：

python -m byoa_agent --interactive --verbose-tools

进入后可以输入：

Use data/sample_reading.txt and data/readings.csv to create a study plan.

退出输入：

exit

在 VS Code 中运行

本项目已包含 .vscode/ 配置，可直接用 VS Code 打开：

& "$env:LOCALAPPDATA\Programs\Microsoft VS Code\bin\code.cmd" -r "C:\Users\zhk\Desktop\agent"

打开后可通过 Ctrl + Shift + P -> Tasks: Run Task 运行 demo、测试、prompt 展示、tool schema 展示和 trace 导出。详细说明见 docs/vscode_setup.md。

使用真实 LLM Function Calling

先安装依赖：

python -m pip install -r requirements.txt

设置环境变量：

$env:OPENAI_API_KEY="sk-your-key-here"
$env:BYOA_MODEL="gpt-4.1-mini"

然后运行：

python -m byoa_agent "Read data/sample_reading.txt, analyze data/readings.csv, and create a study plan."

项目结构

byoa_agent/
  __main__.py        # CLI entrypoint
  agent.py           # orchestration loop and trace builder
  prompt_loader.py   # loads prompt files from prompts/
  schemas.py         # function calling schemas
  tools.py           # external-context tools
prompts/
  system_prompt.md
  tool_selection_policy.md
  demo_brief_template.md
docs/
  system_mechanics_tooling.md
data/
  sample_reading.txt
  readings.csv
tests/
  test_tools.py

截图展示

如果只需要 3-4 张运行截图，按 docs/screenshot_guide.md 操作即可。推荐运行 VS Code 任务：

BYOA: Screenshot demo - all tools