From abe3f690ec43e1fcae8138094d46043e69d3ec8e Mon Sep 17 00:00:00 2001 From: zhanggangyong Date: Thu, 5 Feb 2026 16:10:53 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=E7=BE=8E=E8=82=A1=20?= =?UTF-8?q?AI=20Agent=20=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/STOCK_AGENTS_DOC.md | 563 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 563 insertions(+) create mode 100644 docs/STOCK_AGENTS_DOC.md diff --git a/docs/STOCK_AGENTS_DOC.md b/docs/STOCK_AGENTS_DOC.md new file mode 100644 index 0000000..501ecc5 --- /dev/null +++ b/docs/STOCK_AGENTS_DOC.md @@ -0,0 +1,563 @@ +# 美股 AI Agent 文档 + +本项目包含 **三个独立的美股 AI Agent 服务**，均通过 **HTTP API** 对外提供能力，支持智能对话分析。 + +- **Stock Quote Agent**：美股实时行情查询与分析 +- **Stock News Agent**：美股新闻资讯获取与解读 +- **Stock Analysis Agent**：美股技术分析与投资建议 + +--- + +## 认证方式 + +所有 Chat API 需要在请求头中提供 API Key，支持两种方式： + +| 方式 | Header | 示例 | +|------|--------|------| +| api-key | `api-key` | `api-key: sk-xxxxx` | +| Bearer Token | `Authorization` | `Authorization: Bearer sk-xxxxx` | + +> ⚠️ 未提供认证信息将返回 `401 Unauthorized` + +--- + +## Agent 1：Stock Quote Agent + +### 功能概览 + +提供美股 **实时行情查询** 能力，支持自然语言交互，返回股票价格、涨跌幅、成交量等数据。 + +支持能力： + +- 实时股票行情查询 +- 多股票批量查询 +- 热门股票行情 +- **AI 智能对话分析** + +--- + +### 1️⃣ /chat — 智能对话 + +#### 功能说明 + +通过自然语言与 AI 交互，自动识别股票代码并返回行情数据及投资建议。 + +--- + +#### REST API 调用 + +``` +POST /chat +Content-Type: application/json +api-key: your-api-key +``` + +```json +{ + "message": "AAPL 和 TSLA 今天表现如何？" +} +``` + +--- + +#### 参数说明 + +| 参数 | 类型 | 必需 | 默认值 | 说明 | +|------|------|------|--------|------| +| message | string | ✅ | - | 用户消息（支持自然语言） | +| user_id | string | ❌ | null | 用户ID（用于计费回调） | + +**Header 参数：** + +| 参数 | 类型 | 必需 | 说明 | +|------|------|------|------| +| api-key | string | ⚠ | API Key（二选一） | +| Authorization | string | ⚠ | Bearer Token（二选一） | + +--- + +#### 返回结果 + +```json +{ + "response": "今天AAPL的股价为$274.43，涨跌幅为0.00%。TSLA的股价为$398.78...", + "data": { + "stocks": [ + { + "success": true, + "symbol": "AAPL", + "name": "Apple Inc.", + "price": 274.43, + "change": 0, + "change_percent": 0, + "volume": 5212932, + "high_52week": 288.62, + "low_52week": 169.21 + }, + { + "success": true, + "symbol": "TSLA", + "name": "Tesla, Inc.", + "price": 398.78, + "change": 0, + "change_percent": 0, + "volume": 7867089, + "high_52week": 498.83, + "low_52week": 214.25 + } + ], + "symbols_detected": ["AAPL", "TSLA"] + }, + "timestamp": "2026-02-05T15:30:13.347583" +} +``` + +--- + +### 2️⃣ /quote — 单股行情查询 + +#### REST API 调用 + +``` +GET /quote?symbol=AAPL +``` + +或 + +``` +POST /quote +Content-Type: application/json +``` + +```json +{ + "symbol": "AAPL" +} +``` + +--- + +#### 参数说明 + +| 参数 | 类型 | 必需 | 说明 | +|------|------|------|------| +| symbol | string | ✅ | 股票代码（如 AAPL, TSLA） | + +--- + +#### 返回结果 + +```json +{ + "symbol": "AAPL", + "name": "Apple Inc.", + "price": 274.43, + "change": 2.31, + "change_percent": 0.85, + "volume": 52129320, + "market_cap": 4200000000000, + "high_52week": 288.62, + "low_52week": 169.21, + "timestamp": "2026-02-05T15:30:00.000000" +} +``` + +--- + +### 3️⃣ /batch — 批量行情查询 + +``` +POST /batch +Content-Type: application/json +``` + +```json +{ + "symbols": ["AAPL", "TSLA", "NVDA", "MSFT", "GOOGL"] +} +``` + +--- + +### 4️⃣ /popular — 热门股票行情 + +``` +GET /popular +``` + +返回 AAPL, MSFT, GOOGL, AMZN, TSLA, NVDA, META 等热门股票行情。 + +--- + +## Agent 2：Stock News Agent + +### 功能概览 + +提供美股 **新闻资讯获取与分析** 能力，支持按股票代码或关键词搜索新闻。 + +支持能力： + +- 股票相关新闻查询 +- 市场动态获取 +- 热门财经新闻 +- **AI 新闻解读与影响分析** + +--- + +### 1️⃣ /chat — 智能对话 + +#### 功能说明 + +通过自然语言获取股票新闻并进行 AI 分析解读。 + +--- + +#### REST API 调用 + +``` +POST /chat +Content-Type: application/json +api-key: your-api-key +``` + +```json +{ + "message": "NVDA 最近有什么重要新闻？" +} +``` + +--- + +#### 返回结果 + +```json +{ + "response": "最近关于NVDA的新闻显示出其股票在盘前交易中表现强劲，市场对其AI芯片业务的前景保持乐观...", + "data": { + "news_count": 5, + "symbols": ["NVDA"] + }, + "timestamp": "2026-02-05T15:31:29.298428" +} +``` + +--- + +### 2️⃣ /news — 获取新闻 + +``` +POST /news +Content-Type: application/json +``` + +```json +{ + "symbol": "AAPL", + "limit": 10 +} +``` + +--- + +#### 参数说明 + +| 参数 | 类型 | 必需 | 默认值 | 说明 | +|------|------|------|--------|------| +| symbol | string | ⚠ | null | 股票代码 | +| query | string | ⚠ | null | 搜索关键词 | +| limit | integer | ❌ | 10 | 返回新闻数量（1-50） | + +> `symbol` 与 `query` 二选一 + +--- + +### 3️⃣ /market — 市场动态 + +``` +GET /market +``` + +返回市场涨跌排行、活跃股票等信息。 + +--- + +### 4️⃣ /trending — 热门新闻 + +``` +GET /trending +``` + +返回当前热门财经新闻。 + +--- + +## Agent 3：Stock Analysis Agent + +### 功能概览 + +提供美股 **技术分析** 能力，计算技术指标并给出交易信号与投资建议。 + +支持能力： + +- 技术指标计算（SMA, RSI, MACD, 布林带） +- 趋势判断（看涨/看跌/中性） +- 买卖信号生成 +- 支撑位/阻力位计算 +- **AI 综合分析与投资建议** + +--- + +### 1️⃣ /chat — 智能对话 + +#### 功能说明 + +通过自然语言获取股票技术分析并由 AI 提供投资建议。 + +--- + +#### REST API 调用 + +``` +POST /chat +Content-Type: application/json +Authorization: Bearer your-api-key +``` + +```json +{ + "message": "帮我分析 AAPL，现在适合买入吗？" +} +``` + +--- + +#### 返回结果 + +```json +{ + "response": "根据技术分析数据，AAPL当前价格为$274.31，趋势为中性，信号为持有。RSI值为66.49，接近超买区域...", + "data": { + "analysis": [ + { + "symbol": "AAPL", + "current_price": 274.31, + "indicators": { + "sma_20": 259.12, + "sma_50": 268.63, + "sma_200": null, + "rsi_14": 66.49, + "macd": -0.9012, + "macd_signal": -0.8111, + "bollinger_upper": 275.39, + "bollinger_lower": 242.84 + }, + "trend": "neutral", + "signal": "hold", + "support_level": 243.42, + "resistance_level": 279.5, + "risk_level": "medium" + } + ], + "symbols": ["AAPL"] + }, + "timestamp": "2026-02-05T15:58:50.578048" +} +``` + +--- + +### 2️⃣ /analyze — 技术分析 + +``` +POST /analyze +Content-Type: application/json +``` + +```json +{ + "symbol": "AAPL" +} +``` + +--- + +#### 返回字段说明 + +| 字段 | 类型 | 说明 | +|------|------|------| +| current_price | float | 当前价格 | +| sma_20 | float | 20日简单移动平均线 | +| sma_50 | float | 50日简单移动平均线 | +| sma_200 | float | 200日简单移动平均线 | +| rsi_14 | float | 14日相对强弱指数 | +| macd | float | MACD 值 | +| macd_signal | float | MACD 信号线 | +| bollinger_upper | float | 布林带上轨 | +| bollinger_lower | float | 布林带下轨 | +| trend | string | 趋势：bullish / bearish / neutral | +| signal | string | 信号：buy / sell / hold | +| support_level | float | 支撑位 | +| resistance_level | float | 阻力位 | +| risk_level | string | 风险等级：low / medium / high | + +--- + +### 3️⃣ /compare — 多股对比 + +``` +POST /compare +Content-Type: application/json +``` + +```json +{ + "symbols": ["AAPL", "MSFT", "GOOGL"] +} +``` + +--- + +### 4️⃣ /screen — 股票筛选 + +``` +GET /screen?trend=bullish&signal=buy +``` + +根据技术指标筛选符合条件的股票。 + +--- + +## 统一错误格式 + +**成功：** + +```json +{ + "response": "AI 分析结果...", + "data": {}, + "timestamp": "2026-02-05T15:30:00.000000" +} +``` + +**认证失败（401）：** + +```json +{ + "detail": "请在请求头中提供 api-key 或 Authorization" +} +``` + +**请求错误（400）：** + +```json +{ + "detail": "错误描述" +} +``` + +**服务器错误（500）：** + +```json +{ + "detail": "Internal Server Error" +} +``` + +--- + +## 调用示例 + +### cURL 示例 + +**使用 api-key Header：** + +```bash +curl -X POST "http://test-stock-quote.taijiagnet.com/chat" \ + -H "Content-Type: application/json" \ + -H "api-key: sk-mPV5MVVVVvfGSkXA-ASQXQ" \ + -d '{"message": "AAPL 和 TSLA 今天表现如何？"}' +``` + +**使用 Authorization Bearer：** + +```bash +curl -X POST "http://test-stock-analysis.taijiagnet.com/chat" \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer sk-mPV5MVVVVvfGSkXA-ASQXQ" \ + -d '{"message": "帮我分析 NVDA，现在适合买入吗？"}' +``` + +--- + +### Python 示例 + +```python +import requests + +API_KEY = "sk-mPV5MVVVVvfGSkXA-ASQXQ" + +# Stock Quote Agent +response = requests.post( + "http://test-stock-quote.taijiagnet.com/chat", + headers={ + "Content-Type": "application/json", + "api-key": API_KEY + }, + json={"message": "AAPL 现在多少钱？"} +) +print(response.json()) + +# Stock News Agent +response = requests.post( + "http://test-stock-news.taijiagnet.com/chat", + headers={ + "Content-Type": "application/json", + "Authorization": f"Bearer {API_KEY}" + }, + json={"message": "TSLA 最近有什么新闻？"} +) +print(response.json()) + +# Stock Analysis Agent +response = requests.post( + "http://test-stock-analysis.taijiagnet.com/chat", + headers={ + "Content-Type": "application/json", + "api-key": API_KEY + }, + json={"message": "帮我技术分析 NVDA"} +) +print(response.json()) +``` + +--- + +## 部署信息 + +| Agent | 模板名称 | 镜像 | 端口 | +|-------|----------|------|------| +| Stock Quote | stock_quote_agent | agnettaiji.azurecr.io/ai-agents/stock-quote-agent:latest | 8080 | +| Stock News | stock_news_agent | agnettaiji.azurecr.io/ai-agents/stock-news-agent:latest | 8080 | +| Stock Analysis | stock_analysis_agent | agnettaiji.azurecr.io/ai-agents/stock-analysis-agent:latest | 8080 | + +--- + +## 环境变量配置 + +| 变量名 | 说明 | 默认值 | +|--------|------|--------| +| LLM_BASE_URL | LLM 服务地址 | https://litellm.graystone-fb459c5d.southeastasia.azurecontainerapps.io/v1 | +| LLM_MODEL | 模型名称 | taiji/gpt-4o-mini | +| SERVICE_HOST | 服务监听地址 | 0.0.0.0 | +| SERVICE_PORT | 服务端口 | 8080 | + +--- + +## 免责声明 + +> ⚠️ **投资有风险，入市需谨慎。** 本 Agent 提供的分析和建议仅供参考，不构成任何投资建议。用户应自行判断并承担投资风险。 + +--- + +*文档版本：v1.0.0* +*更新日期：2026-02-05*