Capital Markets Associate

混合股权资本市场合伙人

Equity Capital Markets Associate是一个多代理交易助手，使用Google ADK进行开发，使用FastAPI进行部署。它包括四名专家（Orchestrator、Portfolio、Analytics、Trader）、一个共享的MCP工具客户端、通过gRPC的Graylog仪器和一个兼容LiteLLM的模型设置，使您能够用本地Ollama/MLX模型替换Gemini，以保持安全合规性。

仓库布局

• agents//agent.py --具有遥测+SQLite会话连接的单个ADK代理。
• common/ --共享配置、MCP客户端、遥测挂钩、Telegram批准和工具。
• fastapi_app/main.py --统一的FastAPI服务，可挂载以下所有代理 /agents/ 并暴露 /orchestrate 用于API客户端。
• reference/ --背景文档、架构说明、MCP工具目录。
• .env.example --所有必需的秘密和运行时旋钮（Graylog、MCP服务器、Telegram、LiteLLM等）。

环境设置

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
# Edit .env with Google API key, MCP URL (0.0.0.0:8085), Graylog endpoint (0.0.0.0:4317), Telegram data, and MCP allowlists per agent

集 MODEL_PROVIDER=gemini 默认使用Gemini Cloud或切换到 MODEL_PROVIDER=litellm 随着 LITELLM_BASE_URL （例如。， http://localhost:11434 Ollama）和 LITELLM_MODEL 指向所需的局部模型。会话文件位于 data/sessions/.db；部署时保持此文件夹持久。

代理到代理URL

运行整合的FastAPI服务器时，编排器通过挂载的路由到达对等端：

• PORTFOLIO_URL=http://localhost:8080/agent-proxy/portfolio
• ANALYTICS_URL=http://localhost:8080/agent-proxy/analytics
• TRADER_URL=http://localhost:8080/agent-proxy/trader
• ORCHESTRATOR_URL=http://localhost:8080/agent-proxy/orchestrator

如果您单独推出代理商 adk web，覆盖这些选项以指向每个代理的端口（例如 http://localhost:8011 投资组合代理）。

Docker使用

本地开发（Docker桌面）

docker compose up --build
# or rebuild after dependency changes: docker compose build --no-cache

• 该堆栈现在包括一个OpenTetry收集器(otel-collector 控制），Zipkin(:9411)Graylog用户界面(:9000)MongoDB、OpenSearch和FastAPI服务。FastAPI保持启用 http://localhost:8080；OTLP gRPC/HTTP端点在 4317/4318 用于故障排除。
• .env 自动加载；用Graylog OTLP gRPC输入更新它(GRAYLOG_OTLP_EXPORTER_ENDPOINT，默认值 0.0.0.0:4317)，MCP主机(0.0.0.0:8085)、电报数据和模型设置。应用程序会自动发送到 otel-collector:4317 除非你覆盖 GRAYLOG_OTLP_GRPC_ENDPOINT.
• MCP客户端通过env变量实现每个工具的覆盖，例如 MCP_TOOL_ENDPOINT_get_positions=GET:/positions/false使用此格式将工具映射到自定义路线（例如。， MCP_TOOL_ENDPOINT_technical_analysis=GET:/market/analysis/{topic} --占位符被有效载荷值替换）。默认回退为 POST /tools/.
• 使用Docker桌面日志或 docker compose logs -f trader-agent 检查Graylog出口事件。
• Graylog：浏览至 http://localhost:9000 （除非被覆盖，否则为admin/admin）。OTLP/Zipkin默认已连接；Zipkin跨度为 http://localhost:9411.

会话数据库迁移

如果集装箱拒绝启动 Database ... seems to use an old schema，升级后迁移持久会话文件 google-adk:

python scripts/migrate_session_dbs.py

该脚本升级下的每个SQLite文件 data/sessions/，将上一个副本备份到 .db.bak 在交换迁移的数据库之前（或存档旧文件，以便在迁移助手不可用的情况下创建新的模式）。

生产VM部署

# On the VM
docker build -t registry.example.com/trader-agent:prod .
docker run -d \
  --name trader-agent \
  --env-file /opt/agent/.env \
  -p 8080:8080 \
  -v /opt/agent/data/sessions:/app/data/sessions \
  registry.example.com/trader-agent:prod

• 确保从VM到Graylog的出站连接(0.0.0.0:4317)，MCP服务器(0.0.0.0:8085)，以及Gemini或LiteLLM端点。
• 镜子 .env 将密钥转移到VM上，并与容器重建分开轮换凭据。
• 对于舰队部署，将构建的映像推送到注册表，然后使用相同的 docker run 或使用VM特定卷编写文件。

使用ADK Web UI进行开发

每个代理都可以使用ADK CLI启动，同时重用共享模块：

cd agents/orchestrator
adk web --agent-dir . --host 0.0.0.0 --port 8010
# Repeat for portfolio (8011), analytics (8012), trader (8013)

代理之间的流量通过OTLP gRPC记录，因此请先确认Graylog连接(GRAYLOG_OTLP_GRPC_ENDPOINT=0.0.0.0:4317).

FastAPI部署

准备好以编程方式提供流量后，在一个FastAPI进程后运行所有代理：

uvicorn fastapi_app.main:app --host 0.0.0.0 --port 8080 --workers 2

• /health --准备状态加上型号提供商信息。
• /agents//run --为每个代理挂载的本机ADK端点。
• /orchestrate --通过ASGI将请求直接代理到Orchestrator的快捷方式。

所有端点都会发出结构化事件(api.*, tool.*, model.io)Graylog。通过编辑调整采样 GRAYLOG_TRACE_SAMPLE_RATIO 在 .env.

示例 curl

curl -X POST http://localhost:8080/orchestrate \
  -H "Content-Type: application/json" \
  -d '{
        "text": "Summarize my current holdings and recommend an adjustment.",
        "session_id": "demo-session-001",
        "user_id": "cli-user",
        "agent": "orchestrator"
      }'

响应反映了本地ADK有效负载，返回编排器的推理链和从下游代理编译的最终消息。

技术分析运行示例（QQQ）

请求：

curl --request POST \
  --url http://localhost:8080/orchestrate \
  --header 'Content-Type: application/json' \
  --data '{
    "text": "Can you please get technical analysis on QQQ ",
    "session_id": "demo-session-022",
    "user_id": "cli-user",
    "agent": "orchestrator"
  }'

示例响应（为了可读性而截断）：

[
  {
    "modelVersion": "gemini-2.0-flash-exp",
    "content": {
      "parts": [
        {
          "functionCall": {
            "name": "consult_analytics",
            "args": {"question": "Provide technical analysis on QQQ"}
          }
        }
      ],
      "role": "model"
    },
    "author": "orchestrator"
  },
  {
    "content": {
      "parts": [
        {
          "functionResponse": {
            "name": "consult_analytics",
            "response": {
              "result": [
                {"content": {"parts": [{"functionCall": {"name": "generate_market_insight", "args": {"topic": "QQQ"}}}], "role": "model"}},
                {"content": {"parts": [{"functionResponse": {"name": "generate_market_insight", "response": {"symbol": "QQQ", "current_price": 590.07, "ma_distances": {"ma1hr": {"value": 601.69, "distance_percent": -1.93}, "ema9": {"value": 600.91, "distance_percent": -1.8}, "ma10": {"value": 605.87, "distance_percent": -2.61}, "ema21": {"value": 607.56, "distance_percent": -2.88}, "ma30": {"value": 612.3, "distance_percent": -3.63}, "ma50": {"value": 607.15, "distance_percent": -2.81}, "ma100": {"value": 587.55, "distance_percent": 0.43}, "ma200": {"value": 543.5, "distance_percent": 8.57}}, "atr": {"atr_percentage": 1.86}, "rsi": {"rsi": 43.16098073397344}, "adx": {"adx": 15.267777641919679}}}}], "role": "user"}},
                {"content": {"parts": [{"text": "Here's a technical analysis of QQQ..."}], "role": "model"}}
              ]
            }
          }
        }
      ],
      "role": "user"
    },
    "author": "orchestrator"
  },
  {
    "content": {
      "parts": [
        {
          "text": "The Analytics Agent provided a technical analysis of QQQ ... Short-term neutral to slightly bearish, long-term bullish."
        }
      ],
      "role": "model"
    },
    "author": "orchestrator"
  }
]

MCP、电报和治理

• 编辑 *_MCP_TOOL_ALLOWLIST 用于限制每个代理可见哪些模型上下文协议工具的变量。将映射记录在 reference/MCP_TOOLS.md.
• 电报审批需要 TELEGRAM_BOT_TOKEN, TELEGRAM_CHAT_ID，以及 TELEGRAM_APPROVER_USERNAME.Set HUMAN_APPROVAL_REQUIRED=false 绕过自动化测试的工作流程。
• Orchestrator、Portfolio、Analytics和Trader工具调用MCP服务器 0.0.0.0:8085 重试和详细的日志记录。更新 .env 如果服务器URL或身份验证令牌更改。

MCP端点图

MCP endpoints across agents

可观测性

• 日志、跟踪和自定义事件通过捆绑的OpenTetry Collector（contrib构建）流式传输。代理将OTLP gRPC流量发送到 otel-collector:4317；收集器将跟踪转发到Zipkin，并将日志转发到您配置的OTLP端点。
• 如果部署在Docker Desktop之外，请在VM上运行收集器sidecar（使用 observability/otel-collector-config.yaml)或点 GRAYLOG_OTLP_GRPC_ENDPOINT 直接在现有的收集器/遥测后端。
• 使用 reference/ 用于捕获从交易代理参考存储库同步的仪表板或工具模式的文件夹： ~/AI Agents Intensive 5 Day Google-Kaggle/capstone_project/trading-agents.

可观察性屏幕截图

Graylog log stream

Trace overview spans

MCP服务器（外部依赖）

此仓库不附带MCP服务器。代理使用的端点是通过以下方式生成的 FastMCP 来自OpenAPI规范，该规范封装了一个私有REST层，结合了 API贸易站 和那个 财务建模准备API.Point MCP_SERVER_URL 到您正在运行的tMCP实例；中的工具端点覆盖 .env 将代理工具名称映射到生成的路线。

问题、解决方案和价值

• 问题个人交易员和小型团队缺乏一个受管理的工作流程，无法将投资组合状态、分析和执行结合起来，同时让人们了解风险和合规性。
• 解决方案：一个由MCP工具、批准和可观察性支持的多代理交易副驾驶，分工明确（协调器、投资组合、分析、交易员）。FastAPI将所有代理托管在一个API后面，以供编程使用。
• 价值：通过可审计的工具调用、人工门控执行和可插拔模型（默认为Gemini，LiteLLM/Ollama可选）做出更快、更安全的交易决策。

架构概述

Agent Workflow

CMA工作流程：img/CMA_workflow.png

sequenceDiagram
    participant U as User/API
    participant F as FastAPI gateway
    participant O as Orchestrator
    participant A as Analytics
    participant P as Portfolio
    participant T as Trader
    participant M as MCP (FastMCP/OpenAPI)
    participant TS as TradeStation API
    participant FMP as FMP API
    participant OC as OTel Collector
    participant Z as Zipkin
    participant G as Graylog

    U->>F: POST /orchestrate
    F->>O: Proxy /run
    O->>A: consult_analytics(question)
    A->>M: technical_analysis(topic)
    M->>TS: Market data
    M->>FMP: Fundamentals/technicals
    M-->>A: Analysis payload
    O->>P: (if needed) fetch positions
    O->>T: (if needed) trade/approval
    A-->>O: Analysis summary
    O-->>F: Orchestrated response
    F-->>U: Final answer

    F->>OC: OTLP logs/traces
    O->>OC: OTLP logs/traces
    A->>OC: OTLP logs/traces
    P->>OC: OTLP logs/traces
    T->>OC: OTLP logs/traces
    OC-->>Z: Traces
    OC-->>G: Logs

渲染SVG：参考/架构.SVG

• 代理安装在一个FastAPI进程下，以实现低延迟路由；如果需要，URL可以指向外部代理进程。
• MCP工具客户端强制执行每个代理的分配列表，并通过env支持端点覆盖。
• 人工审批通过Telegram进行（或在 .env 用于测试）。
• 会话数据库是每个代理下的SQLite文件 data/sessions.

演示（失眠）

Insomnia demo

演示的功能

• 通过专家之间的委托呼叫进行多代理协调(agents/orchestrator/agent.py → 投资组合/分析/交易员）。
• 通过MCP与工具集成，包括分配列表、重试和端点覆盖(common/mcp.py, common/tools.py).
• 执行的人在循环治理(common/notifications.py，用于审批的交易员工具）。
• OTLP导出到Graylog的可观察性(common/telemetry.pydocker组成收集器）。
• 模型提供者抽象：Gemini默认，LiteLLM/Ollama替代(common/models.py, .env 旗帜）。
• 通过每个代理的SQLite存储进行会话/状态管理(common/sessions.py).

快速入门和使用清单

1. 安装deps并复制env： python -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt && cp .env.example .env
2. 填充 .env 随着 GOOGLE_API_KEY, MCP_SERVER_URLGraylog端点、Telegram信誉（或设置 HUMAN_APPROVAL_REQUIRED=false 当地）。
3. 在本地运行： uvicorn fastapi_app.main:app --host 0.0.0.0 --port 8080
4. 呼叫编排器（示例）：

curl -X POST http://localhost:8080/orchestrate \
  -H "Content-Type: application/json" \
  -d '{
        "text": "Summarize my current holdings and recommend an adjustment.",
        "session_id": "demo-session-001",
        "user_id": "cli-user",
        "agent": "orchestrator"
      }'

预期行为：编排器通过MCP工具查询投资组合/分析，总结结果，并通过批准检查将执行推迟给交易者。

部署说明

• Docker Compose（本地）: docker compose up --build （包括FastAPI+Otel收集器）。坚持 data/sessions 如果需要，可以通过音量调节。
• VM/容器运行时：构建 docker build -t trader-agent:prod . 然后跑步 -v /opt/agent/data/sessions:/app/data/sessions 和 --env-file /opt/agent/.env.
• 云运行/代理引擎：相同的图像作品；暴露端口8080，并确保对MCP和Graylog的出站访问。文档部署的URL和示例运行在编写中（如果使用）。

Gemini用法

• 默认提供程序是Gemini(MODEL_PROVIDER=gemini, DEFAULT_GOOGLE_MODEL=gemini-2.0-flash-exp).集 GOOGLE_API_KEY 并联系任何代理人；响应中注明了提供者 /health.
• 要切换到本地模型，请设置 MODEL_PROVIDER=litellm, LITELLM_BASE_URL，以及 LITELLM_MODEL （例如。， ollama/gemma:2b).