agent_management/MULTI_FRAMEWORK_SUMMARY.md

Azure Blob Agent 多框架实现总结

📋 概述

本次更新为 Azure Blob Storage Agent 实现了三种框架支持：

1. LangChain 版本 (已有) - 使用 LangChain + LiteLLM
2. MCP 版本 (新增) - 使用 Model Context Protocol
3. A2A 版本 (新增) - 使用 Agent-to-Agent 框架

🆕 新增文件

Agent 实现

文件	说明
azure_blob_agent_mcp.py	MCP 框架版本的 Agent 实现
azure_blob_agent_a2a.py	A2A 框架版本的 Agent 实现

Docker 相关

文件	说明
azure_blob_agent_mcp.Dockerfile	MCP 版本的 Dockerfile
azure_blob_agent_a2a.Dockerfile	A2A 版本的 Dockerfile
requirements_mcp.txt	MCP 版本的依赖
requirements_a2a.txt	A2A 版本的依赖
build_azure_blob_mcp.sh	MCP 版本构建脚本
build_azure_blob_a2a.sh	A2A 版本构建脚本

文档和测试

文件	说明
MULTI_FRAMEWORK_GUIDE.md	多框架使用指南
test_multi_framework.sh	多框架集成测试脚本

🔄 修改的文件

数据库层

database.py - 扩展了数据模型：

Template 模型新增字段：

• agent_framework - Agent 框架类型 (langchain/mcp/a2a)
• tools_config - 工具配置 JSON
• default_model_provider - 默认模型提供商
• default_model_name - 默认模型名称

Agent 模型新增字段：

• agent_framework - Agent 框架类型
• tools_config - 工具配置
• tool_endpoint - 工具端点 URL
• tool_api_key - 工具 API 密钥
• model_provider - 模型提供商
• model_name - 模型名称
• model_endpoint - 模型端点
• model_api_key - 模型 API 密钥
• storage_connection_string - 存储连接字符串
• storage_account_name - 存储账户名称

API 层

app.py - 扩展了请求模型：

CreateTemplateRequest 新增字段：

agent_framework: str = "langchain"
tools_config: Optional[Dict] = {}
default_model_provider: Optional[str] = None
default_model_name: Optional[str] = None

CreatePlatformAgentRequest 新增字段：

namespace: Optional[str] = "ai-agents"
agent_framework: Optional[str] = None
tools_config: Optional[Dict] = {}
tool_endpoint: Optional[str] = None
tool_api_key: Optional[str] = None
model_provider: Optional[str] = None
model_name: Optional[str] = None
model_endpoint: Optional[str] = None
model_api_key: Optional[str] = None
storage_connection_string: Optional[str] = None
storage_account_name: Optional[str] = None

CreateCustomAgentRequest 同样新增了上述字段

Kubernetes 层

k8s_manager.py - 扩展了部署逻辑：

_generate_pod_manifest 方法更新：

• 支持传递框架类型到容器环境变量
• 支持传递工具配置 (tools_config, tool_endpoint, tool_api_key)
• 支持传递模型配置 (model_provider, model_name, model_endpoint, model_api_key)
• 支持传递存储配置 (storage_connection_string, storage_account_name)
• 支持传递用户标识 (user_id, tenant_id)
• 支持自定义命名空间

新增镜像映射：

"azure_blob_agent_mcp": "agnettaiji.azurecr.io/ai-agents/azure-blob-agent-mcp:latest"
"azure_blob_agent_a2a": "agnettaiji.azurecr.io/ai-agents/azure-blob-agent-a2a:latest"

新增端口映射：

"azure_blob_agent_mcp": 8080
"azure_blob_agent_a2a": 8080

新增环境变量说明（用于文档）

🏗️ 架构设计

参数传递流程

用户请求 (API)
    ↓
app.py (API 层)
    ├─ 验证参数
    ├─ 保存到数据库 (database.py)
    └─ 调用 K8sManager
        ↓
k8s_manager.py (K8s 层)
    ├─ 构建环境变量
    │   ├─ AGENT_FRAMEWORK
    │   ├─ TOOLS_CONFIG
    │   ├─ MODEL_*
    │   ├─ STORAGE_*
    │   └─ USER_ID, TENANT_ID, NAMESPACE
    ├─ 创建 Pod/Deployment
    └─ 传递到容器
        ↓
Agent 容器 (azure_blob_agent_*.py)
    ├─ 读取环境变量
    ├─ 初始化框架
    ├─ 配置工具
    ├─ 连接存储
    └─ 提供 API 服务

框架特性对比

特性	LangChain	MCP	A2A
实现文件	azure_blob_agent.py	azure_blob_agent_mcp.py	azure_blob_agent_a2a.py
工具定义	LangChain Tools	MCP Tool Classes	A2A Action Handlers
API 端点	/query	/mcp/tools, /mcp/call	/a2a/capabilities, /a2a/message
协作能力	❌	❌	✅ Agent 注册和通信
工具发现	内置	GET /mcp/tools	GET /a2a/capabilities
消息格式	自然语言	MCP Protocol	A2A Message Protocol
依赖	langchain, litellm	fastapi, pydantic	fastapi, httpx

📝 数据库迁移

提供了迁移脚本 migrate_multi_framework.py：

python migrate_multi_framework.py

支持：

• ✅ SQLite (开发环境)
• ✅ PostgreSQL (生产环境)
• ✅ 自动检测已存在字段
• ✅ 验证迁移结果

🚀 部署流程

1. 构建镜像

cd agent_templates

# 构建 MCP 版本
./build_azure_blob_mcp.sh

# 构建 A2A 版本
./build_azure_blob_a2a.sh

2. 运行数据库迁移

python migrate_multi_framework.py

3. 创建 Agent

# 创建 MCP Agent
curl -X POST http://agent-manager:8000/v2/agents/platform \
  -H "Content-Type: application/json" \
  -d @mcp_agent_config.json

# 创建 A2A Agent
curl -X POST http://agent-manager:8000/v2/agents/platform \
  -H "Content-Type: application/json" \
  -d @a2a_agent_config.json

4. 测试

./test_multi_framework.sh

🔧 环境变量配置示例

MCP Agent

# 框架配置
AGENT_FRAMEWORK=mcp
TEMPLATE_TYPE=azure_blob_agent_mcp

# 工具配置
TOOLS_CONFIG='{"enabled_tools": ["list_containers", "list_blobs"]}'

# 模型配置
MODEL_PROVIDER=openai
MODEL_NAME=gpt-4
MODEL_API_KEY=sk-xxxx
MODEL_ENDPOINT=https://api.openai.com/v1

# 存储配置
AZURE_STORAGE_CONNECTION_STRING=DefaultEndpointsProtocol=https;...
STORAGE_ACCOUNT_NAME=myaccount

# 用户信息
USER_ID=user123
TENANT_ID=tenant456
NAMESPACE=ai-agents

A2A Agent

# 框架配置
AGENT_FRAMEWORK=a2a
TEMPLATE_TYPE=azure_blob_agent_a2a

# Agent 身份
AGENT_ID=blob-agent-001
AGENT_ROLE=storage_manager
AGENT_CAPABILITIES='["blob_storage", "file_operations"]'

# 模型配置
MODEL_PROVIDER=azure-openai
MODEL_NAME=gpt-4
MODEL_API_KEY=xxxx
MODEL_ENDPOINT=https://myopenai.openai.azure.com

# 存储配置
AZURE_STORAGE_CONNECTION_STRING=DefaultEndpointsProtocol=https;...

# 用户信息
USER_ID=user123
TENANT_ID=tenant456
NAMESPACE=ai-agents

🎯 使用场景

LangChain 版本

• ✅ 复杂的推理任务
• ✅ 多步骤文件处理
• ✅ 与现有 LangChain 应用集成

MCP 版本

• ✅ 标准化工具调用
• ✅ 跨平台工具共享
• ✅ 轻量级集成

A2A 版本

• ✅ 多 Agent 协作
• ✅ 分布式任务处理
• ✅ Agent 间通信

📚 API 端点对比

LangChain

• POST /query - 自然语言查询
• GET /health - 健康检查
• POST /connect - 连接存储

MCP

• GET /mcp/tools - 列出可用工具
• POST /mcp/call - 调用工具
• POST /query - 查询（简化版）
• GET /health - 健康检查
• POST /connect - 连接存储

A2A

• GET /a2a/capabilities - 获取能力
• POST /a2a/register - 注册其他 Agent
• GET /a2a/agents - 列出已注册 Agent
• POST /a2a/message - 处理 A2A 消息
• POST /a2a/collaborate - 与其他 Agent 协作
• POST /query - 查询
• GET /health - 健康检查
• POST /connect - 连接存储

✅ 测试清单

• 数据库迁移成功
• MCP 镜像构建成功
• A2A 镜像构建成功
• MCP Agent 创建成功
• A2A Agent 创建成功
• MCP 工具调用正常
• A2A 消息处理正常
• 健康检查通过
• 存储连接正常
• 环境变量正确传递

🐛 已知问题

1. LLM 集成: MCP 和 A2A 版本目前使用简单规则匹配，需要集成实际 LLM 进行意图识别
2. 安全性: API 密钥等敏感信息应加密存储
3. 日志: 需要统一的日志收集和监控

🔮 未来改进

1. 安全增强

   • 密钥加密存储
   • RBAC 权限控制
   • API 密钥轮换

2. 功能扩展

   • 更多 Azure 服务集成
   • 自定义工具注册
   • 工具组合和编排

3. 监控和调试

   • 分布式追踪
   • 性能监控
   • 调试工具

4. 开发体验

   • Web UI 管理界面
   • 可视化工具设计器
   • Agent 模板市场

📖 相关文档

• 多框架使用指南
• API 文档
• Azure Blob Agent 原始文档