Mo Shoes Agent Adk MCP Alloydb

🏃‍♂️ GenAI Sports-人工智能购物助手

弥合网上购物和个人服务之间的差距

一款智能体育购物助手，由谷歌云平台、代理开发工具包（ADK）、模型上下文协议（MCP）工具箱和AlloyDB提供支持。这种下一代人工智能代理提供了反映店内客户服务的个性化购物体验，解决了在线零售中的根本脱节问题。

______________________________________________________________________

🎥 演示视频


点击上图观看完整演示 | 直连

______________________________________________________________________

🏆 满足竞争标准

✅ 云运行使用率（+5）

完整的云运行架构：

• 后端代理服务：部署在Cloud Run上，支持流媒体响应

- 根据需求自动缩放 - 通过工件注册表进行基于容器的部署 - Vertex AI集成的环境变量配置

• 前端应用程序：通过Cloud Run提供的React SPA

- 基于Nginx的静态文件服务 - OAuth2身份验证集成 - 通过HTTPS实现全球访问

• MCP工具箱服务器：作为微服务托管在Cloud Run上

- 集中工具管理 - Secret Manager集成，实现安全配置 - 基于服务帐户的身份验证

技术实施：

# Backend deployment with Vertex AI integration
gcloud run deploy finn-agent \
    --image us-central1-docker.pkg.dev/$PROJECT_ID/finn-agent-images/finn-agent \
    --set-env-vars="GOOGLE_CLOUD_PROJECT=$PROJECT_ID,GOOGLE_GENAI_USE_VERTEXAI=TRUE"

# Toolbox deployment with secret injection
gcloud run deploy toolbox \
    --set-secrets "/app/tools.yaml=tools:latest"

______________________________________________________________________

✅ GCP数据库使用率（+2）

AlloyDB for PostgreSQL-高级AI就绪数据库：

数据库体系结构：

• 主实例：2个CPU，区域可用性
• 公网IP：已启用AlloyDB Auth Proxy进行开发
• VPC对等：安全的专用网络连接
• 顶点AI集成：从数据库直接访问模型

数据模型：

-- Core tables with geospatial and AI capabilities
users (10 records) - Customer profiles with location data
stores (20 records) - Physical store locations with PostGIS geometry
products (100 records) - Sports equipment catalog with embeddings
orders (dynamic) - Order management with delivery tracking
shopping_lists (dynamic) - User cart management
delivery_methods (per store) - Shipping options with pricing

AI驱动的功能：

1. 矢量嵌入：使用嵌入式产品 text-embedding-005

   SELECT array_dims(embedding('text-embedding-005', 'AlloyDB AI')::real[]);

1. 地理空间查询：用于邻近搜索的PostGIS

   -- Find nearby stores with distance calculation
   SELECT store_name, 
          ST_Distance(location, ST_MakePoint($user_lon, $user_lat)::geography) as distance
   FROM stores
   ORDER BY distance;

1. 语义搜索：使用向量相似性进行自然语言产品发现

______________________________________________________________________

✅ 谷歌的人工智能使用率（+5）

多模型AI集成：

1. 双子座2.5闪光灯 -主要代理大脑

from google.adk.models import Gemini

llm = Gemini(model="gemini-2.5-flash")
agent = Agent(
    name="finn",
    model=llm,
    instruction=prompt,
    tools=[toolbox]
)

能力：

• 产品查询的自然语言理解
• 情境感知对话管理
• 带有订单历史的多回合对话
• 实时交互的流式响应

2. 文本嵌入-005 -语义产品搜索

client = genai.Client(vertexai=True, project=PROJECT_ID, location="us-central1")

# Generate product embeddings for semantic search
for product in products:
    result = client.models.embed_content(
        model='text-embedding-005',
        contents=product_description
    )
    embedding = result.embeddings[0].values

使用案例：

• “寻找适合超跑的跑鞋”→ 与相关产品的语义匹配
• 了解关键字匹配之外的用户意图
• 基于描述相似度的个性化推荐

3. 代理开发工具包（ADK） -编排框架

runner = Runner(
    app_name="finn",
    agent=agent,
    session_service=InMemorySessionService()
)

# Streaming conversation
async for event in runner.run_async(
    session_id=session_id, 
    user_id=user_id, 
    new_message=content
):
    yield event.content.parts[0].text

高级功能：

• 会话上下文的会话管理
• 使用MCP Toolbox集成进行工具调用
• 自动错误处理和重试逻辑
• 跨用户交互的状态持久性

______________________________________________________________________

✅ 功能演示（+5）

完成端到端用户之旅：

特征矩阵：

演示脚本（完整工作流）：

// 1. Authentication
User signs in → OAuth verification → JWT token stored

// 2. Product Discovery
"I'm looking for running shoes for an ultra-trail"
→ Gemini understands intent
→ Vector search in AlloyDB
→ Returns Ultra Glide + recommendations

// 3. Product Exploration
"Tell me more about Ultra Glide"
→ Detailed product card with:
   • Price, sizes, colors
   • AI-generated product image
   • Description and features

// 4. Cart Management
"Add Ultra Glide, size 40, color Red/Grey"
→ Inserts into shopping_lists table
→ Confirmation message

"Show my shopping list"
→ Formatted cart with totals
→ Product images and quantities

// 5. Store Location
"Find stores near me"
→ PostGIS query with user location
→ Interactive map with markers
→ Distance calculation in kilometers

// 6. Order Creation
"Place order for Sports Diagonal Mar"
→ Transaction: cart → orders table
→ Order confirmation with ID

// 7. Order Management
"Check my order status"
→ Query orders by user_id
→ Display items, delivery method, total

// 8. Delivery Customization
"List delivery methods for Sports Diagonal Mar"
→ Show Standard, Express, Next Day options

"Update to Express Delivery for order #X"
→ Update order record
→ Recalculate total with shipping

现场演示功能：

• 流媒体响应：Gemini实时生成文本
• 交互式地图：用于商店可视化的传单集成
• 响应式用户界面：桌面和移动优化的React界面
• 图片库：带模态变焦的产品照片
• 错误处理：优雅的降级和用户反馈

🎬 看看它在行动： 观看完整的演示视频

______________________________________________________________________

✅ 对电子商务行业的影响（+5）

🎯 问题陈述：

网上购物中的个人接触差距

传统电子商务平台存在以下问题：

1. 非个人化浏览：没有像实体店那样的引导式发现
2. 决策瘫痪：没有专家指导的选择太多
3. 有限的上下文帮助：不能问“什么最适合越野跑？”
4. 交易摩擦：查找、比较和购买的多个步骤

行业统计：

• 70%的在线购物者因购物车的复杂性而放弃购物车
• 88%的消费者希望获得个性化体验
• 由于用户体验不佳，每年损失180亿美元

______________________________________________________________________

💡 我们的解决方案：对话式商务

GenAI体育 将网上购物转变为 个性化咨询 通过：

1. 自然语言购物

User: "I need shoes for rocky terrain in the mountains"
Finn: "For rocky mountain terrain, I recommend:
      • Ultra Glide - Aggressive tread, ankle support
      • Trail Blazer Pro - Extra cushioning, waterproof
      Which would you like to explore?"

影响：将产品发现时间缩短65%

2. 情境感知建议

代理人记得：

• 以前的购买
• 购物清单项目
• 首选商店
• 交货偏好

例子：

User: "Find stores near me"
Finn: *Uses stored user location from profile*
      *Suggests stores with inventory for cart items*

3. 无缝多动作工作流

单个对话处理：

• 产品搜索→ 详情→ 加入购物车→ 查找店铺→ 下单→ 跟踪交货

传统电子商务：8页点击次数超过15次\ GenAI体育：1个界面中有6条聊天消息

4. 库存意识建议

与通用产品列表不同，Finn只建议 可用产品 从附近的商店：

-- Behind the scenes query
SELECT p.product_name 
FROM products p
JOIN store_inventory si ON p.product_id = si.product_id
WHERE si.store_id = (SELECT nearest_store FROM user_location)
  AND si.quantity > 0;

______________________________________________________________________

🏢 行业应用

零售体育器材 （主要用例）

• 专业装备需要专业知识（鞋型、尺码、地形匹配）
• 由于不确定性，购物车放弃率很高
• 解决方案：Finn担任具有产品专业知识的虚拟销售助理

通用电子商务

• 时尚：“夏季婚礼服装”
• 电子产品：“1500美元以下的视频编辑笔记本电脑”
• 家居用品：“环保清洁产品”

B2B采购

• 规格复杂的工业用品
• 批量订购与配送物流
• 适应：用SKU替换产品，集成ERP系统

医疗零售

• 基于症状的OTC药物建议
• 通过政策工具遵守医疗指南
• 优势AlloyDB可以存储医学知识图

______________________________________________________________________

📊 可衡量的业务影响

______________________________________________________________________

🔮 未来的创新

1. 多模式搜索

- 上传照片：“找到与这些相似的鞋子” - 通过电话集成进行语音购物

1. 预测性库存

- AlloyDB分析预测库存需求 - “此商品很受欢迎，您所在地区只剩下3件了”

1. AR试穿

- 通过Vertex AI Vision实现虚拟试衣间 - “看看你穿这双鞋怎么样”

1. 社交购物

- 与朋友分享购物车 - 协同购买决策

______________________________________________________________________

🏗️ 技术架构

系统概述

┌─────────────────────────────────────────────────────────────┐
│                         User Interface                      │
│  ┌──────────────────────────────────────────────────────┐  │
│  │  React Frontend (Cloud Run)                          │  │
│  │  • Google OAuth 2.0 Sign-In                          │  │
│  │  • Leaflet Maps for Store Locator                    │  │
│  │  • Streaming Chat UI with Markdown Support           │  │
│  │  • Product Gallery with Modal Zoom                   │  │
│  └──────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
                              ↓ HTTPS
┌─────────────────────────────────────────────────────────────┐
│                    Application Layer                        │
│  ┌──────────────────────────────────────────────────────┐  │
│  │  FastAPI Backend (Cloud Run)                         │  │
│  │  • JWT Token Validation                              │  │
│  │  • Session Management (In-Memory)                    │  │
│  │  • Streaming Response Handler                        │  │
│  │  • Image Serving from Cloud Storage                  │  │
│  └──────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                       AI Agent Layer                        │
│  ┌──────────────────────────────────────────────────────┐  │
│  │  ADK Agent with Gemini 2.5 Flash                     │  │
│  │  • Multi-turn conversation context                   │  │
│  │  • Tool calling orchestration                        │  │
│  │  • Prompt engineering for structured output          │  │
│  │  • Async streaming event processing                  │  │
│  └──────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                       Tool Layer (MCP)                      │
│  ┌──────────────────────────────────────────────────────┐  │
│  │  MCP Toolbox Server (Cloud Run)                      │  │
│  │  • 15+ Database Tools (CRUD operations)              │  │
│  │  • Google Sign-In Authentication Provider            │  │
│  │  • tools.yaml Configuration (Secret Manager)         │  │
│  │  • AlloyDB Connection Pool Management                │  │
│  └──────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                      Data Layer                             │
│  ┌────────────────────┐  ┌────────────────────────────┐    │
│  │  AlloyDB           │  │  Vertex AI Platform        │    │
│  │  PostgreSQL 16     │  │  • Gemini 2.5 Flash        │    │
│  │  • Users           │  │  • Text-Embedding-005      │    │
│  │  • Products        │  │                            │    │
│  │  • Stores          │  └────────────────────────────┘    │
│  │  • Orders          │                                     │
│  │  • Shopping Lists  │  ┌────────────────────────────┐    │
│  │  • Delivery Methods│  │  Cloud Storage             │    │
│  │  • PostGIS Enabled │  │  • Product Images (100)    │    │
│  └────────────────────┘  │  • Public Access Enabled   │    │
│                          └────────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                   Infrastructure Layer                      │
│  • VPC with Private Service Peering                         │
│  • AlloyDB Auth Proxy for Secure Connections               │
│  • Artifact Registry for Container Images                   │
│  • Secret Manager for Credentials                           │
│  • Cloud Build for CI/CD                                    │
│  • IAM Service Accounts with Least Privilege               │
└─────────────────────────────────────────────────────────────┘

______________________________________________________________________

部件分解

前端（React+Vite）

// Location: src/frontend/src/pages/Home.jsx
const Home = ({ idToken, setIdToken }) => {
  const [messages, setMessages] = useState([]);
  const [isChatOpen, setIsChatOpen] = useState(false);
  
  // Streaming response handler
  const handleSendMessage = async () => {
    const response = await fetch(`${BACKEND_URL}/chat`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${idToken}`
      },
      body: JSON.stringify({ message, history })
    });
    
    const reader = response.body.getReader();
    let aiText = "";
    while (true) {
      const { value, done } = await reader.read();
      if (done) break;
      aiText += decoder.decode(value);
      setMessages(prev => [...prev, { role: 'assistant', content: aiText }]);
    }
  };
};

主要特点：

• OAuth 2.0与Google登录的集成
• 地理空间可视化小册子地图
• 用于结构化AI输出的自定义markdown渲染器
• 产品照片的图像模式库
• 采用Tailwind CSS的响应式设计

______________________________________________________________________

后端（FastAPI+ADK）

# Location: src/backend/app.py
@app.post("/chat")
async def chat(request: Request):
    data = await request.json()
    message = data.get('message')
    session_id = data.get('session_id') or str(uuid.uuid4())
    user_id = data.get('user_id') or "default-user"
    id_token = request.headers.get('Authorization')
    
    # Call ADK agent with streaming
    event_stream = await finn_chat(message, history, session_id, user_id, id_token)
    return StreamingResponse(event_stream(), media_type="text/plain")

责任：

• 来自Google OAuth的JWT令牌验证
• 会话ID管理，确保对话连续性
• 来自ADK的流响应聚合
• 从云存储提供静态映像服务
• 跨源请求的CORS配置

______________________________________________________________________

AI代理（ADK+Gemini）

# Location: src/backend/finn_agent.py
async def process_message(message, history, session_id, user_id, id_token):
    # Dynamic auth token provider
    async def get_auth_token():
        if id_token and id_token.startswith("Bearer "):
            return id_token[len("Bearer "):]
        return id_token if id_token else ""
    
    # Configure toolbox with authentication
    toolbox = ToolboxToolset(
        server_url="https://toolbox-{PROJECT_NUM}.us-central1.run.app",
        toolset_name="my-toolset",
        auth_token_getters={"google_signin": get_auth_token}
    )
    
    # Initialize agent
    agent = Agent(
        name="finn",
        model=Gemini(model="gemini-2.5-flash"),
        instruction=prompt,  # 300+ line structured prompt
        tools=[toolbox]
    )
    
    # Run with streaming
    async for event in runner.run_async(session_id, user_id, new_message):
        yield event.content.parts[0].text

代理能力：

• 上下文感知对话（记住用户id、偏好）
• 刀具选择逻辑（15+刀具可用）
• 结构化输出格式（产品、订单、商店）
• 错误恢复和重试机制

______________________________________________________________________

MCP工具箱配置

# Location: src/toolbox/tools.yaml
sources:
  alloydb_source:
    type: alloydb
    host: "/cloudsql/PROJECT_ID:REGION:CLUSTER/INSTANCE"
    database: store
    user: postgres
    password: alloydb

authentication_providers:
  google_signin:
    type: oauth_client_id
    client_id: "YOUR_OAUTH_CLIENT_ID.apps.googleusercontent.com"

tools:
  search_products:
    type: sql
    source: alloydb_source
    description: "Search products by keywords using semantic search"
    query: |
      SELECT product_name, brand, price, category, description
      FROM products
      WHERE description ILIKE '%' || :keyword || '%'
      LIMIT 10
    
  get_nearby_stores:
    type: sql
    source: alloydb_source
    description: "Find stores near user location"
    query: |
      SELECT 
        store_name,
        ST_Distance(location, ST_MakePoint(:user_lon, :user_lat)::geography) as distance,
        ST_X(location::geometry) as longitude,
        ST_Y(location::geometry) as latitude
      FROM stores
      ORDER BY distance
      LIMIT 20
  
  create_order:
    type: sql
    source: alloydb_source
    description: "Place order from shopping cart"
    query: |
      INSERT INTO orders (user_id, store_id, total_amount, shipping_address, status)
      VALUES (:user_id, :store_id, :total_amount, :shipping_address, 'pending')
      RETURNING order_id

15种可用工具：

1. search_products -语义产品搜索
2. get_product_details -完整的产品规格
3. add_to_shopping_list -购物车管理
4. get_shopping_list -查看购物车商品
5. get_nearby_stores -地理空间商店查找器
6. create_order -下单
7. get_user_orders -订单历史
8. update_order_delivery -配送方式更新
9. get_delivery_methods -可用的运输选项
10. get_store_inventory -库存检查
11. search_products_by_brand -品牌过滤
12. search_products_by_category -类别浏览
13. get_user_profile -用户数据检索
14. remove_from_shopping_list -购物车商品移除
15. check_product_availability -库存验证

______________________________________________________________________

AlloyDB架构

-- Users with geospatial location
CREATE TABLE users (
    user_id SERIAL PRIMARY KEY,
    first_name VARCHAR(100),
    last_name VARCHAR(100),
    email VARCHAR(255) UNIQUE NOT NULL,
    address VARCHAR(255),
    city VARCHAR(100),
    postal_code VARCHAR(20),
    location GEOGRAPHY(POINT, 4326)  -- PostGIS for proximity queries
);

-- Products with AI embeddings
CREATE TABLE products (
    product_id SERIAL PRIMARY KEY,
    product_name VARCHAR(255) NOT NULL,
    brand VARCHAR(100),
    category VARCHAR(100),
    price DECIMAL(10, 2),
    description TEXT,
    sizes VARCHAR(100),
    colors VARCHAR(100),
    embedding VECTOR(768)  -- Text-Embedding-005 vectors
);

-- Stores with PostGIS geometry
CREATE TABLE stores (
    store_id SERIAL PRIMARY KEY,
    store_name VARCHAR(255) NOT NULL,
    address VARCHAR(255),
    city VARCHAR(100),
    postal_code VARCHAR(20),
    location GEOGRAPHY(POINT, 4326),  -- Geospatial indexing
    phone VARCHAR(20)
);

-- Orders with delivery tracking
CREATE TABLE orders (
    order_id SERIAL PRIMARY KEY,
    user_id INTEGER REFERENCES users(user_id),
    store_id INTEGER REFERENCES stores(store_id),
    total_amount DECIMAL(10, 2),
    shipping_address VARCHAR(255),
    status VARCHAR(50),  -- pending, processing, shipped, delivered
    delivery_method_id INTEGER REFERENCES delivery_methods(method_id),
    created_at TIMESTAMP DEFAULT NOW()
);

-- Dynamic shopping lists
CREATE TABLE shopping_lists (
    list_id SERIAL PRIMARY KEY,
    user_id INTEGER REFERENCES users(user_id),
    product_id INTEGER REFERENCES products(product_id),
    quantity INTEGER DEFAULT 1,
    size VARCHAR(50),
    color VARCHAR(50),
    added_at TIMESTAMP DEFAULT NOW()
);

______________________________________________________________________

数据流示例：“查找跑鞋”

┌──────────────────────────────────────────────────────────────┐
│ 1. User Input: "I'm looking for running shoes for trail"    │
└──────────────────────────────────────────────────────────────┘
                           ↓
┌──────────────────────────────────────────────────────────────┐
│ 2. Frontend sends POST to /chat with:                       │
│    • message: "I'm looking for running shoes for trail"     │
│    • session_id: "abc-123"                                   │
│    • user_id: 5                                              │
│    • Authorization: Bearer {JWT_TOKEN}                       │
└──────────────────────────────────────────────────────────────┘
                           ↓
┌──────────────────────────────────────────────────────────────┐
│ 3. FastAPI Backend validates JWT and passes to ADK Agent    │
└──────────────────────────────────────────────────────────────┘
                           ↓
┌──────────────────────────────────────────────────────────────┐
│ 4. Gemini 2.5 Flash processes intent:                       │
│    • Recognizes: product search query                        │
│    • Extracts keywords: "running shoes", "trail"             │
│    • Selects tool: search_products                           │
└──────────────────────────────────────────────────────────────┘
                           ↓
┌──────────────────────────────────────────────────────────────┐
│ 5. ADK calls MCP Toolbox:                                   │
│    GET https://toolbox-.../api/tools/search_products        │
│    Body: { "keyword": "running trail shoes" }               │
│    Headers: { "Authorization": "Bearer {JWT}" }             │
└──────────────────────────────────────────────────────────────┘
                           ↓
┌──────────────────────────────────────────────────────────────┐
│ 6. MCP Toolbox executes AlloyDB query:                      │
│    SELECT product_name, brand, price, description            │
│    FROM products                                             │
│    WHERE category = 'Running'                                │
│      AND description ILIKE '%trail%'                         │
│    ORDER BY similarity(embedding, query_embedding) DESC      │
│    LIMIT 10;                                                 │
└──────────────────────────────────────────────────────────────┘
                           ↓
┌──────────────────────────────────────────────────────────────┐
│ 7. AlloyDB returns results:                                 │
│    [                                                         │
│      { name: "Ultra Glide", brand: "Salomon", price: 159 }, │
│      { name: "Speedgoat 5", brand: "Hoka", price: 175 },   │
│      ...                                                     │
│    ]                                                         │
└──────────────────────────────────────────────────────────────┘
                           ↓
┌──────────────────────────────────────────────────────────────┐
│ 8. Gemini formats response using structured prompt rules:   │
│    "Here are some products:                                  │
│    • Product: Ultra Glide                                    │
│    Image: Ultra Glide                                        │
│    Salomon's flagship trail shoe with aggressive tread...    │
│                                                              │
│    • Product: Speedgoat 5                                    │
│    Image: Speedgoat 5                                        │
│    Hoka's cushioned trail runner with Vibram outsole..."     │
└──────────────────────────────────────────────────────────────┘
                           ↓
┌──────────────────────────────────────────────────────────────┐
│ 9. FastAPI streams response chunk-by-chunk to frontend      │
└──────────────────────────────────────────────────────────────┘
                           ↓
┌──────────────────────────────────────────────────────────────┐
│ 10. React renders:                                           │
│     • Product cards with images from Cloud Storage           │
│     • Clickable product names for details                    │
│     • Modal zoom for product photos                          │
└──────────────────────────────────────────────────────────────┘

______________________________________________________________________

🚀 部署指导

先决条件

• 启用计费的谷歌云项目
• gcloud CLI已安装并经过身份验证
• Python 3.11+
• Node.js 18+
• psql PostgreSQL客户端

1.环境设置

export PROJECT_ID=your-project-id
export REGION=us-central1

gcloud config set project $PROJECT_ID
gcloud services enable \
  alloydb.googleapis.com \
  compute.googleapis.com \
  run.googleapis.com \
  cloudbuild.googleapis.com \
  artifactregistry.googleapis.com \
  aiplatform.googleapis.com \
  secretmanager.googleapis.com

2.AlloyDB部署

# Create VPC and peering
gcloud compute networks create default --subnet-mode=auto

gcloud compute addresses create peering-range-for-alloydb \
  --global \
  --purpose=VPC_PEERING \
  --prefix-length=16 \
  --network=default

gcloud services vpc-peerings connect \
  --service=servicenetworking.googleapis.com \
  --ranges=peering-range-for-alloydb \
  --network=default

# Create AlloyDB cluster
gcloud alloydb clusters create alloydb-cluster \
  --password=alloydb \
  --network=default \
  --region=$REGION \
  --database-version=POSTGRES_16

# Create primary instance
gcloud alloydb instances create alloydb-inst \
  --instance-type=PRIMARY \
  --cpu-count=2 \
  --region=$REGION \
  --cluster=alloydb-cluster \
  --availability-type=ZONAL \
  --ssl-mode=ALLOW_UNENCRYPTED_AND_ENCRYPTED

# Enable Vertex AI integration
PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:service-$PROJECT_NUMBER@gcp-sa-alloydb.iam.gserviceaccount.com" \
  --role="roles/aiplatform.user"

3.数据库初始化

# Start AlloyDB Auth Proxy
wget https://storage.googleapis.com/alloydb-auth-proxy/v1.13.6/alloydb-auth-proxy.linux.amd64 -O alloydb-auth-proxy
chmod +x alloydb-auth-proxy
./alloydb-auth-proxy "projects/$PROJECT_ID/locations/$REGION/clusters/alloydb-cluster/instances/alloydb-inst" --public-ip &

# Load schema and data
psql -h 127.0.0.1 -U postgres -c "CREATE DATABASE store;"
psql -h 127.0.0.1 -U postgres -d store -f data/store_backup.sql

4.OAuth配置

# Create OAuth consent screen (via Console)
# Then create OAuth Client ID
gcloud alpha iap oauth-brands create \
  --application_title="GenAI Sports" \
  --support_email=your-email@example.com

# Save the generated CLIENT_ID for later

5.MCP工具箱部署

cd src/toolbox

# Update tools.yaml with your credentials
cat > tools.yaml  iam-policy.json

# Add audit config for AlloyDB
# (Manual step via Console or gcloud alpha commands)

______________________________________________________________________

🤝 贡献

我们欢迎捐款！请参阅我们的投稿指南：

1. 分叉存储库
2. 创建要素分支(git checkout -b feature/amazing-feature)
3. 提交更改(git commit -m 'Add amazing feature')
4. 推送到分支(git push origin feature/amazing-feature)
5. 打开拉取请求

开发设置

# Backend
cd src/backend
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
uvicorn app:app --reload --port 8001

# Frontend
cd src/frontend
npm install
npm run dev

______________________________________________________________________

📚 文档

• AlloyDB设置指南
• 云运行部署
• MCP工具箱配置
• API 参考 （即将推出）

______________________________________________________________________

🐛 故障排除

常见问题

问题：AlloyDB的“连接被拒绝”

# Ensure Auth Proxy is running
ps aux | grep alloydb-auth-proxy

# Check firewall rules
gcloud compute firewall-rules list --filter="name:allow-ssh"

# Verify VPC peering
gcloud services vpc-peerings list --network=default

问题：未找到工具箱工具

# Verify secret is updated
gcloud secrets versions access latest --secret=tools

# Check toolbox logs
gcloud logging read "resource.labels.service_name=toolbox" --limit 50

# Redeploy with latest secret
gcloud run services update toolbox \
  --update-secrets "/app/tools.yaml=tools:latest"

问题：前端显示“需要登录”

# Verify OAuth Client ID
grep -r "YOUR_OAUTH_CLIENT_ID" src/frontend/

# Check CORS configuration in backend
grep -A5 "CORSMiddleware" src/backend/app.py

# Validate JWT token format
# Should be: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

问题：双子座的反应被切断

# Increase streaming buffer size in backend
# Edit src/backend/finn_agent.py:
# streaming_config = types.GenerationConfig(max_output_tokens=8192)

______________________________________________________________________

📝 许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

______________________________________________________________________

🙏 致谢

• 谷歌云平台 基础设施和人工智能服务
• 代理开发工具包（ADK） 强大的编排框架团队
• 模型上下文协议（MCP） 实现无缝工具集成
• AlloyDB 人工智能就绪PostgreSQL数据库团队
• 双子座人工智能 自然语言理解能力

______________________________________________________________________

📞 支持

如有疑问或问题：

• GitHub问题: 创建问题
• 电子邮件: support@genai-sports.example.com
• 文档: 维基

______________________________________________________________________

🎯 路线图

2025年第一季度

• \[\]多语言支持（西班牙语、法语、德语）
• \[\]通过语音转文本API进行语音交互
• \[\]使用协同过滤的产品推荐引擎

2025年第二季度

• \[\]移动应用程序（React Native）
• \[\]使用Vertex AI Vision进行AR尝试
• \[\]库存管理仪表板

2025年第3季度

• \[\]B2B采购门户
• \[\]多租户架构
• \[\]使用BigQuery进行高级分析

2025年第四季度

• \[\]全球扩张（多区域部署）
• \[\]基于区块链的忠诚度计划
• \[\]人工智能驱动的需求预测

______________________________________________________________________

建于❤️ 使用谷歌云平台