microsoft-foundry

Tổng quan

microsoft-foundry là kỹ năng gì?

Kỹ năng microsoft-foundry là một bộ workflow và tài liệu tham chiếu được biên soạn kỹ, giúp bạn đi qua toàn bộ vòng đời của Azure AI Foundry agents. Trọng tâm là triển khai và vận hành thực tế:

• Tạo prompt agents và hosted agents
• Build Docker image và push lên Azure Container Registry (ACR)
• Triển khai agents lên Azure AI Foundry
• Thiết lập projects, RBAC, quota và connections
• Chạy evaluation datasets và quản lý agent-metadata.yaml
• Cấu hình agent theo mô hình standard và private-network
• Bật observability, tracing và troubleshooting

Toàn bộ nội dung được lấy từ repository microsoft/azure-skills và được cấu trúc sẵn để bạn có thể vận hành agents trên Azure AI Foundry mà không cần tự suy luận lại cấu trúc repo.

Kỹ năng này phù hợp với ai?

Hãy dùng microsoft-foundry nếu bạn là:

• Backend engineer hoặc platform engineer chịu trách nhiệm triển khai và vận hành Azure AI Foundry agents
• AI/ML engineer đang chuyển prototype sang một Foundry project chạy production
• Developer tích hợp Foundry agents với các dịch vụ, SDK hoặc công cụ MCP hiện có
• Người phụ trách kỹ thuật cần nắm RBAC, quota, private networking và thiết lập môi trường

Nếu bạn chỉ cần triển khai hạ tầng Azure cơ bản (App Service, Functions, web app tổng quát), thì kỹ năng này không phù hợp—hãy sử dụng một kỹ năng triển khai Azure tổng quát hơn.

microsoft-foundry giải quyết những vấn đề gì?

Kỹ năng này được thiết kế để xử lý các bài toán lặp lại sau:

• "Tôi nên cấu trúc agent repo như thế nào cho Foundry?"
  Hãy dùng hướng dẫn references/agent-metadata-contract.md cho bố cục .foundry/ và các trường trong agent-metadata.yaml.

• "Làm sao tạo và triển khai agents một cách nhất quán?"
  Sử dụng các workflow foundry-agent/create và foundry-agent/deploy để tạo prompt/hosted agents, build container, push lên ACR và khởi chạy agent containers.

• "Cấu hình projects, connections, RBAC và quota như thế nào?"
  Làm theo project/create, rbac/rbac.md và quota/quota.md để tạo project, gán vai trò và lập kế hoạch capacity.

• "Làm sao đánh giá và quan sát agents của tôi?"
  Dùng foundry-agent/eval-datasets, foundry-agent/observe và foundry-agent/trace để chạy batch eval, quản lý datasets và evaluators, và kết nối tới các tài nguyên observability.

• "Xử lý cấu hình standard so với private-network ra sao?"
  Dùng references/standard-agent-setup.md và references/private-network-standard-agent-setup.md để chọn và cấu hình mô hình mạng phù hợp.

Khi nào microsoft-foundry là lựa chọn phù hợp?

Hãy dùng kỹ năng này khi bạn cần:

• Triển khai prompt hoặc hosted agents lên Azure AI Foundry
• Chuẩn hóa cấu trúc project của agent với .foundry/agent-metadata.yaml
• Tích hợp MCP tools và Azure SDKs vào một workflow có thể lặp lại
• Quản lý RBAC, quota và capacity planning cho workload của agent
• Chạy evaluation datasets và theo dõi kết quả trên nhiều môi trường
• Thiết lập observability với Application Insights và traces
• Triển khai trong cấu hình standard hoặc private-network (VNet)

Không nên dùng kỹ năng này nếu bạn chỉ cần:

• Triển khai ứng dụng Azure nói chung (web app, Functions, App Service)
• Chuẩn bị tài khoản hoặc subscription Azure ở mức khái quát

Trong các trường hợp đó, hãy kết hợp kỹ năng này với các kỹ năng triển khai/chuẩn bị Azure tổng quát, hoặc dùng một kỹ năng chuyên dụng như azure-deploy / azure-prepare.

Cách sử dụng

Cài đặt

Để thêm microsoft-foundry từ repository microsoft/azure-skills, hãy cài bằng lệnh:

npx skills add https://github.com/microsoft/azure-skills --skill microsoft-foundry

Lệnh này sẽ giúp các workflow và nội dung tham chiếu của microsoft-foundry sẵn sàng cho agent hoặc môi trường công cụ của bạn. Sau khi cài đặt, điểm vào chính là file SKILL.md trong thư mục skills/microsoft-foundry.

Cấu trúc repository và các thư mục chính

Sau khi cài kỹ năng hoặc mở trực tiếp trong repository, bạn sẽ thấy cấu trúc sau:

• SKILL.md – trang index cấp cao và danh sách sub-skill
• foundry-agent/ – các workflow end-to-end cho từng agent
  • create/ – tạo prompt agents hoặc hosted agents
  • deploy/ – build và triển khai agents, bao gồm container và ACR
  • eval-datasets/ – quản lý eval datasets và các lần chạy đánh giá
  • invoke/ – gọi các agents hiện có
  • observe/ – thiết lập observability và các workflow giám sát
  • trace/ – thu thập trace và tạo dataset từ trace
  • troubleshoot/ – hướng dẫn xử lý sự cố cho các lần chạy lỗi
• project/
  • create/ – tạo và cấu hình Azure AI Foundry projects
  • connections.md – hướng dẫn về connections ở cấp độ project
• rbac/
  • rbac.md – vai trò RBAC, quyền hạn và các pattern phổ biến
• quota/
  • quota.md – hướng dẫn về quota và lập kế hoạch capacity
  • references/ – lập kế hoạch capacity, xử lý lỗi, tối ưu hóa
• references/
  • agent-metadata-contract.md – bố cục .foundry/ và agent-metadata.yaml
  • auth-best-practices.md – các mẫu xác thực Azure và RBAC
  • standard-agent-setup.md – cấu hình agent standard (không cô lập mạng)
  • private-network-standard-agent-setup.md – cấu hình VNet/private-link
  • sdk/ – tài liệu tham chiếu thao tác bằng SDK khi không có MCP tools

Hãy bắt đầu với SKILL.md để hiểu các sub-skill, sau đó đi sâu vào thư mục kịch bản phù hợp.

Quy trình khởi động nhanh: từ project đến agent đã triển khai

Phần này phác thảo lộ trình thực tế sử dụng nội dung trong kỹ năng microsoft-foundry.

1. Tạo hoặc chuẩn bị Foundry project

1. Mở project/create/create-foundry-project.md.
2. Làm theo các bước để:
   • Tạo Azure AI Foundry project
   • Xác nhận project endpoint (ví dụ: https://<resource>.services.ai.azure.com/api/projects/<project>)
   • Liên kết các connections cần thiết (Cosmos DB, Storage, Azure AI Search, v.v.) cho cấu hình standard
3. Xem project/connections.md để đảm bảo thread storage, file storage và vector store connections của bạn được cấu hình đúng, đặc biệt nếu bạn dự định dùng standard agent setup.

2. Cấu hình RBAC và xác thực

1. Đọc rbac/rbac.md để kiểm tra:
   • Cần những vai trò nào (Owner, Contributor, User Access Administrator, v.v.) trên resource group và các tài nguyên Foundry
   • Cách gán vai trò theo best practice RBAC của Azure
2. Mở references/auth-best-practices.md và áp dụng các khuyến nghị:
   • Dùng managed identities và Azure RBAC trong môi trường production
   • Giới hạn DefaultAzureCredential cho môi trường phát triển cục bộ
   • Chọn loại credential phù hợp cho production, CI/CD và môi trường dev

Cách này giúp các lần triển khai và hoạt động của agent xác thực ổn định mà không cần hard-code secrets.

3. Quyết định dùng basic, standard hay private-network setup

1. Mở references/standard-agent-setup.md để nắm rõ:
   • Khác biệt giữa cấu hình Basic và Standard
   • Các connections bắt buộc cho cấu hình standard: Cosmos DB, Azure Storage, Azure AI Search và tùy chọn Azure AI Services
   • Các điều kiện tiên quyết như vai trò RBAC trên resource group
2. Nếu bạn cần cô lập mạng hoàn toàn, hãy đọc references/private-network-standard-agent-setup.md:
   • Yêu cầu về VNet và subnet (agent subnet và private endpoint subnet)
   • Yêu cầu đồng bộ vùng (region) giữa tài nguyên Foundry và VNet
   • Cách dùng Bicep template chính thức cho private-network standard agent setup

Hãy chọn cấu hình phù hợp với yêu cầu tuân thủ và mạng của bạn trước khi chuyển sang bước tạo agent.

4. Chuẩn hóa bố cục project của agent

1. Mở references/agent-metadata-contract.md và căn chỉnh project theo bố cục được mô tả:

   <agent-root>/
     .foundry/
       agent-metadata.yaml
       datasets/
       evaluators/
       results/
   

2. Đảm bảo agent-metadata.yaml chứa định nghĩa môi trường với các trường như:

   • defaultEnvironment
   • environments.<name>.projectEndpoint
   • environments.<name>.agentName
   • environments.<name>.azureContainerRegistry (cho hosted agents)
   • environments.<name>.observability.* (cho Application Insights)
   • environments.<name>.testCases[] cho các evaluation bundle

File này sẽ trở thành nguồn chân lý cho cấu hình theo từng môi trường, và toàn bộ workflow của microsoft-foundry giả định file này tồn tại và chính xác.

5. Tạo prompt agent hoặc hosted agent

1. Với prompt agents, mở foundry-agent/create/create-prompt.md:

   • Hiểu sự khác nhau giữa prompt agents và workflows
   • Làm theo các bước để xác định ngữ cảnh project (endpoint, credentials)
   • Dùng MCP tools nếu có, và fallback sang azure-ai-projects SDK như tài liệu mô tả
   • Cung cấp tên agent, model deployment, phần instructions và các tools tùy chọn (file search, code interpreter, v.v.)

2. Với hosted agents, mở foundry-agent/create/create.md:

   • Chọn xem bạn đang tạo agent mới hoàn toàn (greenfield) hay chuyển đổi từ project hiện có (brownfield)
   • Chọn framework và ngôn ngữ dựa trên các đường dẫn mẫu (Python hoặc C#, như Microsoft Agent Framework hoặc LangGraph)
   • Dùng hướng dẫn để tích hợp với repository foundry-samples khi cần

Kết thúc bước này, bạn sẽ có một agent project tương thích Foundry, sẵn sàng để triển khai.

6. Build và triển khai agent

1. Mở foundry-agent/deploy/deploy.md.
2. Làm theo workflow bao gồm:
   • Quét project và thu thập environment variables
   • Sinh Dockerfile và sử dụng docker / az acr cho hosted agents
   • Dùng MCP tools như agent_update, agent_container_control và agent_container_status_get
   • Tạo hoặc cập nhật deployment và start/stop agent containers
3. Không nên chạy azd up, azd deploy, az acr build hoặc docker build một cách riêng lẻ mà không xem qua hướng dẫn này—kỹ năng điều phối các lệnh đó như một pipeline triển khai hoàn chỉnh.

Khi hoàn thành bước này, agent của bạn sẽ được triển khai và có thể truy cập qua Azure AI Foundry.

7. Gọi và kiểm thử agent

1. Mở foundry-agent/invoke/invoke.md.
2. Dùng các mẫu đã được tài liệu hóa để:
   • Xác định đúng môi trường và endpoint từ agent-metadata.yaml
   • Gọi agent với payload mẫu hoặc tuỳ chỉnh
   • Xác minh phản hồi, tools và state hoạt động như kỳ vọng

Đây là giai đoạn tốt để smoke test trước khi chạy các bộ đánh giá đầy đủ.

8. Đánh giá và cải tiến

1. Mở foundry-agent/eval-datasets/eval-datasets.md.
2. Dùng hướng dẫn để:
   • Quản lý datasets và evaluators trong .foundry/datasets và .foundry/evaluators
   • Chạy các workflow đánh giá dựa trên định nghĩa testCases trong agent-metadata.yaml
   • Lưu kết quả dưới .foundry/results và so sánh theo môi trường hoặc phiên bản agent
3. Lặp lại việc tinh chỉnh prompts hoặc instructions và chạy lại đánh giá để theo dõi cải thiện theo thời gian.

Observability, tracing và troubleshooting

Observability và giám sát

1. Mở foundry-agent/observe/observe.md.
2. Cấu hình observability theo hướng dẫn:
   • Gắn Application Insights bằng resource ID và connection string được mô tả trong agent-metadata-contract.md
   • Dùng các dashboard hoặc truy vấn được khuyến nghị để giám sát độ trễ, lỗi và throughput

Điều này giúp bạn theo dõi hành vi của môi trường production và liên hệ nó với các thay đổi triển khai.

Tracing và tạo dataset từ traces

1. Mở foundry-agent/trace/trace.md.
2. Dùng các workflow được tài liệu hóa để:
   • Thu thập traces từ agents của bạn
   • Chọn lọc và tạo datasets từ traces, lưu dưới .foundry/datasets
   • Đưa các datasets này vào workflow đánh giá để kiểm thử sát với thực tế hơn

Cách này đặc biệt hữu ích khi bạn muốn chuyển traffic người dùng thực thành các kịch bản đánh giá.

Khắc phục sự cố triển khai và lỗi runtime

1. Mở foundry-agent/troubleshoot/troubleshoot.md.
2. Làm theo các hướng dẫn troubleshooting cho các vấn đề như:
   • Lỗi triển khai và lỗi khởi động container
   • Endpoint, credentials hoặc connections bị cấu hình sai
   • Lỗi quota hoặc capacity (đối chiếu thêm quota/quota.md và quota/references/*.md)

Kết hợp tài liệu này với log và telemetry trong Application Insights để chẩn đoán và xử lý sự cố.

Quota, capacity và tối ưu hóa

1. Mở quota/quota.md để có cái nhìn tổng quan về:
   • Cách quota được áp dụng cho models và deployments trong Azure AI Foundry
   • Cách tư duy về capacity trên nhiều môi trường và vùng (region)
2. Xem các file trong quota/references/:
   • capacity-planning.md – giúp ước lượng capacity cho agents dựa trên pattern sử dụng
   • error-resolution.md – ánh xạ các lỗi thường gặp liên quan quota sang cách xử lý đề xuất
   • optimization.md – gợi ý cách tinh chỉnh workload để hoạt động trong giới hạn quota

Nội dung này giúp bạn tránh các bất ngờ khi scale và giữ cho agents phản hồi tốt.

Câu hỏi thường gặp (FAQ)

Có bắt buộc dùng microsoft-foundry mới sử dụng được Azure AI Foundry không?

Không. Bạn có thể dùng Azure AI Foundry trực tiếp qua Azure portal, CLI hoặc SDKs. Kỹ năng microsoft-foundry là một bộ hướng dẫn có cấu trúc, đóng gói best practice, workflow và tài liệu tham chiếu vào một nơi, giúp bạn thiết lập projects, agents và môi trường một cách nhất quán hơn.

Tôi có thể dùng microsoft-foundry cho các dịch vụ Azure không thuộc Foundry không?

Hãy dùng kỹ năng này khi mục tiêu chính của bạn là triển khai và vận hành Azure AI Foundry agents và projects. Với việc triển khai tổng quát cho web app, API hoặc các dịch vụ PaaS khác (App Service, Functions, generic containers), hãy dùng một kỹ năng hoặc hướng dẫn triển khai Azure chuyên biệt khác.

microsoft-foundry có hỗ trợ cả prompt agents và hosted agents không?

Có. Kỹ năng này có nội dung chuyên biệt cho cả hai loại:

• foundry-agent/create/create-prompt.md dành cho prompt agents.
• foundry-agent/create/create.md và foundry-agent/deploy/deploy.md dành cho hosted agents, bao gồm containerization, ACR và quản lý vòng đời container.

microsoft-foundry xử lý xác thực và bảo mật như thế nào?

Bảo mật và xác thực được đề cập trong references/auth-best-practices.md và rbac/rbac.md:

• Dùng managed identities và Azure RBAC trong production
• Chỉ dùng DefaultAzureCredential cho phát triển cục bộ
• Chọn loại credential phù hợp cho môi trường CI/CD và on-prem

Hãy xem kỹ các tài liệu này trước khi kết nối SDKs hoặc MCP tools để tránh cấu hình thiếu an toàn hoặc dễ hỏng.

Tôi có bắt buộc dùng MCP tools không, hay chỉ dùng SDKs cũng được?

Nội dung được viết để làm việc với MCP tools khi có, đồng thời cung cấp phương án fallback dùng SDK trong thư mục references/sdk. Ví dụ, create-prompt.md giải thích cách mặc định dùng azure-ai-projects SDK khi không có MCP tools.

Làm sao biết project của agent đã được cấu trúc đúng?

Hãy đối chiếu project của bạn với references/agent-metadata-contract.md. Đảm bảo bạn có:

• Thư mục .foundry/ tại agent root
• File agent-metadata.yaml hợp lệ bao gồm environments và test cases
• Các thư mục datasets/, evaluators/ và results/ như mô tả

Nếu tuân thủ hợp đồng này, phần còn lại của workflow microsoft-foundry sẽ khớp với bố cục project của bạn.

Tôi có thể dùng microsoft-foundry với cấu hình private network (VNet) không?

Có. references/private-network-standard-agent-setup.md cung cấp hướng dẫn chi tiết về:

• Cấu hình VNet và subnet cần thiết
• Các ràng buộc về region giữa tài nguyên Foundry và VNet
• Cách dùng Bicep template chính thức cho private-network standard agent setup

Hãy sử dụng tài liệu này cùng với references/standard-agent-setup.md khi bạn cần giữ traffic trong mạng riêng.

Sau khi cài đặt, tôi nên bắt đầu từ đâu trong repository?

Sau khi cài kỹ năng, hãy bắt đầu với:

1. SKILL.md – để có cái nhìn tổng quan về tất cả sub-skill
2. project/create/create-foundry-project.md – để thiết lập Foundry project
3. references/agent-metadata-contract.md – để chuẩn hóa bố cục agent
4. foundry-agent/create/ và foundry-agent/deploy/ – để build và triển khai agent đầu tiên của bạn

Sau đó, bạn có thể tiếp tục với eval-datasets, observe, trace, rbac và quota tùy theo nhu cầu kịch bản.