Aca Python Agent Workbench MCP

带有Azure存储的Python Aspire代理工作台

一个用以下代码构建的现代Python代理工作台 Aspire 13 用于Azure容器应用程序部署，具有Azure存储集成（块、队列、表）和MCP（模型上下文协议）支持。

🤖 GitHub复制品就绪：此存储库包括全面的 帮助您充分利用人工智能辅助开发。看 贡献.md 关于贡献指南。

概述

该项目演示了一个尖端的云原生Python应用程序，使用：

• Aspire 13 （最新）用于编排和云部署
• .NET 10 SDK 用于Aspire工具
• Azure容器应用 用于无服务器托管
• Azure存储 （块、队列、表）用于数据持久化
• 快速API 用于高性能REST API
• React+Vite 使用TypeScript的前端
• 开放遥测 可观察性
• 主控程序 用于代理通信

📚 架构文档：参见 存储_建筑.md 有关基础存储架构的详细信息，包括多租户数据模型、分区策略和查询模式。

项目结构

.
├── PythonAspireSample/
│   ├── apphost.cs                      # Aspire 13 single-file AppHost
│   ├── apphost.run.json                # Run configuration
│   ├── app/                            # Python FastAPI application
│   │   ├── main.py                     # Main API with Azure Storage endpoints
│   │   ├── telemetry.py                # OpenTelemetry configuration
│   │   ├── pyproject.toml              # Python dependencies
│   │   ├── .python-version             # Python version (3.13)
│   │   └── .dockerignore               # Docker ignore patterns
│   └── frontend/                       # React + Vite frontend
│       ├── src/                        # TypeScript source files
│       ├── public/                     # Static assets
│       ├── vite.config.ts              # Vite configuration
│       └── package.json                # Node dependencies
├── azure.yaml                          # Azure Developer CLI config
└── README.md                           # This file

先决条件

必需

• .NET SDK 10.0.100或更高版本 （Aspire 13需要）
• Python 3.13 或以后
• Node.js 18+ （前端）
• Docker 桌面版 或波德曼（用于当地发展）

用于Azure部署

• Azure开发者命令行界面（azd） - 安装azd
• Azure订阅

入门指南

1.安装。净10 SDK

Linux/macOS：

curl -sSL https://dot.net/v1/dotnet-install.sh | bash /dev/stdin --channel 10.0
export PATH="$HOME/.dotnet:$PATH"
export DOTNET_ROOT="$HOME/.dotnet"

Windows（PowerShell）：

Invoke-WebRequest -Uri https://dot.net/v1/dotnet-install.ps1 -OutFile dotnet-install.ps1
./dotnet-install.ps1 -Channel 10.0

验证安装：

dotnet --version  # Should show 10.0.100 or later

2.安装Aspire CLI 13

将Aspire CLI安装为。NET全局工具：

dotnet tool install -g Aspire.Cli --prerelease

验证安装：

aspire --version  # Should show 13.0.0

3.在本地运行应用程序

导航到项目目录并运行：

cd PythonAspireSample
aspire run

这将：

• 启动Aspire仪表板（通常在https://localhost:19888)
• 启动Python FastAPI应用程序
• 启动React前端
• 为本地开发设置Azure存储模拟（Azurite）
• 自动配置所有服务连接
• 启用OpenTetry跟踪和指标

4.访问应用程序

运行后，访问：

• Aspire仪表板: https://localhost:19888
• Python API: http://localhost:PORT（检查仪表板上的实际端口）
• 前端: http://localhost:PORT（检查仪表板上的实际端口）

仪表板提供：

• 实时服务健康监测
• 分布式跟踪可视化
• 日志聚合
• 指标和绩效数据
• 资源拓扑

API终点

Python FastAPI应用程序提供以下端点：

核心终点

• GET / -服务信息和可用端点
• GET /health -健康检查端点
• GET /api/weatherforecast -天气预报数据示例

Azure存储集成端点

• GET /api/storage/test -测试所有Azure存储连接
• GET /api/blob/upload -将测试blob上载到Azure blob存储
• GET /api/queue/send -向Azure队列存储发送测试消息
• GET /api/table/insert -将测试实体插入Azure表存储

Azure存储集成

该应用程序演示了与三个Azure存储服务的集成：

Blob存储

• 上传和下载文件
• 集装箱管理
• 通过集成 azure-storage-blob Python 软件开发工具包
• 连接字符串： ConnectionStrings__blobs （由Aspire设定）

队列存储

• 发送和接收消息
• 队列管理
• 通过集成 azure-storage-queue Python 软件开发工具包
• 连接字符串： ConnectionStrings__queues （由Aspire设定）

表存储

• NoSQL实体存储
• CRUD操作
• 通过集成 azure-data-tables Python 软件开发工具包
• 连接字符串： ConnectionStrings__tables （由Aspire设定）

Aspire CLI命令

创建新项目

# Create a new Python Aspire project
aspire new aspire-py-starter --name MyProject --output ./MyProject

# Create just an AppHost
aspire new aspire-apphost-singlefile --name MyAppHost --output ./apphost

添加集成

# Add PostgreSQL
aspire add postgresql

# Add Redis
aspire add redis

# Add Azure Service Bus
aspire add azure-servicebus

运行和管理

# Run in development mode
aspire run

# Run with debug output
aspire run --debug

# Initialize Aspire in existing solution
aspire init

发布（预览）

# Generate deployment artifacts
aspire publish

# Deploy to Azure Container Apps (Preview)
aspire deploy

Azure容器应用部署

使用Aspire CLI（推荐）

1. 使用Aspire CLI进行部署 （如果可用）：

   cd PythonAspireSample
   aspire deploy

使用Azure开发者命令行界面（azd）

1. 初始化项目：

   azd init

1. 配置Azure资源：

   azd provision

这将创建：

- Azure容器应用程序环境 - Azure容器注册表 - Azure存储帐户（带块、队列、表） - 应用洞察 - 日志分析工作区

1. 部署应用程序：

   azd deploy

1. 查看部署：

   azd show

1. 监控日志：

   azd monitor --logs

配置

环境变量

Python应用程序从Aspire自动配置的环境变量中读取Azure存储连接字符串：

• ConnectionStrings__blobs -Blob存储连接
• ConnectionStrings__queues -队列存储连接
• ConnectionStrings__tables -表存储连接

Azurite的地方发展

对于没有Aspire的本地测试，您可以使用Azurite（Azure存储模拟器）：

# Install Azurite
npm install -g azurite

# Start Azurite
azurite --silent --location /tmp/azurite

# Connection strings for local emulator
export ConnectionStrings__blobs="UseDevelopmentStorage=true"
export ConnectionStrings__queues="UseDevelopmentStorage=true"
export ConnectionStrings__tables="UseDevelopmentStorage=true"

发展

安装Python依赖项

cd PythonAspireSample/app

# Using uv (recommended by Aspire)
uv pip install -e .

# Or using pip
pip install -e .

安装前端依赖项

cd PythonAspireSample/frontend
npm install

生产大楼

# Frontend
cd PythonAspireSample/frontend
npm run build

# The build output will be served by the Python app in production

Docker构建

手动构建容器：

# Python app
cd PythonAspireSample/app
docker build -t python-aspire-app .

# Frontend (if needed separately)
cd PythonAspireSample/frontend
docker build -t python-aspire-frontend .

监测和可观察性

该项目包括综合可观测性：

• 开放遥测 分布式跟踪集成
• 结构化日志记录 转到Aspire仪表板
• 健康检查 用于服务监控
• 指标收集 用于性能分析
• Aspire仪表板 获取当地发展见解
• Azure应用洞察 （部署到Azure时）
• Azure监视器 整合

查看遥测数据

在Aspire仪表板中，您可以：

• 查看跨服务的请求跟踪
• 监控服务依赖关系
• 分析性能瓶颈
• 跟踪错误和异常
• 实时查看日志

故障排除

常见问题

1. Aspire CLI需要。净值10：确保你有。NET SDK 10.0.100或更高版本已安装

   dotnet --version

1. 端口冲突：Aspire动态分配端口。检查仪表板上的实际端口。

1. 存储连接错误:

- 对于本地开发人员，确保Azurite正在运行 - 对于Azure，验证存储帐户连接字符串

1. Python版本：确保安装了Python 3.13+

   python --version

1. Node.js版本：确保前端安装了Node 18+

   node --version

查看日志

地方发展：

• 使用Aspire仪表板在一个地方查看所有服务日志
• 访问地址：https://localhost:19888

Azure部署：

• Azure门户>容器应用>日志流
• azd monitor --logs
• 应用洞察>交易搜索

调试模式

使用调试输出运行：

aspire run --debug

高级功能

单文件AppHost

此项目使用Aspire 13的新单文件AppHost格式(apphost.cs)，它提供：

• 简化项目结构
• 不需要单独的.csproj文件
• 使用内联包引用 #:package 指令
• 更易于理解和维护

UV包装管理器

Python应用程序使用 uv 为了实现快速的包管理：

• 明显快于pip
• 更好的依赖关系解决方案
• 与Aspire集成

容器文件发布

前端通过以下方式发布到Python应用程序的静态目录中：

app.PublishWithContainerFiles(frontend, "./static");

这将创建一个包含前端和后端的单一容器。

贡献

欢迎投稿！此存储库是 GitHub复制品就绪 提供全面的指导，帮助您有效地做出贡献。

GitHub Copilot入门

此存储库包括：

• **** -项目特定副驾驶说明
• 贡献.md -详细的捐款指南
• .vcode/settings.json -针对Copilot优化的VS代码配置
• .编辑权 -跨编辑器的一致代码风格

GitHub Copilot将自动使用这些说明，根据此项目的模式和惯例提供更好的建议。

贡献步骤

1. 分叉存储库
2. 创建要素分支
3. 进行更改（Copilot将帮助您提供上下文感知建议）
4. 提交拉取请求

看 贡献.md 详细指南。

资源

文档

• 存储体系结构 -使用Azure存储服务的多租户存储设计
• 部署指导 -Azure容器应用部署
• 快速开始 -5分钟设置指南
• 贡献 -贡献指南

外部资源

• Aspire 13文档
• Aspire CLI概述
• Azure容器应用
• Azure存储Python SDK
• FastAPI文档
• Azure开发者命令行界面

许可证

这个项目是开源的，可以在MIT许可证下使用。