Nhập một agent khai báo của Microsoft Agent Framework — một agent và một máy chủ MCP
Một agent khai báo của Microsoft Agent Framework — một agent trên một mô hình OpenAI, tìm kiếm tài liệu qua một máy chủ MCP — được aggrega import soạn nháp thành các tệp Aggrega, với image của ứng dụng được trả lời một lần trong một tệp câu trả lời, và được build cho Docker Compose.
Nhập một agent khai báo của Microsoft Agent Framework hướng dẫn từng bước: lệnh, những gì nó hỏi, các tệp mà nó ghi và lý do mỗi dòng có mặt ở đó, quá trình build và agent đang chạy. Thư mục này chứa từng giai đoạn của hướng dẫn đó:
| thư mục hoặc tệp | nội dung |
|---|---|
source/ | agent khai báo, support-agent.yaml, .aggrega-config.yaml biến thư mục thành một không gian làm việc, và import-answers.yaml, các giá trị mà không agent khai báo nào chứa: image của ứng dụng, và tên của Kubernetes Secret mà một bản build cho Kubernetes đọc khóa OpenAI từ đó |
draft/ | các tệp mà aggrega import support-agent.yaml --target compose đã ghi, không thay đổi, bao gồm cả release.lock, và những gì nó đã in ra: stdout.txt trên đầu ra chuẩn, import.txt trên đầu ra lỗi chuẩn |
Agent khai báo được viết cho ví dụ này. Mã của ứng dụng, vốn tải agent đó, không thuộc ví dụ: quá trình nhập không bao giờ đọc mã đó, và Release chỉ định image mà ứng dụng chạy trong đó.
Trong một bản checkout của kho tài liệu, check.sh chạy lại quá trình nhập, so sánh những gì nó ghi và in ra với draft/, so sánh các khối mà hướng dẫn trích dẫn với các tệp này, và xác thực rồi build những gì quá trình nhập đã ghi. Nó cần catalog thư viện chuẩn (lấy ở đâu) được checkout bên cạnh kho này, hoặc thư mục của catalog đó được chỉ định trong AGGREGA_CATALOG_DIRS.
Tạo ví dụ
Bạn có thể chạy bước nhập của ví dụ này bằng các lệnh bên dưới, hoặc để trợ lý AI của bạn chạy thay bạn.
Ghi ví dụ vào một thư mục mới đặt theo tên của nó:
aggrega scaffold --example import-agent-frameworkSau đó nó in ra các lệnh cần chạy tiếp theo. Lệnh đầu tiên chuyển vào thư mục mới:
cd import-agent-frameworkBuild
Quá trình nhập soạn nháp các tệp Aggrega bên cạnh agent khai báo, trong source/. Nó đối chiếu dự án với catalog thư viện chuẩn, được registry mặc định của không gian làm việc phát hành dưới dạng một snapshot đã ký: lần nhập đầu tiên tải nó về, xác minh nó, giữ nó trong bộ nhớ đệm nội dung của không gian làm việc và gọi tên nó bằng digest của nó trong bản ghi mà nó ghi bên cạnh các bản nháp. Một không gian làm việc chỉ định các thư mục catalog của riêng mình — trong AGGREGA_CATALOG_DIRS, hoặc dưới workspace.catalog_dirs — sẽ nhập dựa trên các thư mục đó thay thế. Quá trình nhập đọc image từ import-answers.yaml, sau đó kéo về những gì mà Release được soạn nháp phụ thuộc vào, để bản build có thể tiếp theo ngay:
cd sourceaggrega import support-agent.yaml --target composeaggrega build --release release.yamlImage mà ví dụ nêu tên đại diện cho image bạn build từ dự án của mình; cách build nó và chạy stack có trong hướng dẫn được liên kết ở trên.
Với trợ lý AI
Một trợ lý AI được thiết lập với các công cụ của Aggrega cũng có thể làm như vậy: hãy dán prompt này vào trợ lý.
Chỉ sử dụng các công cụ của Aggrega và không tự tạo thư mục nào. Nếu thư mục không gian làm việc chưa chứa thư mục `import-agent-framework`, hãy gọi công cụ `scaffold` một lần với `example` đặt thành `import-agent-framework` và không có `dir`: công cụ này ghi ví dụ vào một thư mục `import-agent-framework` mới, trong đó thư mục `source` chứa những gì ví dụ này nhập. Sau đó gọi công cụ `import` với `workspace_root` đặt thành `import-agent-framework/source`, `source` đặt thành `support-agent.yaml` và `target` đặt thành `compose`: công cụ này đọc các câu trả lời cần thiết từ `import-answers.yaml` bên cạnh `support-agent.yaml`, ghi các bản nháp vào `import-agent-framework/source` và kéo về những gì chúng cần. Sau đó gọi công cụ `validate` với `workspace_root` đặt thành `import-agent-framework/source` và `release` đặt thành `release.yaml`, rồi gọi công cụ `build` với `workspace_root` đặt thành `import-agent-framework/source`, `release` đặt thành `release.yaml` và `write` đặt thành true. Hãy cho tôi biết lần build đã ghi những tệp nào; chúng nằm trong `import-agent-framework/source/dist/`.Kiểm thử
Khi stack đang chạy theo cách hướng dẫn từng bước chạy nó, một yêu cầu sẽ đến được agent. Route bên dưới là của chính chương trình trong hướng dẫn, một máy chủ HTTP nhỏ trên cổng 8000; chương trình của riêng bạn tự quyết định route của nó. Release công bố agent trên 127.0.0.1:8000, vì vậy yêu cầu được gửi từ máy của bạn:
curl -sS -X POST http://127.0.0.1:8000/ask -H 'Content-Type: application/json' \ -d '{"question": "In one short sentence: what is Azure Container Apps?"}'{"error": "the agent failed: ChatClientException: (\"<class 'agent_framework_openai._chat_client.OpenAIChatClient'> service failed to complete the prompt: Error code: 401 - Incorrect API key provided: sk-place************-key. [… omitted: where to find an API key, and the same error repeated as the exception it wraps]"}Khóa của lần chạy là một giá trị giữ chỗ, vì vậy câu trả lời là việc OpenAI từ chối khóa đó. Trên Kubernetes, hãy chuyển tiếp một cổng cục bộ tới Deployment, vốn không có Service, rồi gửi cùng yêu cầu đó tới nó từ một terminal khác:
kubectl port-forward deploy/supportagent 8000:8000curl -sS -X POST http://127.0.0.1:8000/ask -H 'Content-Type: application/json' \ -d '{"question": "In one short sentence: what is Azure Container Apps?"}'Câu trả lời vẫn như vậy.