agent_management/agent_templates/docs/AZURE_BLOB_AGENT_MCP_EXAMPLES.md

Azure Blob Agent MCP 请求调用示例

服务信息

• 服务名称: Azure Blob Storage AI Agent (MCP)
• 版本: 1.0.0
• 框架: Model Context Protocol (MCP)
• 默认端口: 8080

概述

MCP 版本使用 Model Context Protocol 协议实现智能文件操作，提供标准化的工具调用接口。

---

API 端点

1. 健康检查

端点: GET /health

请求示例 (curl):

curl http://localhost:8080/health

响应示例:

{
  "status": "healthy",
  "connected": true,
  "framework": "mcp",
  "user_id": "user123",
  "namespace": "ai-agents",
  "connection_info": {
    "account_kind": "StorageV2",
    "sku_name": "Standard_LRS"
  }
}

---

2. 获取 MCP 工具列表

端点: GET /mcp/tools

列出所有可用的 MCP 工具及其参数。

请求示例 (curl):

curl http://localhost:8080/mcp/tools

请求示例 (Python):

import requests

response = requests.get("http://localhost:8080/mcp/tools")
tools = response.json()
for tool in tools["tools"]:
    print(f"Tool: {tool['name']}")
    print(f"Description: {tool['description']}")
    print(f"Parameters: {tool['parameters_schema']}")

响应示例:

{
  "tools": [
    {
      "name": "list_containers",
      "description": "列出所有 Blob 容器",
      "parameters_schema": {
        "type": "object",
        "properties": {},
        "required": []
      }
    },
    {
      "name": "list_blobs",
      "description": "列出容器中的所有 Blob",
      "parameters_schema": {
        "type": "object",
        "properties": {
          "container_name": {
            "type": "string",
            "description": "容器名称"
          }
        },
        "required": ["container_name"]
      }
    },
    {
      "name": "upload_blob",
      "description": "上传文件到 Blob 容器",
      "parameters_schema": {
        "type": "object",
        "properties": {
          "container_name": {"type": "string"},
          "blob_name": {"type": "string"},
          "content": {"type": "string"}
        },
        "required": ["container_name", "blob_name", "content"]
      }
    },
    {
      "name": "download_blob",
      "description": "从 Blob 容器下载文件",
      "parameters_schema": {
        "type": "object",
        "properties": {
          "container_name": {"type": "string"},
          "blob_name": {"type": "string"}
        },
        "required": ["container_name", "blob_name"]
      }
    }
  ]
}

---

3. 调用 MCP 工具

端点: POST /mcp/tool

调用特定的 MCP 工具。

请求体:

{
  "tool_name": "list_blobs",
  "parameters": {
    "container_name": "mycontainer"
  }
}

请求示例 (curl):

curl -X POST http://localhost:8080/mcp/tool \
  -H "Content-Type: application/json" \
  -d '{
    "tool_name": "list_blobs",
    "parameters": {
      "container_name": "documents"
    }
  }'

请求示例 (Python):

import requests

# 示例 1: 列出容器
list_containers = {
    "tool_name": "list_containers",
    "parameters": {}
}
response = requests.post("http://localhost:8080/mcp/tool", json=list_containers)
print(response.json())

# 示例 2: 列出容器中的文件
list_blobs = {
    "tool_name": "list_blobs",
    "parameters": {
        "container_name": "documents"
    }
}
response = requests.post("http://localhost:8080/mcp/tool", json=list_blobs)
print(response.json())

# 示例 3: 上传文件
upload_blob = {
    "tool_name": "upload_blob",
    "parameters": {
        "container_name": "documents",
        "blob_name": "report.txt",
        "content": "This is the report content"
    }
}
response = requests.post("http://localhost:8080/mcp/tool", json=upload_blob)
print(response.json())

# 示例 4: 下载文件
download_blob = {
    "tool_name": "download_blob",
    "parameters": {
        "container_name": "documents",
        "blob_name": "report.txt"
    }
}
response = requests.post("http://localhost:8080/mcp/tool", json=download_blob)
print(response.json())

响应示例 (list_blobs):

{
  "status": "success",
  "tool_name": "list_blobs",
  "result": {
    "blobs": [
      {
        "name": "file1.txt",
        "size": 1024,
        "last_modified": "2026-01-15T10:30:00Z"
      },
      {
        "name": "file2.pdf",
        "size": 2048,
        "last_modified": "2026-01-14T15:20:00Z"
      }
    ],
    "count": 2
  }
}

---

4. MCP 查询 (自然语言)

端点: POST /mcp/query

使用自然语言查询，MCP 会自动选择合适的工具。

请求体:

{
  "query": "显示 documents 容器中的所有文件",
  "container_name": "documents",
  "context": {
    "user_id": "user123",
    "session_id": "sess-456"
  }
}

请求示例 (curl):

curl -X POST http://localhost:8080/mcp/query \
  -H "Content-Type: application/json" \
  -d '{
    "query": "列出所有容器",
    "context": {"user_id": "user123"}
  }'

请求示例 (Python):

import requests

query_data = {
    "query": "上传一个名为 test.txt 的文件到 mycontainer，内容是 Hello World",
    "context": {
        "user_id": "user123",
        "operation": "upload"
    }
}

response = requests.post(
    "http://localhost:8080/mcp/query",
    json=query_data
)
print(response.json())

响应示例:

{
  "status": "success",
  "query": "上传一个名为 test.txt 的文件到 mycontainer，内容是 Hello World",
  "answer": "成功上传文件 test.txt 到容器 mycontainer",
  "tools_used": ["upload_blob"],
  "context": {
    "container_name": "mycontainer",
    "blob_name": "test.txt",
    "size": 11
  }
}

---

完整使用流程示例

Python SDK 风格的完整示例:

import requests
import json

class AzureBlobMCPClient:
    """Azure Blob MCP Agent 客户端"""
    
    def __init__(self, base_url: str):
        self.base_url = base_url.rstrip('/')
    
    def health_check(self):
        """健康检查"""
        response = requests.get(f"{self.base_url}/health")
        return response.json()
    
    def get_tools(self):
        """获取可用工具列表"""
        response = requests.get(f"{self.base_url}/mcp/tools")
        return response.json()
    
    def call_tool(self, tool_name: str, parameters: dict):
        """调用工具"""
        data = {
            "tool_name": tool_name,
            "parameters": parameters
        }
        response = requests.post(f"{self.base_url}/mcp/tool", json=data)
        return response.json()
    
    def query(self, query: str, context: dict = None):
        """自然语言查询"""
        data = {
            "query": query,
            "context": context or {}
        }
        response = requests.post(f"{self.base_url}/mcp/query", json=data)
        return response.json()
    
    # 便捷方法
    def list_containers(self):
        """列出所有容器"""
        return self.call_tool("list_containers", {})
    
    def list_blobs(self, container_name: str):
        """列出容器中的文件"""
        return self.call_tool("list_blobs", {"container_name": container_name})
    
    def upload_blob(self, container_name: str, blob_name: str, content: str):
        """上传文件"""
        return self.call_tool("upload_blob", {
            "container_name": container_name,
            "blob_name": blob_name,
            "content": content
        })
    
    def download_blob(self, container_name: str, blob_name: str):
        """下载文件"""
        return self.call_tool("download_blob", {
            "container_name": container_name,
            "blob_name": blob_name
        })


# 使用示例
client = AzureBlobMCPClient("http://localhost:8080")

# 1. 健康检查
print("Health:", client.health_check())

# 2. 获取工具列表
print("Tools:", client.get_tools())

# 3. 列出容器
containers = client.list_containers()
print("Containers:", containers)

# 4. 列出文件
files = client.list_blobs("documents")
print("Files:", files)

# 5. 上传文件
upload_result = client.upload_blob(
    "documents",
    "report.txt",
    "This is my report content"
)
print("Upload:", upload_result)

# 6. 下载文件
download_result = client.download_blob("documents", "report.txt")
print("Download:", download_result)

# 7. 自然语言查询
query_result = client.query(
    "统计 documents 容器中有多少个文件",
    context={"user_id": "user123"}
)
print("Query:", query_result)

---

MCP 协议集成示例

与 LangChain 集成:

from langchain.tools import Tool
import requests

class MCPBlobTool:
    """MCP Blob 工具包装器"""
    
    def __init__(self, base_url: str):
        self.base_url = base_url
    
    def _call_mcp_tool(self, tool_name: str, **kwargs):
        response = requests.post(
            f"{self.base_url}/mcp/tool",
            json={"tool_name": tool_name, "parameters": kwargs}
        )
        return response.json()
    
    def list_containers(self):
        return self._call_mcp_tool("list_containers")
    
    def list_blobs(self, container_name: str):
        return self._call_mcp_tool("list_blobs", container_name=container_name)

# 创建 LangChain 工具
mcp_blob = MCPBlobTool("http://localhost:8080")

tools = [
    Tool(
        name="ListContainers",
        func=mcp_blob.list_containers,
        description="列出所有 Azure Blob 容器"
    ),
    Tool(
        name="ListBlobs",
        func=lambda x: mcp_blob.list_blobs(x),
        description="列出指定容器中的所有文件。输入: 容器名称"
    )
]

# 在 LangChain Agent 中使用
from langchain.agents import initialize_agent
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(temperature=0)
agent = initialize_agent(tools, llm, agent="zero-shot-react-description", verbose=True)

result = agent.run("列出所有容器，然后显示第一个容器中的文件")
print(result)

---

环境变量配置

# 服务配置
export SERVICE_HOST="0.0.0.0"
export SERVICE_PORT="8080"
export POD_NAME="azure-blob-agent-mcp"
export TEMPLATE_TYPE="azure_blob_agent_mcp"
export AGENT_FRAMEWORK="mcp"

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

# 工具配置 (JSON 格式)
export TOOLS_CONFIG='{
  "blob_storage": {
    "enabled": true,
    "default_container": "documents"
  }
}'

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

# 用户标识
export USER_ID="default-user"
export TENANT_ID="tenant-001"
export NAMESPACE="ai-agents"

# 启动服务
python azure_blob_agent_mcp.py

---

注意事项

1. 工具发现: 先调用 /mcp/tools 了解可用工具
2. 参数验证: 严格按照工具的 schema 传递参数
3. 错误处理: MCP 返回标准化的错误格式
4. 上下文传递: 通过 context 传递会话信息
5. 异步支持: 支持异步工具调用
6. 工具组合: 可以组合多个工具完成复杂任务