agents.md — Codex Engineering & Data Fetch Agent

1. Purpose & Scope

Define an AI agent system that: (1) interprets natural language developer or analyst requests, (2) plans multi‑step tasks (code authoring, refactoring, data retrieval), (3) safely invokes internal tools (stock data fetch functions, file I/O, code exec sandboxes), (4) returns structured, auditable results, and (5) adheres to OpenAI Assistants API paradigms (tools: function calling, file search / code interpreter when enabled). (OpenAI 平台, OpenAI 平台, OpenAI 平台)

2. Historical Context & Deprecation Awareness

Legacy Codex inference models were deprecated (March 2023), so the agent must target current general or reasoning/coding models (e.g. gpt-4.1, o3-mini, o4-mini, or other tool‑enabled releases) rather than obsolete endpoints; design includes a Model Abstraction Layer to swap models without rewriting orchestration when OpenAI publishes deprecations. (GitHub, Visual Studio Magazine, OpenAI 平台)

3. Goals & Success Criteria

Primary goals: high‑accuracy function argument generation, deterministic structured outputs, minimized hallucinated tool calls, resilient rate limit handling, transparent adjusted‑price semantics. Success metrics: ≥95% valid JSON schema conformance for tool calls (with strict mode), error retry latency < exponential policy cap, and zero unapproved shell operations. (OpenAI 平台, OpenAI, OpenAI 平台)

4. Non‑Goals

Not a portfolio optimizer, not giving investment advice, not bypassing provider ToS, and not persisting secrets outside the secure configuration store—explicit guardrails to prevent misuse. (OpenAI 平台, OpenAI 平台)

5. Architecture Overview

Pattern: Planner → Tool Executor → Synthesizer. Planner uses model reasoning to choose functions; Executor layer performs deterministic Python operations (fetch history, write CSVs, generate diffs); Synthesizer merges raw outputs + rationale + disclaimers; optional Critic pass revalidates structured output before returning. (OpenAI 社區, OpenAI 社區, OpenAI 社區)

6. Tool / Function Inventory

Tool Name	Category	Purpose	Key Notes
fetch_history	Data	Download OHLCV (symbols, start/end, interval, adjust flags).	Inclusive end logic; maps to yfinance wrapper. (OpenAI 平台, OpenAI 平台)
list_supported_intervals	Meta	Enumerate allowed intervals & max lookback hints.	Prevent invalid interval errors. (OpenAI 平台, OpenAI 平台)
write_csv_bundle	Output	Persist per‑symbol frames in naming scheme.	Deterministic artifact traceability. (OpenAI 平台, OpenAI 平台)
summarize_dataset	QA	Row counts, min/max dates, gaps, columns.	Aids post‑fetch validation. (OpenAI 社區, Reddit)
generate_code_patch	Code	Create or modify Python modules / tests.	Uses model coding capability. (The Verge, Business Insider)
run_tests	QA	Execute unit tests subset (sandbox).	Isolated interpreter / code interpreter tool. (OpenAI 平台, OpenAI 平台)
explain_symbol_normalization	Explainability	Show how each input symbol normalized (e.g. 2330→2330.TW).	Transparency reduces confusion. (Medium, OpenAI 平台)

7. Function Schemas (JSON Schema / Strict Mode)

Use Assistants function calling with strict: true to force model conformance; enumerations reduce drift; required fields enforce argument completeness; optional arrays allow incremental refinement (e.g. adding columns). (OpenAI 平台, OpenAI, OpenAI 平台)

{
  "name": "fetch_history",
  "description": "Download historical OHLCV for symbols (inclusive end date).",
  "strict": true,
  "parameters": {
    "type": "object",
    "properties": {
      "symbols": { "type": "array", "items": { "type": "string" }, "minItems": 1 },
      "start_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" },
      "end_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" },
      "interval": {
        "type": "string",
        "enum": ["1m","2m","5m","15m","30m","60m","90m","1h","1d","5d","1wk","1mo","3mo"]
      },
      "auto_adjust": { "type": "boolean", "default": true },
      "repair": { "type": "boolean", "default": false },
      "columns": {
        "type": "array",
        "items": { "type": "string" },
        "description": "Subset columns (e.g. Close, Volume)"
      }
    },
    "required": ["symbols","start_date"]
  }
}

Structured output enforcement ensures downstream parsing reliability and reduces guard code. (OpenAI, OpenAI 平台)

8. Model Selection Strategy

Default: a cost‑efficient, tool‑capable model for routine planning (e.g. mid‑tier reasoning or coding‑optimized variant); escalate to a higher reasoning model when: (a) multi‑file refactor, (b) complex dependency graph summarization, (c) test failure triage. New reasoning models (e.g. o3-mini) offer faster structured reasoning; fallback policies maintain continuity during model unavailability. (The Verge, The Verge, GitHub)

9. Deprecation & Version Policy

Maintain a models.json manifest with active, deprecated_by, sunset_date; nightly job compares OpenAI deprecation feed and marks internally‑approved alternates to avoid sudden outages. (OpenAI 平台, Visual Studio Magazine)

10. Prompt Layer Design

System Prompt: sets role (“coding & data acquisition assistant”), forbids investment advice, mandates citation or provenance reporting. Developer Prompt: enumerates available functions & argument guidelines. User Prompt: raw user request. Chain-of-thought internal; only final rationale summary returned. (OpenAI 平台, OpenAI 平台, OpenAI 社區)

11. Planning Heuristics

Before calling tools: validate date patterns; expand relative intervals (“last 3 weeks”) to concrete ISO dates; cluster symbols to respect rate limits (batch size threshold dynamic); if user wants code modification, draft diff via generate_code_patch first, then request confirmation before write_csv_bundle. (OpenAI 社區, Reddit, OpenAI 平台)

12. Execution Workflow

1. Parse & Normalize (symbols / dates).
2. Decide Tools (single vs composite).
3. Call fetch_history (strict schema).
4. Call summarize_dataset for QA.
5. If user requested saving, invoke write_csv_bundle.
6. Synthesizer adds disclaimers & next‑step guidance. (OpenAI 平台, OpenAI 平台, OpenAI 平台)

13. Structured Output & Validation

Strict mode ensures JSON matches schema; post‑validation includes semantic checks (date range non‑empty, interval valid, symbol count limit) before dispatch; errors trigger a self‑correction planner re‑prompt advising minimal delta changes. (OpenAI 平台, OpenAI, OpenAI 平台)

14. Rate Limiting & Throttling

Read OpenAI published limits and adapt concurrency (tokens per minute / requests per minute) while adjusting for dynamic Plus / Pro or Azure quotas; implement exponential backoff + jitter for 429 or network spikes. (OpenAI 平台, 微軟學習, OpenAI 社區)

15. External Data & Image / Code Tools

Assistants API supports Code Interpreter and File Search; enabling Code Interpreter allows dynamic parsing of downloaded CSVs for user quick stats without manual local execution; treat file tool operations as privileged steps requiring explicit user consent. (OpenAI 平台, OpenAI 平台)

16. Performance Tuning

Choose smaller reasoning models for simple argument formation (reduces latency) and escalate for multi‑function code generation; maintain batch threshold heuristics (e.g. > N symbols triggers chunking) to minimize upstream service pressure. (The Verge, The Verge)

17. Code Generation & Refactoring

Leverage modern coding / reasoning models (e.g. improved coding throughput vs older Codex) to produce diffs instead of full files; diffs reduce merge risk; include test stubs referencing affected modules. (The Verge, GitHub)

18. Error Taxonomy & Recovery

Error	Likely Cause	Mitigation
Schema Validation	Hallucinated arg name	Self‑repair prompt with explicit allowed keys
Rate Limit 429	Burst activity	Backoff + batch splitting
Empty Dataset	Bad symbol / holiday	Suggest interval or date shift
Deprecation Failure	Model removed	Swap to fallback from manifest
Tool Timeout	Network stall	Retry (bounded) then partial result summary
Referenced best practices encourage iterative function planning and monitoring reasoning drift. (OpenAI 社區, OpenAI 社區, OpenAI 社區)

19. Security & Compliance

No secrets in user prompts; environment variables for API keys; disclaimers inserted on every financial data response to clarify informational nature; refuse trading recommendations to remain within safe usage guidelines. (OpenAI 平台, OpenAI 平台, OpenAI 平台)

20. Logging & Observability

Log (request_id, model, tokens_in/out, tool_calls[], latency_ms, retry_count, rate_limit_headers snapshot) to enable capacity planning and debugging tool misuse. Rate metrics correlate with evolving usage/message limits environment to preempt throttling. (OpenAI 平台, OpenAI 社區, The Verge)

21. Testing Strategy

• Schema Tests: Validate JSON definitions compile & required fields enforced.
• Prompt Replay: Golden user prompts produce stable tool call sequences.
• Mutation Tests: Inject invalid intervals to confirm rejection flow.
• Latency Benchmarks: Compare small vs reasoning model call times weekly.
• Deprecation Simulation: Force model removal to test fallback. Community best practices highlight iterative refinement to improve function selection fidelity. (Reddit, OpenAI 社區, OpenAI 平台)

22. CI/CD Integration

Pre‑merge pipeline: run unit tests, schema lint, sample assistant dry‑run (no external calls for determinism); nightly job triggers live integration tests within rate limits. (OpenAI 平台, 微軟學習)

23. Versioning & Change Control

Semantic version for agent spec (agents.md): increment MINOR when adding tools; MAJOR when altering existing schema shape; patch for documentation or non‑breaking prompt tweaks; record upstream model migrations. (OpenAI 平台, Visual Studio Magazine)

24. Observed Ecosystem Trends

Increased availability of reasoning models and CLI / local agent tooling (open source codex CLI) motivates modular model adapter; news indicates ongoing improvements in coding performance and research tool rate limit adjustments. (GitHub, The Verge, The Verge)

25. Roadmap

Short term: Retry abstraction, interval lookback heuristics, diff‑aware code patch tool. Mid term: Automatic test generation from code changes, partial dataset streaming summarizer. Long term: Multi‑agent parallelization (task graph) and adaptive model selection using live performance metrics. (OpenAI 社區, The Verge, GitHub)

26. Example Session Trace (Condensed)

User asks: “Get 2330 and AAPL daily close & volume for last month and save files.” Planner expands dates, normalizes 2330→2330.TW, calls fetch_history, then write_csv_bundle, returns summary plus disclaimer. (Medium, OpenAI 平台, OpenAI 平台)

27. Example Planner Prompt Snippet

“Given the user request: … Decide if data fetch, code change, or explanation. For fetch: produce a single fetch_history call with inclusive ISO dates. Validate intervals against allowed enum. If user asked to save, follow with write_csv_bundle using previous result context. Never speculate financial advice.” (OpenAI 平台, OpenAI 平台, OpenAI 平台)

28. Example Self‑Repair Prompt

“If previous function call failed due to invalid parameter, propose corrected call using ONLY valid parameter names: … Provide updated JSON arguments matching schema.” (OpenAI 社區, Reddit)

29. Monitoring & Metrics

Track: tool_call_accuracy (% successful executions), avg_planning_tokens, function_retry_rate, schema_noncompliance_count, and time_to_first_token across models to evaluate trade‑offs and plan upgrades. (The Verge, OpenAI 平台, OpenAI 社區)

30. Appendix A: Additional Schemas

Include write_csv_bundle with required output_path & file_format enum to prepare for adding parquet/json later; strict schema ensures future extension without breaking existing parameters. (OpenAI 平台, OpenAI)

31. Appendix B: Rate Limit Backoff Policy

Initial delay 1s; multiplier 2; jitter ±20%; max attempts 5; abort and summarize partial results if still failing—aligned with general community recommendations to reduce thrash. (OpenAI 平台, Reddit)

32. Appendix C: Model Fallback Table

Priority	Model	Use Case	Fallback Trigger
1	High reasoning (e.g., latest tool model)	Multi-step planning	Latency SLA breach or quota
2	Mid-tier (fast)	Standard fetch + simple code edits	Rate limit spikes or high cost
3	Small / lightweight	Quick symbol normalization, retries	Global throttling
Stay current with emerging reasoning / coding models for optimal trade‑offs. (The Verge, The Verge, GitHub)

33. Appendix D: Deprecation Checklist

Weekly cron: call deprecation endpoint feed / docs, diff against manifest, warn if active model scheduled for retirement; auto create ticket to update config. (OpenAI 平台, Visual Studio Magazine)

34. Appendix E: User Safety Statement Injection

Every financial data answer appends: “Data is informational, sourced via Yahoo Finance interfaces, may be delayed or incomplete; no investment advice.” (Enforced by post‑processor). (OpenAI 平台, OpenAI 平台, OpenAI 平台)

35. Approval & Governance

Material changes (new external tool, relaxed safety rule, model swap) require two maintainer approvals and version bump; referenced against deprecation & best practice guidance for accountability. (OpenAI 平台, OpenAI 社區, OpenAI 平台)

---

End of agents.md — This specification should evolve with OpenAI tool capabilities, new model releases, and internal performance telemetry. (OpenAI 平台, The Verge, GitHub)