使用说明

A2A CR Box - 企业内容发现代理

一个由Gemini驱动的专业企业内容发现助手，专注于Box内容搜索、AI分析、文档生成、FOIA合规性检查以及MCP集成。

🚀 功能

核心能力

盒内内容搜索在Box中查找文件、文档和文件夹
Box AI 问答就特定文件内容提出有洞察力的问题
盒式集线器询问自动发现并使用最相关的Box Hub
Box 文档生成器使用模板生成专业的资本调用通知及其他文件
盒式MCP（多芯片封装）集成利用Leverage Box MCP远程服务器提升AI能力并实现跨平台集成
《信息自由法》（FOIA）合规应用《信息自由法》元数据模板并生成合规报告
企业内容发现查找特定的文件、监管档案、报告和业务内容
专业沟通以企业为重点的恰当商务回应

可用工具

框选搜索 - 在您的Box企业中查找文档和文件
Box AI 问答 - 使用Box AI询问特定文件内容的问题
Box Hub 询问 - 自动发现并使用最相关的知识中心
Box 文档生成器 使用Box Doc Gen API生成出资通知和其他文件
Box MCP 工具 - 通过Box MCP远程服务器增强AI功能
《信息自由法》（FOIA）处理流程 - 应用合规元数据并生成审计报告
资金调用工作流程 - 完整的资本调用通知创建工作流程

🏗️ 建筑学

**Google ADK（代理开发工具包）**为GeminiAgent提供动力
**Box Python SDK（Box Python软件开发工具包）**处理Box API的认证和操作
JWT 认证使用Box实现安全的服务器到服务器身份验证
**Cloud Run（云运行）**作为可扩展的容器化服务进行部署
AgentSpace 集成准备好进行Discovery Engine注册

🔧 设置

先决条件

Python 3.9+（或 Python 3.9及以上版本）
Google Cloud Platform 账户
带有JWT应用凭据的Box开发者账户

安装

克隆仓库

git clone <your-repo-url>
cd A2A_CR_Box

安装依赖项
```
pip install -r requirements.txt
```

配置 Box JWT 认证

选项A：本地JWT配置（开发环境）

复制 box_jwt_config.example.json 到；向；对于；在……方面；关于 box_jwt_config.json
填写您的Box JWT应用程序凭据：
- clientID
- clientSecret
- enterpriseID
- publicKeyID
- privateKey
- passphrase

选项B：Google Secret Manager（生产环境 - 推荐）

这是一种安全且已准备好投入生产的方案，它将您的JWT凭证存储在Google Secret Manager中，而不是本地文件中。

第一步：启用密钥管理器API

gcloud services enable secretmanager.googleapis.com --project=your-project-id

步骤2：创建Box JWT密钥

# Create secret for Box Client ID
echo -n "your_client_id_here" | gcloud secrets create box-client-id --data-file=- --project=your-project-id

# Create secret for Box Client Secret  
echo -n "your_client_secret_here" | gcloud secrets create box-client-secret --data-file=- --project=your-project-id

# Create secret for Box Public Key ID
echo -n "your_public_key_id_here" | gcloud secrets create box-public-key-id --data-file=- --project=your-project-id

# Create secret for Box Private Key (the entire PEM content)
gcloud secrets create box-private-key --data-file=path/to/your/private_key.pem --project=your-project-id

# Create secret for Box Private Key Passphrase
echo -n "your_passphrase_here" | gcloud secrets create box-private-key-passphrase --data-file=- --project=your-project-id

# Create secret for Box Enterprise ID
echo -n "your_enterprise_id_here" | gcloud secrets create box-enterprise-id --data-file=- --project=your-project-id

步骤3：使用安装脚本（最简单的方法）

将此脚本保存为 box_jwt_secrets_setup.sh：

#!/bin/bash
# box_jwt_secrets_setup.sh

echo "🔐 Setting up Box JWT secrets in Google Secret Manager..."
echo ""

# Prompt for credentials
read -p "Enter Box Client ID: " BOX_CLIENT_ID
read -p "Enter Box Client Secret: " BOX_CLIENT_SECRET
read -p "Enter Box Public Key ID: " BOX_PUBLIC_KEY_ID
read -p "Enter Box Enterprise ID: " BOX_ENTERPRISE_ID
read -s -p "Enter Box Private Key Passphrase: " BOX_PASSPHRASE
echo ""
read -p "Enter path to Box Private Key PEM file: " BOX_PRIVATE_KEY_PATH

# Set project
PROJECT_ID="your-project-id"

echo ""
echo "📝 Creating secrets in project: $PROJECT_ID"
echo ""

# Create secrets
echo "Creating box-client-id..."
echo -n "$BOX_CLIENT_ID" | gcloud secrets create box-client-id --data-file=- --project=$PROJECT_ID

echo "Creating box-client-secret..."
echo -n "$BOX_CLIENT_SECRET" | gcloud secrets create box-client-secret --data-file=- --project=$PROJECT_ID

echo "Creating box-public-key-id..."
echo -n "$BOX_PUBLIC_KEY_ID" | gcloud secrets create box-public-key-id --data-file=- --project=$PROJECT_ID

echo "Creating box-enterprise-id..."
echo -n "$BOX_ENTERPRISE_ID" | gcloud secrets create box-enterprise-id --data-file=- --project=$PROJECT_ID

echo "Creating box-private-key-passphrase..."
echo -n "$BOX_PASSPHRASE" | gcloud secrets create box-private-key-passphrase --data-file=- --project=$PROJECT_ID

echo "Creating box-private-key..."
gcloud secrets create box-private-key --data-file="$BOX_PRIVATE_KEY_PATH" --project=$PROJECT_ID

echo ""
echo "✅ All Box JWT secrets created successfully!"
echo "🔒 Your credentials are now securely stored in Google Secret Manager"

使其可执行并运行：

chmod +x box_jwt_secrets_setup.sh
./box_jwt_secrets_setup.sh

步骤4：更新requirements.txt文件 添加Secret Manager客户端库：

google-cloud-secret-manager>=2.0.0

步骤5：更新.gitignore文件 现在你可以安全地忽略JWT配置文件了：

# Box Configuration (Sensitive)
box_jwt_config.json
*.jwt
*.pem
*.key
*.p12
*.pfx

设置环境变量

export GOOGLE_CLOUD_PROJECT="your-project-id"
export GOOGLE_CLOUD_LOCATION="us-central1"
export GOOGLE_GENAI_USE_VERTEXAI="TRUE"
export MODEL="gemini-2.5-flash"

🚀 部署

本地开发

python -m uvicorn agent_executor:app --reload

Cloud Run 部署

./deploy.sh <project-id> <service-name>

AgentSpace 注册

部署后，请在 Google Cloud Discovery Engine 中注册您的代理：

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://discoveryengine.googleapis.com/v1alpha/projects/<PROJECT_ID>/locations/global/collections/default_collection/engines/<ENGINE_ID>/assistants/default_assistant/agents" \
  -d '{
    "name": "Box_Search_Agent",
    "displayName": "Box Search Agent",
    "description": "Enterprise content discovery agent for Box",
    "a2aAgentDefinition": {
      "jsonAgentCard": "{\"provider\": {\"url\": \"<YOUR_CLOUD_RUN_URL>\"},\"name\": \"box_search_agent\",\"description\": \"A Box search assistant that helps you find content in your Box enterprise\"}"
    }
  }'

📖 使用示例

盒内容搜索

User: "Find regulatory documents"
Agent: [Searches Box and returns organized results with file counts and details]

Box AI 问答

User: "What are the key points in Capital Call Notice.pdf?"
Agent: [Uses Box AI to analyze the specific file and provide insights]

Box Hub 询问

User: "What are our company policies?"
Agent: [Automatically discovers relevant hubs and provides answers from the best knowledge base]

盒式MCP（多芯片封装）集成

User: "Search for Project Phoenix files using MCP"
Agent: [Uses Box MCP Remote Server for enhanced search with advanced filtering]

User: "Analyze this document with Box AI via MCP"
Agent: [Leverages Box AI through MCP for deeper document analysis]

User: "Extract structured data from this file via MCP"
Agent: [Uses Box MCP to convert unstructured documents into structured data]

User: "Get project status from Box Hub via MCP"
Agent: [Provides project-level insights using Box Hub analysis via MCP]

《信息自由法》（FOIA）合规处理

User: "Apply FOIA metadata to Project Phoenix folder"
Agent: [Applies FOIA retention template to all relevant files]

User: "Generate FOIA compliance report"
Agent: [Creates comprehensive audit trail and compliance documentation]

User: "Help me with FOIA workflow"
Agent: [Guides through complete FOIA request processing workflow]

资本调用通知创建

User: "Help me create capital call notices"
Agent: [Guides through complete workflow from template selection to document generation]

User: "Find templates for capital call notices"
Agent: [Discovers available templates and provides guidance]

User: "Show me sample LP data structure"
Agent: [Provides comprehensive sample data structure for capital call notices]

🔒 安全

认证方法

JWT 认证使用Box实现安全的服务器到服务器身份验证
环境变量敏感配置已安全存储
框选API权限企业访问所需的最低权限
Cloud Run 安全性无未认证访问，默认安全

Google Secret Manager的优势

使用Google Secret Manager来管理JWT凭证具有多重安全优势：

🔒 增强安全性凭证存储在Google的Secure Secret Manager中，而非本地文件
🚀 更轻松的部署在部署中无需包含敏感文件
📝 版本控制密钥可以在不更改代码的情况下进行版本管理和轮换
👥 访问控制IAM（身份和访问管理）控制谁能访问机密信息
🔄 轻松更新更新密钥而无需重新部署代码
🔍 审计日志记录追踪谁在何时访问了机密信息
🌍 多区域秘密可以在不同区域之间复制以提高可用性

最佳实践

在生产环境中使用 Google Secret Manager 进行部署
仅在开发/测试环境中保留本地JWT配置
定期轮换JWT凭据
为秘密权限使用最小特权访问原则
通过云日志监控秘密访问

🛠️ 开发

项目结构

A2A_CR_Box/
├── agent_executor.py      # Main A2A executor
├── gemini_agent.py        # Gemini agent with tools
├── box_auth.py           # Box JWT authentication
├── box_search.py         # Box content search
├── box_ai_ask.py         # Box AI file analysis
├── box_hub_ask.py        # Box Hub discovery and querying
├── box_doc_gen.py        # Box Doc Gen for capital call notices
├── box_mcp_client.py     # Box MCP Remote Server integration
├── foia_processor.py     # FOIA compliance and metadata processing
├── box_batch_summarize.py # Batch summarization tools
├── simple_summarize.py   # Simple summarization utilities
├── requirements.txt      # Python dependencies
├── deploy.sh            # Cloud Run deployment script
├── box_jwt_config.example.json # JWT configuration template
├── box_jwt_secrets_setup.sh   # Secret Manager setup script
└── README.md            # This file

添加新工具

在新的Python文件中创建你的工具函数
将其导入 gemini_agent.py
把它加到 tools 列表
更新代理指令
添加相应的技能

📝 许可证

此项目根据Box服务条款（TOS）授权。此项目按现状交付，不承诺提供维护服务。

🤝 贡献

为仓库创建分支（或：克隆仓库）
创建一个特性分支
做出你的更改
如适用，请添加测试
提交拉取请求

📞 支持

对于问题和疑问：

在Google Cloud Console中查看日志
评审框API文档
查阅Google ADK文档

🔄 版本历史

版本1.0.0首次发布，具备Box搜索和AI功能
v1.1.0增加了Box Hub询问功能
**v1.2.0（版本1.2.0）**增强企业专注度与专业沟通
**v1.3.0（中文可表述为：版本1.3.0）**添加了Box文档生成功能以集成资本调用通知
v1.4.0添加了符合《信息自由法》（FOIA）要求的元数据模板处理功能
v1.5.0增加了Box MCP远程服务器集成，以增强AI功能
**v1.6.0（版本1.6.0）**增强的工作流助手和跨平台MCP支持