taijibaga/agent_management
9
0
Fork 0
forked from zhanggangyong/agent_management
Code Pull Requests Activity

docs: 添加美股 AI Agent 文档

Browse Source
This commit is contained in:
zhanggangyong
2026-02-05 16:10:53 +00:00
parent 70d9328afc
commit abe3f690ec
1 changed files with 563 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/STOCK_AGENTS_DOC.md
+563
View File
@@ -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*