agent_management/agent_templates/MULTI_FRAMEWORK_GUIDE.md

Azure Blob Agent - 多框架支持使用指南

本文档介绍如何使用三种不同框架版本的 Azure Blob Storage AI Agent：

• LangChain 版本: 使用 LangChain + LiteLLM
• MCP 版本: 使用 Model Context Protocol
• A2A 版本: 使用 Agent-to-Agent 框架

📋 目录

1. 框架对比
2. 部署配置
3. API 使用示例
4. 创建 Agent 示例

🔍 框架对比

特性	LangChain	MCP	A2A
工具调用	LangChain Tools	MCP Protocol	A2A Messages
Agent 协作	❌	❌	✅
结构化输出	✅	✅	✅
复杂推理	✅	⚡ 轻量	⚡ 轻量
适用场景	复杂任务链	标准化工具	多Agent协作

🚀 部署配置

1. LangChain 版本

{
  "name": "my-blob-agent",
  "template_name": "azure_blob_agent",
  "owner_id": "user123",
  "namespace": "ai-agents",
  "agent_framework": "langchain",
  "environment_vars": {
    "LITELLM_API_BASE": "http://litellm-service:4000",
    "LITELLM_MODEL": "gpt-3.5-turbo",
    "LITELLM_API_KEY": "sk-xxxx",
    "AZURE_STORAGE_CONNECTION_STRING": "DefaultEndpointsProtocol=https;..."
  }
}

2. MCP 版本

{
  "name": "my-blob-agent-mcp",
  "template_name": "azure_blob_agent_mcp",
  "owner_id": "user123",
  "namespace": "ai-agents",
  "agent_framework": "mcp",
  "model_provider": "openai",
  "model_name": "gpt-4",
  "model_api_key": "sk-xxxx",
  "model_endpoint": "https://api.openai.com/v1",
  "storage_connection_string": "DefaultEndpointsProtocol=https;...",
  "tools_config": {
    "enabled_tools": ["list_containers", "list_blobs", "search_blobs"]
  }
}

3. A2A 版本

{
  "name": "my-blob-agent-a2a",
  "template_name": "azure_blob_agent_a2a",
  "owner_id": "user123",
  "namespace": "ai-agents",
  "agent_framework": "a2a",
  "model_provider": "openai",
  "model_name": "gpt-4",
  "model_api_key": "sk-xxxx",
  "storage_connection_string": "DefaultEndpointsProtocol=https;...",
  "environment_vars": {
    "AGENT_ID": "blob-agent-001",
    "AGENT_ROLE": "storage_manager",
    "AGENT_CAPABILITIES": "[\"blob_storage\", \"file_operations\"]"
  }
}

📡 API 使用示例

MCP 版本 API

1. 列出所有可用工具

curl http://<agent-url>/mcp/tools

响应：

{
  "tools": [
    {
      "name": "list_containers",
      "description": "列出 Azure Blob Storage 中的所有容器",
      "inputSchema": {
        "type": "object",
        "properties": {},
        "required": []
      }
    },
    {
      "name": "list_blobs",
      "description": "列出指定容器中的所有文件",
      "inputSchema": {
        "type": "object",
        "properties": {
          "container_name": {
            "type": "string",
            "description": "容器名称"
          }
        },
        "required": ["container_name"]
      }
    }
  ]
}

2. 调用 MCP 工具

curl -X POST http://<agent-url>/mcp/call \
  -H "Content-Type: application/json" \
  -d '{
    "tool_name": "list_containers",
    "parameters": {}
  }'

curl -X POST http://<agent-url>/mcp/call \
  -H "Content-Type: application/json" \
  -d '{
    "tool_name": "list_blobs",
    "parameters": {
      "container_name": "my-container"
    }
  }'

A2A 版本 API

1. 获取 Agent 能力

curl http://<agent-url>/a2a/capabilities

响应：

{
  "agent_id": "blob-agent-001",
  "agent_role": "storage_manager",
  "capabilities": ["blob_storage", "file_operations"],
  "supported_actions": [
    "list_containers",
    "list_blobs",
    "get_blob_info",
    "search_blobs",
    "get_stats"
  ]
}

2. 注册其他 Agent

curl -X POST http://<agent-url>/a2a/register \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "analytics-agent",
    "agent_role": "data_analyzer",
    "capabilities": ["data_analysis", "visualization"],
    "endpoint": "http://analytics-agent:8080"
  }'

3. 发送 A2A 消息

curl -X POST http://<agent-url>/a2a/message \
  -H "Content-Type: application/json" \
  -d '{
    "message_id": "msg-001",
    "from_agent": "external-agent",
    "to_agent": "blob-agent-001",
    "message_type": "request",
    "action": "list_containers",
    "parameters": {}
  }'

4. Agent 间协作

curl -X POST http://<agent-url>/a2a/collaborate \
  -H "Content-Type: application/json" \
  -d '{
    "target_agent_id": "analytics-agent",
    "action": "analyze_data",
    "parameters": {
      "data_source": "blob_storage"
    }
  }'

🛠️ 创建 Agent 示例

使用 Agent Manager API 创建

1. 创建 MCP Agent

curl -X POST http://agent-manager:8000/v2/agents/platform \
  -H "Content-Type: application/json" \
  -d '{
    "name": "blob-mcp-001",
    "template_name": "azure_blob_agent_mcp",
    "owner_id": "user123",
    "namespace": "ai-agents",
    "agent_framework": "mcp",
    "model_provider": "openai",
    "model_name": "gpt-4",
    "model_api_key": "sk-xxxx",
    "storage_connection_string": "DefaultEndpointsProtocol=https;AccountName=myaccount;AccountKey=xxx;EndpointSuffix=core.windows.net",
    "tools_config": {
      "max_iterations": 5,
      "timeout": 30
    }
  }'

2. 创建 A2A Agent

curl -X POST http://agent-manager:8000/v2/agents/platform \
  -H "Content-Type: application/json" \
  -d '{
    "name": "blob-a2a-001",
    "template_name": "azure_blob_agent_a2a",
    "owner_id": "user123",
    "namespace": "ai-agents",
    "agent_framework": "a2a",
    "model_provider": "azure-openai",
    "model_name": "gpt-4",
    "model_endpoint": "https://myopenai.openai.azure.com",
    "model_api_key": "xxxx",
    "storage_connection_string": "DefaultEndpointsProtocol=https;...",
    "query_params": {
      "agent_id": "blob-a2a-001",
      "agent_role": "storage_manager",
      "agent_capabilities": ["blob_storage", "file_operations"]
    }
  }'

🔧 参数说明

通用参数（所有框架）

参数	类型	必需	说明
name	string	✅	Agent 名称（唯一）
template_name	string	✅	模板名称
owner_id	string	✅	所有者ID
namespace	string	❌	K8s 命名空间，默认 ai-agents
agent_framework	string	❌	框架类型: langchain, mcp, a2a
storage_connection_string	string	❌	Azure Storage 连接字符串
storage_account_name	string	❌	存储账户名称

模型配置参数（MCP/A2A）

参数	类型	必需	说明
model_provider	string	✅	模型提供商: openai, azure-openai
model_name	string	✅	模型名称: gpt-4, gpt-3.5-turbo
model_api_key	string	✅	模型 API 密钥
model_endpoint	string	❌	模型 API 端点

工具配置参数（MCP/A2A）

参数	类型	必需	说明
tools_config	object	❌	工具配置 JSON
tool_endpoint	string	❌	外部工具端点
tool_api_key	string	❌	工具 API 密钥

资源配置参数

参数	类型	必需	说明
cpu_request	string	❌	CPU 请求，如 100m
cpu_limit	string	❌	CPU 限制，如 500m
memory_request	string	❌	内存请求，如 128Mi
memory_limit	string	❌	内存限制，如 512Mi

🎯 使用场景

LangChain 版本适用于：

• 需要复杂推理链的任务
• 多步骤文件处理流程
• 集成现有 LangChain 生态系统

MCP 版本适用于：

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

A2A 版本适用于：

• 多 Agent 协作场景
• 分布式任务处理
• Agent 间通信需求

📝 数据库迁移

如果从旧版本升级，需要运行数据库迁移：

-- 添加新字段到 templates 表
ALTER TABLE templates ADD COLUMN agent_framework VARCHAR(50) DEFAULT 'langchain';
ALTER TABLE templates ADD COLUMN tools_config JSON;
ALTER TABLE templates ADD COLUMN default_model_provider VARCHAR(100);
ALTER TABLE templates ADD COLUMN default_model_name VARCHAR(200);

-- 添加新字段到 agents 表
ALTER TABLE agents ADD COLUMN agent_framework VARCHAR(50) DEFAULT 'langchain';
ALTER TABLE agents ADD COLUMN tools_config JSON;
ALTER TABLE agents ADD COLUMN tool_endpoint VARCHAR(500);
ALTER TABLE agents ADD COLUMN tool_api_key VARCHAR(500);
ALTER TABLE agents ADD COLUMN model_provider VARCHAR(100);
ALTER TABLE agents ADD COLUMN model_name VARCHAR(200);
ALTER TABLE agents ADD COLUMN model_endpoint VARCHAR(500);
ALTER TABLE agents ADD COLUMN model_api_key VARCHAR(500);
ALTER TABLE agents ADD COLUMN storage_connection_string VARCHAR(1000);
ALTER TABLE agents ADD COLUMN storage_account_name VARCHAR(200);

🐛 故障排查

问题: MCP 工具调用失败

解决方案:

1. 检查工具名称是否正确
2. 验证参数格式
3. 查看日志: kubectl logs <pod-name> -n ai-agents

问题: A2A Agent 无法注册

解决方案:

1. 确认目标 Agent 可访问
2. 检查网络策略
3. 验证 endpoint URL 格式

📚 更多资源

• LangChain 文档
• MCP 协议规范
• Agent Manager API 文档