Các importer lõi
Kho mã của trình biên dịch tự xây dựng mười plugin importer, mỗi plugin cho một định dạng nguồn, và phát hành chúng cùng mọi bản phát hành của trình biên dịch:
| Plugin | Phục vụ | Đọc |
|---|---|---|
importer/langflow | import:langflow | một flow được xuất từ Langflow, dưới dạng JSON |
importer/flowise | import:flowise | một chatflow hoặc một agentflow được xuất từ Flowise, dưới dạng JSON |
importer/n8n | import:n8n | một workflow được xuất từ n8n, dưới dạng JSON |
importer/mcp | import:mcp | cấu hình của một MCP client — .mcp.json, claude_desktop_config.json, .vscode/mcp.json hoặc .cursor/mcp.json — hoặc một mô tả máy chủ của MCP registry, server.json, dưới dạng JSON |
importer/compose | import:compose | một ứng dụng Compose — compose.yaml, docker-compose.yml và các tệp override của chúng — dưới dạng YAML |
importer/dify | import:dify | một ứng dụng được xuất từ Dify theo DSL của nó, dưới dạng YAML |
importer/crewai | import:crewai | các agent và task mà một dự án CrewAI khai báo — config/agents.yaml và config/tasks.yaml, dưới dạng YAML, hoặc crew.jsonc và agents/<name>.jsonc, hoặc các cách viết JSON chặt chẽ của chúng là crew.json và agents/<name>.json, dưới dạng JSON có chú thích |
importer/langgraph | import:langgraph | cấu hình của một ứng dụng LangGraph, langgraph.json, dưới dạng JSON, và của một tệp môi trường mà cấu hình đó nêu tên thì chỉ tên các biến, khi import được trao tệp đó dưới with.sources |
importer/google-adk | import:google-adk | các agent được khai báo trong các tệp Agent Config của một ứng dụng xây dựng trên Google ADK — root_agent.yaml và các cấu hình mà các sub-agent của nó nêu tên — dưới dạng YAML |
importer/agent-framework | import:agent-framework | một agent khai báo của Microsoft Agent Framework, một tài liệu thuộc kind Prompt với tên bất kỳ, dưới dạng YAML |
Mỗi importer được xây dựng từ chính mã nguồn của trình biên dịch và được gắn phiên bản của trình biên dịch, nên các
importer phát hành cùng trình biên dịch ở X.Y.Z báo cáo phiên bản X.Y.Z, và các thực thể Plugin của chúng
ghi lại phiên bản đó. Khác với các plugin được liệt kê trong Các plugin nhúng, không importer nào được biên dịch
vào tệp nhị phân. Tệp nhị phân mang thực thể Plugin của từng importer và digest của module duy nhất mà nó
chấp nhận cho importer đó, nên mỗi importer phục vụ định dạng của mình trong mọi workspace, mà không cần mục nào trong catalog.
Cả mười đều được xây dựng trên gói importer của bộ Go kit, github.com/aggrega-ai/aggrega-pdk/go/pkg/importer. Đối với các importer Langflow, Flowise và n8n, mọi việc một importer làm bất kể định dạng — chấm điểm các Components trong catalog của workspace so với từng node, quyết định tham chiếu một Component hay soạn nháp một Component mới, bố trí bản nháp, mang theo các giá trị thông tin xác thực mà nó chứa hoặc ghi chúng rỗng theo yêu cầu của một thiết lập, ghi các bản nháp và đọc các thiết lập bên dưới — đều thuộc về gói đó, và chỉ việc đọc định dạng, cùng việc biết nền tảng mà các flow chạy trên đó, là riêng của từng importer. Importer MCP soạn nháp một instance của một Component cho mỗi máy chủ, nên nó không chấm điểm gì; nó dùng chung cách gói đó đọc các thiết lập mà nó đọc, quyết định của gói về các giá trị thông tin xác thực và các quy ước đặt tên và mô tả bản nháp, như Importer MCP mô tả. Importer Compose quyết định mỗi service mà nó khớp giống như các importer flow quyết định một node, thông qua cùng gói đó, kết xuất bản nháp như chúng, và dùng chung phần còn lại như importer MCP, như Importer Compose mô tả. Importer Dify soạn nháp bản cài đặt Dify mà thư viện chuẩn lắp ráp, mang theo ứng dụng, thông qua bản nháp nền tảng của cùng gói đó theo dạng nó có cho một nền tảng là cả một bản cài đặt, như Importer Dify mô tả. Importer CrewAI soạn nháp một instance của agent CrewAI trong thư viện chuẩn cho mỗi agent mà một dự án khai báo, nối với model mà agent đó nêu tên, và dùng chung phần còn lại như importer MCP, như Importer CrewAI mô tả. Importer LangGraph soạn nháp một instance của agent LangGraph trong thư viện chuẩn cho mỗi graph mà cấu hình của một ứng dụng khai báo, nối với kho dữ liệu nơi checkpointer của nó lưu trạng thái, và dùng chung phần còn lại như importer MCP, như Importer LangGraph mô tả. Importer Google ADK soạn nháp một instance của agent ADK trong thư viện chuẩn cho mỗi cây agent mà các cấu hình của một ứng dụng khai báo, nối với model mà cây đó nêu tên khi ADK gửi các yêu cầu của nó tới Gemini API, và dùng chung phần còn lại như importer MCP, như Importer Google ADK mô tả. Importer Agent Framework soạn nháp một instance của agent Agent Framework trong thư viện chuẩn cho mỗi agent khai báo, nối với model OpenAI mà agent đó nêu tên — mỗi máy chủ MCP mà nó nêu tên được ghi trong phần chú thích, vì nhà cung cấp của model kết nối tới máy chủ đó như một công cụ được host — và dùng chung phần còn lại như importer MCP, như Importer Agent Framework mô tả. Cách socket importer hoạt động, và những gì nó được trao, được mô tả trong Socket importer.
Trang này là tài liệu tham khảo về những gì mỗi trình nhập đọc và soạn nháp. Để nhập một dự án của riêng bạn và build kết quả, hãy bắt đầu tại Nhập, nơi hướng dẫn một dự án từ nguồn của nó đến một bản build, lần lượt từng định dạng.
Cách một lần nhập lấy được một importer
aggrega import, phương thức aggrega/import của phiên trình soạn thảo và công cụ import của trợ lý lấy một core importer theo cùng một cách. Khi máy đã có module của nó — trong bộ nhớ đệm nội dung của workspace — lần nhập đọc nó từ đó, không cần đến mạng cho việc này. Khi máy chưa có, lần nhập đầu tiên cần đến nó sẽ tải nó từ registry mặc định của workspace, ở phiên bản của trình biên dịch, và:
- đối chiếu nó với digest mà tệp nhị phân mang theo, để chỉ module mà bản phát hành của trình biên dịch đã công bố được chạy;
- xác minh nó như một lần pull xác minh một plugin mà nó tải về — chữ ký của nó theo chính sách tin cậy của registry đó, và các hàm host mà nó dùng so với các hàm mà thực thể Plugin của nó ghi lại;
- lưu nó trong bộ nhớ đệm nội dung của workspace, đây là thứ duy nhất được ghi cho nó: không có lockfile và không có bản ghi về các plugin được tin cậy, vì một lần nhập không ghim importer nào cả.
Mọi lần nhập sau đó đều đọc nó từ bộ nhớ đệm nội dung. Một module không xác minh được sẽ bị từ chối, và không có gì được lưu. Trong một thư mục không được workspace nào đánh dấu thì không có bộ nhớ đệm nội dung để lưu nó, nên việc tải bị từ chối ở đó, kèm tên thư mục và cách chỉ định một workspace hoặc biến thư mục đó thành một workspace. Module không bao giờ được đọc từ bên cạnh một thực thể Plugin cùng tên ở phiên bản khác trong một thư mục catalog: module đó thuộc về thực thể kia.
Khi không thể tải được module, lần nhập dừng lại với lỗi
A plugin’s .wasm is not on this machine (Tệp của plugin không có trên máy này),
nêu tên importer và phiên bản của nó, và cho biết điều gì đưa module của nó lên máy:
- Chạy lần nhập một lần khi có mạng, trong trường hợp workspace đang ngoại tuyến hoặc không thể truy cập registry của nó. Lần chạy đó tải module về và mọi lần chạy sau đều ngoại tuyến.
- Đặt module của nó bên cạnh một thực thể Plugin của importer đó ở phiên bản đó trong một thư mục catalog, dưới tên mà thông báo đưa ra —
importer--langflow.wasmcho importer Langflow. Một thực thể catalog có cùng tên và phiên bản với một core importer sẽ chạy thay cho nó, với module được đọc từ bên cạnh thực thể đó; một thực thể ở đó mà không có module bên cạnh thì không chạy thay cho nó, và core importer được lấy như mô tả ở trên. Khi registry không có module, hoặc workspace không chỉ định registry mặc định nào, đây là biện pháp khắc phục duy nhất mà thông báo đưa ra.
Importer nào chạy bên cạnh các importer của riêng bạn
Các core importer là ứng viên bên cạnh các importer mà catalog của workspace bạn chứa, theo các quy tắc chọn mọi importer, được trình bày trong Which importer turns a source into drafts (Importer nào biến một nguồn thành bản nháp):
- Trong cùng một tên, phiên bản cao nhất sẽ chạy, hoặc phiên bản mà một mục
plugins.importerchỉ định. - Khi catalog của bạn chứa một importer có tên khác cho
langflow,flowise,n8n,mcp,compose,dify,crewai,langgraph,google-adkhoặcagent-framework, sẽ có hai importer quảng bá định dạng đó, và một lần import không gắn importer nào trong hai sẽ bị từ chối, nêu tên cả hai, theo A parse or import format is advertised by more than one plugin (Một định dạng parse hoặc import được nhiều hơn một plugin quảng bá). Một mụcplugins.importerchỉ định importer bạn muốn sẽ giải quyết việc này. - Một importer mà catalog của bạn chứa với cùng tên và phiên bản như một core importer, với module nằm bên cạnh entity của nó, là importer sẽ chạy, được đọc từ đó.
- Một thực thể Plugin mang tên của một core importer mà không có module bên cạnh trong thư mục catalog của nó — ví dụ như trong một bản checkout của catalog ghi lại các importer mà một bản phát hành đã công bố — là thực thể mà không lần import nào có thể chạy, vì module của nó không được đọc từ bất kỳ nơi nào khác; do đó nó không phải là ứng viên để chạy, mặc dù các chữ ký mà nó ghi lại vẫn tham gia vào việc nhận diện nguồn. Ở chính phiên bản của trình biên dịch, core importer chạy thay cho nó. Ở bất kỳ phiên bản nào khác, cũ hơn hay mới hơn, nó bị bỏ qua, và lựa chọn được thực hiện trong số các importer có thể chạy — trừ khi một mục
plugins.importerchỉ định đúng phiên bản đó, hoặc không có importer nào cùng tên có thể chạy khai báo định dạng được yêu cầu, như khi thực thể ghi lại một định dạng mà importer của chính trình biên dịch không ghi lại. Khi đó nó vẫn là ứng viên theo các quy tắc ở trên, và lần import chọn nó sẽ dừng lại, nêu tên thư mục cần đặt module của nó.
Dù importer nào của chính catalog của bạn được chọn, module của nó được đọc từ bên cạnh thực thể của chính nó, ở phiên bản của chính nó: một module đặt bên cạnh một thực thể cùng tên ở phiên bản khác thuộc về thực thể đó.
Cách nhận diện một nguồn
Một lần nhập không nêu định dạng của nó bằng --format sẽ được nhận diện qua các chữ ký mà mỗi trình nhập
khai báo:
- Langflow — một nguồn phân tích được dưới dạng JSON và mang một mảng tại
data.nodes. - Flowise — một nguồn phân tích được dưới dạng JSON, mang các mảng tại
nodesvàedges, và không mang gì tạidata.nodes. - n8n — một nguồn phân tích được dưới dạng JSON, mang một mảng tại
nodesvà một đối tượng tạiconnections, và không mang gì tạiedgeshay tạidata.nodes. - MCP — một nguồn phân tích được dưới dạng JSON, có tên
.mcp.json,claude_desktop_config.jsonhoặc.cursor/mcp.jsonvà mang một đối tượng tạimcpServers; một nguồn phân tích được dưới dạng JSON có chú thích, như Visual Studio Code đọc nó, có tên.vscode/mcp.jsonvà mang một đối tượng tạiservers; hoặc một nguồn có tên bất kỳ phân tích được dưới dạng JSON và có$schemalà một văn bản bắt đầu bằnghttps://static.modelcontextprotocol.io/schemas/, tức một mô tả máy chủ registry. Tên được so khớp với phần cuối của đường dẫn được trao cho lần nhập, nênproject/.vscode/mcp.jsonđược nhận diện, cònmcp.jsonđược trao từ bên trong.vscode, hoặc tệp của một client dưới bất kỳ tên nào khác, được nhập bằng cách nêu--format mcp. - Compose — một nguồn phân tích được dưới dạng YAML, có tên như Compose mặc định đọc một tệp Compose hoặc tệp
ghi đè của nó —
compose.yaml,compose.yml,docker-compose.yml,docker-compose.yaml,compose.override.yml,compose.override.yaml,docker-compose.override.ymlhoặcdocker-compose.override.yaml— và mang một đối tượng tạiservices. Một tệp Compose dưới bất kỳ tên nào khác được nhập bằng cách nêu--format compose. - Dify — một nguồn có tên bất kỳ phân tích được dưới dạng YAML, mang văn bản
apptạikind, và mang một giá trị nào đó tạiapp.modevà tạiversion, như mọi ứng dụng Dify xuất ra đều có. - CrewAI — một nguồn có tên
config/agents.yamlhoặcconfig/tasks.yamlphân tích được dưới dạng YAML, một nguồn có têncrew.jsonchoặccrew.jsonphân tích được dưới dạng JSON có chú thích và mang một danh sách tạiagents, hoặc một nguồn có tênagents/<name>.jsonchoặcagents/<name>.jsonphân tích được dưới dạng JSON có chú thích và mang một giá trị nào đó tạirole. Một dự án kiểu cổ điển đặt khóa cho các agent và các task của nó bằng những tên do tác giả tự chọn, nên hai tệp của nó chỉ được phân biệt qua tên. - LangGraph — một nguồn có tên
langgraph.jsonphân tích được dưới dạng JSON và mang một đối tượng tạigraphs; hoặc một nguồn có tên bất kỳ phân tích được dưới dạng JSON, mang một đối tượng tạigraphsvà có$schemalà văn bảnhttps://langgra.ph/schema.json, schema mà LangGraph công bố cho cấu hình của nó. Một cấu hình dưới tên khác không nêu schema nào được nhập bằng cách nêu--format langgraph. Không chữ ký của trình nhập nào nêu tên một tệp môi trường, nên việc nhận diện một thư mục không mở tệp nào như vậy. - Google ADK — một nguồn có tên
root_agent.yamlphân tích được dưới dạng YAML và mang một giá trị nào đó tạinamevà tạiinstruction, như cấu hình của một LlmAgent, hoặc một văn bản tạiagent_classvà một giá trị nào đó tạiname, như cấu hình của mọi agent khác. Một cấu hình dưới tên khác được nhập bằng cách nêu--format google-adk. Không chữ ký nào nêu tên cấu hình của một sub-agent, vốn có thể mang tên bất kỳ, nên việc nhận diện một thư mục không mở tệp YAML nào ngoàiroot_agent.yaml. - Agent Framework — một nguồn có tên bất kỳ phân tích được dưới dạng YAML, mang văn bản
Prompttạikindvà một đối tượng tạimodel, như một agent khai báo có nêu mô hình của nó; Agent Framework nạp một agent khai báo từ bất kỳ tệp nào mà ứng dụng của nó nêu tên, nên chữ ký không nêu tên tệp nào. Một agent khai báo không nêu mô hình, hoặc viết kind của nó theo kiểu chữ hoa thường khác hay dưới dạngAgent, được nhập bằng cách nêu--format agent-framework.
Một nguồn khớp với hai trong số chúng sẽ bị từ chối với tên của cả hai định dạng, và được nhập bằng cách nêu tên một định dạng với --format. Các trình nhập Langflow, Flowise, n8n và LangGraph đọc nguồn của chúng qua trình phân tích phục vụ parse:json, trình nhập MCP đọc một cấu hình liệt kê các máy chủ của nó dưới servers qua trình phân tích phục vụ parse:jsonc và mọi nguồn khác qua trình phân tích phục vụ parse:json, các trình nhập Compose, Dify, Google ADK và Agent Framework qua trình phân tích phục vụ parse:yaml, và trình nhập CrewAI đọc các tệp của một dự án kiểu cổ điển qua trình phân tích phục vụ parse:yaml và các tệp còn lại qua trình phân tích phục vụ parse:jsonc: đó là trình phân tích mà catalog của workspace của bạn phục vụ, nếu nó phục vụ một trình như vậy, và nếu không thì là trình phân tích mà chính trình biên dịch mang theo cho cú pháp đó (xem Embedded plugins). Vì vậy một lần nhập qua bất kỳ trình nào trong số chúng không cần trình phân tích nào trong catalog của bạn, và không có gì được tải về cho nó. Một trình phân tích mà catalog của bạn có phục vụ là trình được dùng, và trình của trình biên dịch không tham gia. Các trình nhập Langflow, Flowise, n8n, Dify và Agent Framework không khai báo mẫu tệp nào, nên mỗi trình đọc một tệp và việc nhập một thư mục qua bất kỳ trình nào trong số đó đều bị từ chối; trình nhập MCP khai báo bốn tên tệp của client, nên một thư mục được đọc qua các cấu hình client mà nó chứa; trình nhập Compose khai báo tám tên tệp Compose, nên một thư mục được đọc qua các tệp Compose mà nó chứa; trình nhập CrewAI khai báo sáu tên khai báo của một dự án, nên thư mục của một dự án được đọc qua các khai báo của nó và không gì khác; trình nhập LangGraph khai báo langgraph.json, nên thư mục của một ứng dụng được đọc chỉ qua cấu hình của nó, và cả mã lẫn tệp môi trường của nó đều không bao giờ được đọc; và trình nhập Google ADK khai báo root_agent.yaml, nên thư mục của một ứng dụng được đọc chỉ qua cấu hình gốc của nó — các cấu hình mà các sub-agent của nó nêu tên chỉ đến được trình nhập dưới with.sources của phần đính kèm của nó — và cả mã lẫn tệp môi trường của nó đều không bao giờ được đọc. Một chữ ký không nêu tên tệp nào — của các trình nhập Langflow, Flowise và n8n, của trình nhập MCP cho một mô tả máy chủ registry, của trình nhập LangGraph cho một cấu hình có nêu schema của nó, của trình nhập Dify và của trình nhập Agent Framework — áp dụng cho mọi tệp được nhập riêng lẻ: một lần nhập không nêu định dạng sẽ đọc một tệp như vậy dưới dạng JSON, và dưới dạng YAML, để thử chúng, bất kể nó dành cho trình nhập nào, qua chính các trình phân tích đó — trình biên dịch mang theo cả hai, nên không có gì được tải về cho trình nào. Một tệp chứa chú thích hoặc dấu phẩy thừa ở cuối không phân tích được dưới dạng JSON, nên không chữ ký đọc JSON nào nhận diện nó; các chữ ký của trình nhập CrewAI cho crew.jsonc, agents/<name>.jsonc và các cách viết .json của chúng, cùng chữ ký của trình nhập MCP cho .vscode/mcp.json, đọc JSON có chú thích, qua trình phân tích mà trình biên dịch mang theo cho cú pháp đó khi catalog của bạn không phục vụ trình nào.
Một nguồn bị trình phân tích của nó từ chối — với các trình nhập Langflow, Flowise, n8n và LangGraph là nguồn không phải
JSON, với trình nhập MCP là nguồn không phải JSON có chú thích hoặc, trừ khi nó liệt kê các máy chủ của nó dưới
servers, không phải JSON, với các trình nhập Compose, Dify và Agent Framework là nguồn
không phải YAML, với trình nhập CrewAI là một khai báo không phải YAML hoặc không phải JSON có chú thích, và với
trình nhập Google ADK là một cấu hình không phải YAML —
sẽ dừng lần nhập với
parse-failed, có thông điệp mang lý do của chính trình phân tích. Việc nêu định dạng không thay đổi điều đó:
trình nhập yêu cầu cây của nguồn, và sự từ chối của trình phân tích là câu trả lời nó nhận được.
Cách đặt tên cho bản nháp
Mỗi importer đặt tên cho Aggregate mà nó soạn nháp, và cho Release bên cạnh nếu nó soạn nháp một bản, là <target_namespace>/<name>. Phần đầu là thiết lập target_namespace, là imported trừ khi bạn đặt giá trị khác. <name> là mục đầu tiên không rỗng trong các mục sau:
-
tên mà nguồn tự đặt cho mình, trong trường mà định dạng của nó khai báo tên đó:
Importer Tên mà nó đọc importer/langflownamecủa flowimporter/flowisekhông có: một bản export không mang tên riêng importer/n8nnamecủa workflowimporter/mcpnamecủa mô tả server trong registry; cấu hình của client không mang tên nàoimporter/composenamecấp cao nhất của dự án, tên của tệp override thay cho tên của tệp mà nó ghi đè, theo cách Compose hợp nhất chúngimporter/difynamecủa ứng dụng, dướiappimporter/crewainamecủa crew trongcrew.jsonchoặccrew.json;config/agents.yamlvàconfig/tasks.yamlkhông mang tên nào, vì một dự án kiểu cổ điển đặt tên crew trong chương trình của nóimporter/langgraphid của graph mà cấu hình khai báo, vì một cấu hình không mang tên riêng importer/google-adknamecủa agent gốcimporter/agent-frameworknamecủa agent;displayNamecủa nó không được đọc -
tên đầy đủ của thư mục được giao cho lần import —
my.projectgiữ dấu chấm của nó, được viết làmy-project— giống như Compose đặt tên dự án theo thư mục chứa nó;aggrega import .đặt tên theo thư mục nơi nó chạy; -
tên của tệp được giao riêng lẻ cho lần import, không có phần mở rộng;
-
flow.
Một bản nháp được tạo từ nhiều nguồn — nhiều dự án Compose, cấu hình, cây agent hoặc server, hoặc một cấu hình khai báo nhiều graph — chỉ lấy tên của chúng khi mọi nguồn đều tự đặt tên và tất cả được viết giống nhau; nếu không, nó lấy mục tiếp theo. Tên được viết bằng chữ thường, mỗi chuỗi ký tự không phải chữ cái và chữ số ASCII được viết thành một dấu gạch nối, và các dấu gạch nối ở hai đầu bị bỏ đi: Basic Prompting được viết là basic-prompting, và SupportAgent là supportagent. Cùng một nguồn được đặt tên giống nhau ở mọi lần import. Một Manifest mà lần import soạn nháp cho một target sẽ lấy tên của Release, hoặc tên của Aggregate khi không có Release nào được soạn nháp, như Những gì một target thêm vào mô tả.
Những gì importer Langflow đọc
- Các node và edge nằm dưới đối tượng
datacấp cao nhất của flow, tứcdata.nodesvàdata.edges. - Với mỗi node: kiểu của nó lấy từ
data.typecủa node, và các trường của nó lấy từ các mục củadata.node.templatecó giá trị là một đối tượng mangtype. Các mục khác của template không phải là trường. - Một trường có đối tượng mang
password: trueđược phác thảo thành một khe thông tin xác thực, và mọi trường khác thành một trường giá trị. Tên của trường không đóng vai trò gì, và việc phác thảo một node thành một Component không đọc giá trị của trường nào. - Một ghi chú ghim trên canvas, tức một node có kiểu
noteNode, không được import, và một edge tới một node không được import sẽ bị loại bỏ. - Việc phác thảo nền tảng mang flow còn đọc thêm từ flow:
idcấp cao nhất của nó; giá trị của mỗi trường được đánh dấupassword: true; trườngmcp_servercủa một node MCP Tools — máy chủ MCP mà nó nêu tên, cùng cấu hình của máy chủ đó — hoặc các trường mà nó giữ máy chủ của mình thay vào đó; mỗi đầu vào mà Langflow đánh dấu là không phải thông tin xác thực nhưng có thể mang một thông tin xác thực, như Các giá trị thông tin xác thực mà flow nắm giữ liệt kê; trường mà một node nêu tên mô hình của nó, và nhà cung cấp mô hình mà nó chạy trên đó; và các trường qua đó một node truy cập địa chỉ và khóa của một thành phần, mà nó viết lại. Những gì chúng phác thảo cho biết điều gì xảy ra với từng mục.
Những gì trình nhập Flowise đọc
- Các nút và các cạnh ở cấp cao nhất của luồng,
nodesvàedges. - Với mỗi nút: kiểu của nút lấy từ
data.namecủa nút; các khe thông tin xác thực của nút lấy từ các mục củadata.inputParamscótypelàcredential, theonamecủa chúng; và các trường giá trị của nút lấy từ các khóa củadata.inputs, trừ đi những khóa màdata.inputAnchorsnêu tên — nơi một nút khác kết nối vào, điều mà cạnh giữa chúng ghi lại — và trừ đi các thông tin xác thực. - Việc phác thảo một nút thành một Component không đọc giá trị của trường nào, và tên của một thông tin xác thực không đóng vai trò gì trong việc nó là thông tin xác thực.
- Một ghi chú được ghim trên canvas, tức một nút có kiểu
stickyNote, không được nhập, và một cạnh nối tới một nút không được nhập sẽ bị loại bỏ. - Việc phác thảo nền tảng mang chatflow cũng đọc từ chatflow đó:
idở cấp cao nhất của nó, khi đó là một UUID; thông tin xác thực mà một nút giữ tạidata.credential; giá trị của mỗi đầu vào màinputParamscủa nút khai báo có kiểupassword;FLOWISE_CREDENTIAL_IDtrong số các đầu vào của một nút, vàcredentialhoặcFLOWISE_CREDENTIAL_IDbên trong một đối tượng cấu hình ở bất kỳ độ sâu nào của chúng; cấu hình máy chủ trong đầu vàomcpServerConfigcủa một nút; mỗi đầu vào mà Flowise đánh dấu là không phải thông tin xác thực nhưng có thể mang một thông tin xác thực, như Các giá trị thông tin xác thực mà luồng nắm giữ liệt kê, và thành viên mà cấu hình của một agentflow dùng để nêu tên mô hình hoặc công cụ nó chọn; đầu vàomodelNamecủa một nút; và Base Path của một nút OpenAI, tức đầu vàobasepathcủa nó. Những gì chúng phác thảo cho biết điều gì xảy ra với từng thứ.
Những gì trình nhập n8n đọc
- Các
nodesvà cácconnectionscủa workflow, ở cấp cao nhất của bản xuất. - Với mỗi node,
namecủa nó, dùng để định danh nó — các kết nối của n8n gọi tên các node mà chúng nối bằng tên, và tên các node trong một workflow là duy nhất — vàtypecủa nó, viết đầy đủ, kèm gói của nó: chẳng hạn@n8n/n8n-nodes-langchain.lmChatOpenAi, hoặcn8n-nodes-base.httpRequest. Một node không có tên được định danh bằngidcủa nó. - Mỗi kết nối mà workflow liệt kê là một cạnh, từ node nó rời đi đến node nó đi vào,
bất kể loại của nó: một kết nối
mainchuyển dữ liệu từ node này sang node kế tiếp, và một kết nối AI —ai_languageModel,ai_tool,ai_vectorStore,ai_embedding,ai_memoryvà các loại khác — trao cho node nó đi vào mô hình, công cụ, kho lưu trữ hoặc bộ nhớ mà node nó rời đi đại diện. Dù theo cách nào, node mà một kết nối đi vào đều tiêu thụ node mà kết nối đó rời đi. - Mỗi loại thông tin xác thực mà
credentialscủa một node nêu tên, và mỗi tham số cấp cao nhất mà n8n đánh dấu là mật khẩu, được soạn thành một khe thông tin xác thực; mỗi tham số cấp cao nhất khác của node là một trường giá trị. Việc soạn một node thành một Component không đọc giá trị của trường nào. - Một ghi chú ghim trên canvas, tức một node loại
n8n-nodes-base.stickyNote, không được nhập, và một kết nối tới một node không được nhập sẽ bị loại bỏ. - Việc soạn nền tảng chứa workflow cũng đọc từ nó:
idcấp cao nhất của nó; mỗi thông tin xác thực mà một node chọn; mỗi tham số mà n8n đánh dấu là mật khẩu; địa chỉ mà một node MCP client gọi tới; các header và tham số truy vấn mà một node gửi kèm một yêu cầu do workflow tạo ra, như Các giá trị thông tin xác thực mà flow chứa liệt kê; và tham số mà một node mô hình dùng để nêu tên mô hình của nó. Những gì chúng soạn cho biết điều gì xảy ra với từng thứ.
Những gì chúng soạn thảo
Mỗi nút được đối chiếu với các Components trong danh mục riêng của workspace và không gì khác, như importer socket mô tả, và mỗi importer mang theo một bảng ngắn ánh xạ các loại nút phổ biến của định dạng của nó — các mô hình chat và embedding, truy xuất, yêu cầu HTTP và, trên Langflow, nút MCP Tools MCPTools, được ánh xạ tới core/ai-tool/mcp — sang các Components của thư viện chuẩn. Bảng của Langflow cũng ánh xạ thành phần Language Model, LanguageModelComponent, mô hình chat mà các flow khởi đầu của Langflow gọi, tới core/ai-model/openai, mô hình mà kết nối mô hình của nền tảng Langflow phục vụ: nút chạy trên nhà cung cấp mô hình mà trường provider của nó đặt tên, mặc định là OpenAI, và một nút đặt tên một nhà cung cấp khác không bao giờ được nối vào kết nối đó, như Những nút nào trở thành phần mô tả. Bảng của importer n8n ánh xạ các mô hình chat và embedding của n8n, công cụ MCP client của nó tới core/ai-tool/mcp, các công cụ HTTP request, công cụ SerpApi, các vector store Qdrant, PGVector, Chroma, Milvus và Weaviate, cùng các bộ nhớ chat Postgres và Redis. Một nút mà n8n chạy ngay trong workflow — một agent, một chain, một trigger, một bộ nhớ mà workflow giữ trong tiến trình của chính nó, một công cụ code — thuộc về chính workflow, và không hàng nào ánh xạ nó. Một hàng của bảng đó chỉ được tính vào việc khớp khi danh mục của workspace chứa Component mà nó nêu tên. Lệnh báo cáo một dòng cho mỗi nút mà nó đã ánh xạ, nêu tên thứ nó đã chọn, bậc khớp và điểm của ứng viên tốt nhất, và một dòng ghi made no choice for <node id> (<node type>) cho một nút mà nó không gán Component riêng nào. Một nút được tham chiếu tới một Component trong danh mục, thay vì được soạn thảo, không có tệp riêng: Aggregate bản nháp nêu tên Component đó.
Cách bố trí bản nháp do thiết lập layout quyết định. platform, giá trị mặc định, soạn thảo nền tảng chạy flow, mang theo flow như khi được xuất, và chỉ gán một Component riêng cho mỗi phần của flow mà một socket của nền tảng tiếp nhận — trên các nền tảng của thư viện chuẩn, đó là một mô hình, một MCP server hoặc một công cụ khác được truy cập qua HTTP, và một vector store. nodes soạn thảo mỗi nút thành một Component riêng.
Nền tảng mang theo flow
Theo mặc định, một lần import ghi ra:
aggregate.yaml— một Aggregate bản nháp được đặt tên theo flow, như Cách đặt tên cho bản nháp mô tả. Nó chứa một instance của nền tảng chạy flow —core/ai-agent/langflow, dưới khóalangflow, cho một flow Langflow,core/ai-agent/flowise, dưới khóaflowise, cho một flow Flowise, vàcore/ai-agent/n8n, dưới khóan8n, cho một workflow n8n — tham chiếu tới Component cùng tên trong danh mục. Instance mang flow trongvalues.flow_definitionvà nêu tên nó trong giá trị định danh,flow_idtrên Langflow,chatflow_idtrên Flowise vàworkflow_idtrên n8n. Mỗi phần của flow là một mục riêng bên cạnh nó, được nối với nền tảng dướiusescủa instance.release.yaml— một Release bản nháp cùng tên, chỉ đến Aggregate đó, có một mục cho nền tảng và một mục cho mỗi phần, mang image của nền tảng và gắn mọi bí mật mà bản nháp cần theo tham chiếu, như Những gì bản nháp để lại cho Release mô tả.- một tệp dưới
components/cho mỗi phần mà nó soạn thảo thay vì tham chiếu, được viết như bố trí theo từng nút viết một nút được soạn thảo.
Khi có đích, lần nhập soạn manifest.yaml bên cạnh chúng, như Những gì một đích bổ sung mô tả.
Mọi nút không phải là một phần đều ở lại bên trong flow mà nền tảng mang theo và không trở thành Component nào. Quyết định của nó ghi lại các ứng viên mà nó đã được đối chiếu và không chọn gì, và lý do của nó ghi kept in the flow <platform> carries, with no Component of its own:, theo sau là nguyên nhân — chẳng hạn không hàng ánh xạ nào nêu tên loại của nó và ứng viên gần nhất chỉ đạt chừng ấy điểm. Flow giữ các cạnh giữa các nút; bản nháp không tự viết cạnh nào.
Chatflow Multiple Documents QnA của Flowise, được export thành Multiple Documents QnA.json và được import không có thiết lập nào và không có đích trên một danh mục chứa nền tảng Flowise của thư viện chuẩn cùng các Components mô hình và công cụ truy xuất của nó, được soạn thảo thành Aggregate này, phần lớn flow được lược bỏ ở đây và đánh dấu ...:
apiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: imported/multiple-documents-qna version: 0.1.0 description: Draft Aggregate imported from a source in the flowise format.spec: components: flowise: type: core/ai-agent/flowise # For the compose target only, uncomment the lines below, which declare owner_password on flowise: a secret the Release alone attaches arrives under the key value, so each is declared with a key of its own and no two arrive under one; the Release attaches its origin, naming this type or none. # features: # owner_password: # type: core/secret-value # values: # key: OWNER_PASSWORD values: # chatflow_id is derived from the exported flow, which gives no identifier of its own. chatflow_id: '96da3b80-86d0-5f23-b4e7-2573ea1f76ad' flow_definition: | { "description": "Tool agent that can retrieve answers from multiple sources using relevant Retriever Tools", ... "embeddings": "{{"{{"}}openAIEmbeddings_0.data.instance}}", ... } uses: model: chatopenai-0: target: chatopenai-0 # For the compose target only, uncomment the lines below, which declare credential on chatopenai-0: a secret the Release alone attaches arrives under the key value, so each is declared with a key of its own and no two arrive under one; the Release attaches its origin, naming this type or none. # features: # credential: # type: core/secret-value # values: # key: OPENAI_API_KEY # swap to core/ai-model/azure-openai (score 0.4000) by setting type: core/ai-model/azure-openai chatopenai-0: type: core/ai-model/openai values: model: |- gpt-3.5-turboMô hình chat của nó là phần duy nhất được nối; hai mô hình embedding ở lại trong flow, vì socket mô hình chỉ nhận một kết nối duy nhất, và các công cụ retriever ở lại trong flow, vì không socket nào của nền tảng tiếp nhận chúng. Lần import báo cáo từng thứ.
Định danh của flow là định danh mà bản xuất gán cho nó — id cấp cao nhất của một flow Langflow, id cấp cao nhất của một chatflow Flowise khi đó là một UUID, và id cấp cao nhất của một workflow n8n — khi định danh đó gồm từ một đến 128 chữ cái, chữ số, ., -, _ hoặc :, bắt đầu bằng một chữ cái hoặc chữ số. Khi bản xuất không có định danh nào, hoặc có một định danh chứa ký tự khác, bản nháp ghi một UUID dựa trên tên, được suy ra từ tên định dạng và flow như được mang theo, nên một flow luôn cho ra một định danh, và một chú thích phía trên giá trị cho biết nó được suy ra. Một chatflow được xuất từ trình soạn thảo của Flowise không mang id, nên nó được gán một định danh suy ra.
Khi danh mục của workspace không chứa Component nào mang tên của nền tảng, bản nháp vẫn nêu tên nền tảng nhưng không nối phần nào với nó: mỗi nút lẽ ra là một phần sẽ ở lại trong flow, được báo cáo, và lần import cảnh báo rằng danh mục không chứa Component như vậy.
Những nút nào trở thành phần, và mỗi phần được nối ở đâu
Một nút là một phần của flow khi một hàng trong bảng ánh xạ của importer, hoặc một mục mapping_overrides, ánh xạ loại của nó, hoặc khi ứng viên tốt nhất của nó khớp ít nhất ở bậc trung bình. Một nút MCP Tools của Langflow là một phần bất kể điểm số: nó nêu tên MCP server mà nó gọi, và server đó chính là phần. Một phần trở thành một Component riêng, được tham chiếu hoặc soạn thảo đúng như reuse_mode quyết định, và được nối với socket đầu tiên của nền tảng — theo thứ tự mà mục danh mục của nền tảng khai báo các socket — có label selector được Component của phần thỏa mãn: các label của Component mà nó tham chiếu, hoặc, với một phần nó soạn thảo, các label của ứng viên tốt nhất khi ứng viên đó khớp ít nhất ở bậc trung bình. Một phần có Component không thỏa mãn selector của socket nào, hoặc không có Component để đọc label, sẽ ở lại trong flow, và lần import báo cáo nó.
Những quy tắc này thu hẹp điều đó:
- Một mô hình Langflow đặt tên một nhà cung cấp khác không nhận kết nối mô hình nào. Một nút
LanguageModelComponenthoặcEmbeddingModelchạy trên nhà cung cấp mô hình mà trườngprovidercủa nút đặt tên, hoặc, ở nơi trường đó trống, nhà cung cấp của mô hình mà trườngmodelchọn. Nền tảng cung cấp kết nối mô hình của nó cho một client tương thích OpenAI, nên một nút đặt tên bất kỳ nhà cung cấp nào khácOpenAI— bất kể một hàng ánh xạ hay một override ánh xạ nó tới đâu — không bao giờ được nối vào socketmodel: nó được nối vào socket kế tiếp mà Component của nó thỏa mãn, hoặc ở lại trong flow, với quyết định của nó không chọn gì và không có Component nào được soạn thảo cho nó, và quá trình nhập báo cáo nút đó kèm tên nhà cung cấp mà nó chạy trên. Một nút không chọn nhà cung cấp nào, đặt tên nhà cung cấp qua một biến toàn cục, hoặc lấy mô hình từ một nút khác được nối như mọi phần khác. - Một socket chỉ nhận một kết nối duy nhất được giữ bởi một phần. Trên mọi nền tảng, socket
modelnhận một kết nối, mà các Recipes của nền tảng cung cấp dưới dạng mộtOPENAI_BASE_URLvà mộtOPENAI_API_KEY. Khi nhiều phần được đặt vào đó, phần đầu tiên có Component mangmodel.aggrega.ai/capability: generativesẽ giữ nó — hoặc phần đầu tiên, khi không phần nào mang — và mọi phần khác ở lại trong flow, được báo cáo cùng với phần đang giữ kết nối và cách flow tiếp cận phần đó theo như nút của nó được viết. - Langflow chỉ tiếp cận một kết nối
toolsthông qua một nút MCP Tools nêu tên nó. Nền tảng ghi địa chỉ của một kết nối tools vào cấu hình server của nút MCP Tools có trườngmcp_servernêu tên kết nối đó, nên một nút có template không mang trườngmcp_server— bất kể loại của nó, và bất kể một hàng ánh xạ hay override ánh xạ nó tới đâu — không bao giờ được nối với sockettools: nó được nối với socket kế tiếp mà Component của nó thỏa mãn, hoặc ở lại trong flow và được báo cáo. Một nút MCP Tools không nêu tên server nào sẽ không được nối với socket nào và được báo cáo. Một nút có cấu hình server tự khởi chạy một server riêng cũng vậy — nó mang mộtcommand, hoặc đặt chế độStdio— và báo cáo của nó cho biết cần xóa gì, vì quá trình build của nền tảng dừng lại khi gặp một nút nêu tên một server mà không kết nối tools nào đáp ứng. - Một MCP server được nối theo tên mà flow đặt cho nó. Các nút của một flow nêu tên cùng một server sẽ tiếp cận một phần, được soạn thảo một lần, thông qua một kết nối. Alias của kết nối là tên của server khi alias của một kết nối có thể nhận tên đó — chữ cái, chữ số, dấu gạch ngang và dấu gạch dưới — và không kết nối nào khác của socket đó cung cấp dưới cùng tên biến, tức alias được viết hoa với mọi ký tự khác được viết thành dấu gạch dưới. Nếu không, kết nối nhận một alias suy ra từ khóa của phần, server của nút được đổi tên thành alias đó trong flow mà bản nháp mang theo, và quyết định của phần nói rõ điều này.
Quyết định của một phần được nối cho biết nó được nối với socket nào của nền tảng và qua kết nối nào, đồng thời nêu tên mỗi socket mà nó đã bị bỏ qua và lý do.
Cách flow được mang theo tiếp cận từng phần
Ở nơi định dạng cho phép, luồng mà nền tảng mang theo sẽ tiếp cận từng phần đã nối dây qua kết nối của phần đó, và bản nháp ghi vào luồng những gì giúp nó làm được như vậy — tên của một biến, một địa chỉ được làm trống, hoặc những gì nút sẽ gửi thay cho những gì kết nối cung cấp, được làm trống, và không bao giờ là một giá trị. Đây là việc nối dây, không phải việc xóa một giá trị thông tin xác thực: bản nháp ghi nó bất kể thiết lập empty_credentials nói gì, vì một giá trị được giữ lại ở đó sẽ ghi đè những gì kết nối cung cấp.
-
Một nút MCP Tools của Langflow. Nền tảng ghi địa chỉ mà kết nối của nút cung cấp vào cấu hình máy chủ của nút và, ở nơi kết nối mang một thông tin xác thực, ghi tên của biến chứa thông tin đó dưới header mà công cụ công bố. Bản nháp ghi trống địa chỉ mà bản xuất đã giữ ở đó, để luồng không giữ bản sao nào của nó, và để lại địa chỉ của máy chủ —
infra.endpointcủa phần — cho Release. Langflow gửi trườngheadersriêng của nút đè lên các header trong cấu hình máy chủ của nút, nên bản nháp ghi trống toàn bộ giá trị của trường đó và giữ nguyên kiểu của nó — một object thành{}, một list thành[], văn bản thành một chuỗi rỗng — vì một header được giữ lại với giá trị bị làm trống vẫn sẽ được gửi, trong khi một object hoặc list rỗng không ghi đè gì cả. -
Một nút mô hình hoặc kho vector của Langflow. Nền tảng cung cấp một kết nối mô hình dưới dạng
OPENAI_BASE_URLvàOPENAI_API_KEY, và một kết nối kho vector dưới dạng các biến được đặt tên theo alias của nó, mà Langflow đọc qua một trường đặt tên một biến toàn cục: một trường có object mangload_from_db: truegiữ tên của biến làm giá trị của nó, và Langflow đọc biến toàn cục có tên đó, hoặc biến môi trường có tên đó ở nơi không có biến toàn cục nào được lưu. Bản nháp ghi mỗi trường sau với tên của biến vàload_from_db: true:openai_api_basecủa một nútOpenAIModel, thànhOPENAI_BASE_URL, vàapi_keycủa nó, thànhOPENAI_API_KEY;openai_api_basecủa một nútOpenAIEmbeddings, thànhOPENAI_BASE_URL, vàopenai_api_keycủa nó, thànhOPENAI_API_KEY;api_keycủa một nútLanguageModelComponent, thànhOPENAI_API_KEY;api_basecủa một nútEmbeddingModel, thànhOPENAI_BASE_URL, vàapi_keycủa nó, thànhOPENAI_API_KEY;pg_server_urlcủa một nútpgvector, thànhAGGREGA_VECTOR_STORE_<ALIAS>_CONNECTION_STRING, trong đó<ALIAS>là alias của kết nối viết hoa, với mọi ký tự không phải chữ cái hay chữ số được viết thành dấu gạch dưới.
Một nút
LanguageModelComponenthoặcEmbeddingModelchạy trên một trong nhiều nhà cung cấp mô hình — nhà cung cấp mà trườngprovidercủa nút đặt tên, hoặc, ở nơi trường đó trống, nhà cung cấp của mô hình mà trườngmodelchọn — và trao khóa của nút cho nhà cung cấp đó. Nền tảng cung cấp kết nối mô hình cho một client tương thích OpenAI, nên một nút như vậy chỉ được ghi với các biến ở nơi nó chạy trênOpenAI. Một nút chạy trên nhà cung cấp khác không bao giờ được nối, như đã nói ở trên; một nút không chọn nhà cung cấp nào, đặt tên nhà cung cấp qua một biến toàn cục, hoặc lấy mô hình từ một nút khác sẽ được ghi mà không có biến nào, để bản nháp không bao giờ trỏ một nhà cung cấp khác tới khóa của kết nối. Ở nơi không trường nào của một nút như vậy cho biết địa chỉ API của nó — một nútLanguageModelComponentkhông giữ trường nào cho OpenAI, vàapi_basecủa một nútEmbeddingModelcó thể thiếu, hoặc trống ở nơi nó không thể đặt tên một biến — client OpenAI mà nút chạy lấyOPENAI_BASE_URLtừ môi trường, nên nút vẫn tiếp cận được địa chỉ mà nền tảng cung cấp.Client của một nút
OpenAIEmbeddingsgửidefault_headerscủa nó đè lên các header mà nó tạo từ khóa, và hợp nhấtdefault_querycủa nó đè lên query của địa chỉ nó gọi, nên trên một nút như vậy mà bản nháp nối dây, toàn bộ giá trị của mỗi trường được ghi trống với kiểu được giữ nguyên, nhưheaderscủa một nút MCP Tools.Một trường mà bản xuất ghi mà không có cả hai thành phần đó sẽ không được ghi lại — một trường thông tin xác thực trong số đó được mang theo như đã ghi, hoặc được ghi trống ở nơi thiết lập yêu cầu, như bên dưới. Ở nơi trường đó là trường mang địa chỉ của phần — và, với một nút
LanguageModelComponenthoặcEmbeddingModel, cho ra một địa chỉ — ở nơi một nút như vậy không chạy trênOpenAI, hoặc ở nơi nút thuộc bất kỳ kiểu nào khác, quá trình nhập báo cáo phần đó là được tiếp cận tại địa chỉ mà luồng hoặc các giá trị mặc định của thành phần của nó cho ra. -
Một nút OpenAI của Flowise. Client OpenAI mà Flowise dùng để chạy một nút
chatOpenAIhoặcopenAIEmbeddingsđọcOPENAI_BASE_URLvàOPENAI_API_KEYtừ môi trường ở nơi Base Path của nút trống và nút không chọn thông tin xác thực nào, nên bản nháp ghi trống Base Path mà bản xuất giữ, và thông tin xác thực mà nút chọn, tạidata.credential, cũng được ghi trống. Client đó gửi các header mặc định của nút,baseOptionscủa nó, đè lên header mà nó tạo từ khóa, nên bản nháp ghi trống toàn bộ giá trị của chúng với kiểu được giữ nguyên. Một nút mô hình thuộc bất kỳ kiểu nào khác được báo cáo là được tiếp cận tại địa chỉ mà chatflow hoặc các giá trị mặc định của chính nút cho ra. -
Một công cụ hoặc kho vector của Flowise. Một chatflow đọc địa chỉ mà nền tảng cung cấp cho chúng —
AGGREGA_TOOL_<ALIAS>_URLhoặcAGGREGA_VECTOR_STORE_<ALIAS>_URL— chỉ qua một biến Runtime có tên đó, mà không gì tạo ra khi khởi động. Bản nháp không ghi gì cho nó, và quá trình nhập báo cáo bước khiến chatflow đọc nó: tạo biến Runtime trên trang Variables của Flowise, và đọc nó trong nút dưới dạng$vars.<name>. -
Bất kỳ nút n8n nào. Nền tảng cung cấp một kết nối mô hình dưới dạng
OPENAI_BASE_URLvàOPENAI_API_KEY, và một kết nối công cụ hoặc kho vector dưới dạngAGGREGA_TOOL_<ALIAS>_URLhoặcAGGREGA_VECTOR_STORE_<ALIAS>_URL, trong khi một nút n8n tiếp cận một mô hình, một kho hoặc một dịch vụ tại địa chỉ mà thông tin xác thực đã lưu mà nút chọn cho ra, hoặc địa chỉ mà các tham số của chính nút giữ, và một workflow chỉ đọc một biến môi trường qua một biểu thức đọc$env, điều mà nền tảng từ chối trừ khi Aggregate đặtvalues.allow_env_access_in_nodesthànhtrue. Bản nháp để giá trị đó ở mặc định,false, vì việc đặt nó cho phép mọi workflow, và mọi người dùng có thể chỉnh sửa một workflow, đọc mọi biến trong môi trường của nền tảng, kể cả các thông tin xác thực được cung cấp. Vì vậy bản nháp không ghi gì vào workflow cho một kết nối, và mọi phần đã nối dây được báo cáo là được tiếp cận không qua kết nối. Một nút MCP client tiếp cận máy chủ của nó tại địa chỉ mà workflow giữ — như bản xuất đã ghi, hoặc không có địa chỉ nào ở nơi thiết lậpempty_credentialsghi trống nó, như bên dưới — và địa chỉ riêng của máy chủ —infra.endpointcủa phần — được để lại cho Release.
Ở nơi luồng được mang theo, mỗi phần đã nối dây được báo cáo với trường hợp nào trong số sau đúng:
part-reads-connection ở nơi luồng tiếp cận phần qua kết nối của phần đó, và
part-address-in-flow ở nơi luồng tiếp cận phần không qua kết nối của nó — tại một địa chỉ
mà luồng giữ, hoặc một địa chỉ mà các giá trị mặc định của thành phần của nó cho ra. Quyết định của phần cũng nói như vậy.
Một nút mà bản nháp không nối dây tới socket nào vẫn có thể được tiếp cận bởi một kết nối mà bản nháp có nối dây, tùy theo cách nút
được ghi: một client OpenAI không có địa chỉ và không có khóa riêng sẽ đọc OPENAI_BASE_URL và
OPENAI_API_KEY mà nền tảng cung cấp cho kết nối mô hình từ môi trường của nó. Ở nơi một nút làm vậy,
bản nháp ghi nút như với một nút đã nối dây, để không gì nút giữ được gửi thay cho những gì
kết nối cung cấp, và báo cáo nó với part-reads-connection:
- một nút
OpenAIEmbeddingscủa Langflow có trường địa chỉ đặt tên biếnOPENAI_BASE_URLmà nền tảng cung cấp, được đọc như một biến toàn cục, trong khi một phần được nối dây tới socket mô hình:default_headersvàdefault_querycủa nó; - một nút
chatOpenAIhoặcopenAIEmbeddingscủa Flowise có Base Path trống và không chọn thông tin xác thực nào, và cấu hình của một mô hình như vậy mà một nút agentflow giữ trong các input của nó, trong khi một phần được nối dây tới socket mô hình:baseOptionscủa nó.
Trên mọi nút khác, các giá trị này không phải là việc nối dây: chúng được mang theo như đã viết, hoặc được ghi rỗng khi thiết lập yêu cầu, như phần tiếp theo mô tả.
Các giá trị thông tin xác thực mà luồng chứa
Trước khi luồng được mang theo, quá trình nhập xác định mọi giá trị trong luồng có thể mang thông tin xác thực, tại các vị trí liệt kê dưới đây, mỗi giá trị thuộc một trong ba loại: những gì một định dạng đánh dấu là thông tin xác thực; một thành phần trong cấu hình của máy chủ MCP, ở bất cứ đâu định dạng lưu cấu hình đó; và một đầu vào mà định dạng đánh dấu là không phải thông tin xác thực nhưng vẫn có thể mang thông tin xác thực — header của yêu cầu, tham số truy vấn, toàn bộ một yêu cầu viết dưới dạng dòng lệnh, một đầu vào chứa thông tin xác thực dưới tên của một thông tin xác thực.
Theo mặc định, quá trình nhập không ghi rỗng giá trị nào trong số đó: luồng được mang theo đúng như khi được xuất, và mỗi giá trị đã xác định có chứa nội dung — không phải chuỗi rỗng và không phải null — được nêu trong một cảnh báo credential-carried, theo nút và trường của nó — một header hoặc một tham số truy vấn theo tên của nó — không bao giờ theo giá trị hay bất kỳ phần nào của giá trị, cùng với giá trị của thiết lập empty_credentials sẽ ghi rỗng nó. Thiết lập này bật việc loại bỏ: marked ghi rỗng những gì một định dạng đánh dấu là thông tin xác thực và mọi thành phần trong cấu hình của máy chủ MCP; all ghi rỗng cả các đầu vào được đánh dấu là không phải thông tin xác thực. Mỗi giá trị mà thiết lập ghi rỗng được báo cáo bằng credential-emptied, theo nút và trường của nó, không bao giờ theo giá trị; một giá trị vốn đã rỗng, hoặc là null, được giữ nguyên và không được báo cáo. Một giá trị mà thiết lập không chấp nhận sẽ dừng quá trình nhập, không tạo bản nháp nào, thay vì được hiểu là none.
Một giá trị đã xác định chỉ gồm một tham chiếu biến và không có gì khác thì không chứa giá trị riêng: tên trần của một biến, ${NAME} — kể cả một biến định sẵn như ${workspaceFolder} hoặc ${userHome} — hoặc một trong các dạng mà các MCP client định nghĩa, ${env:NAME} và ${input:id}. Dù thiết lập nói gì, nó vẫn được mang theo như đã viết và không được nêu trong cảnh báo nào, bất kể luồng ở định dạng nào, như cách MCP importer viết. Cũng vậy với một thành phần chỉ là một tham chiếu nằm trong một giá trị mà định dạng lưu dưới dạng văn bản, chẳng hạn một mcpServerConfig của Flowise viết dưới dạng văn bản JSON, hoặc header và tham số truy vấn được lưu dưới dạng đối tượng JSON trong văn bản trên Flowise và n8n: khi ghi rỗng, văn bản giữ thành phần đó như đã viết.
Một tham chiếu mang văn bản sau một toán tử thì chứa văn bản đó, vốn có thể là một khóa, dù có hay không có dấu hai chấm đứng trước toán tử: một giá trị mặc định, ${NAME:-value} hoặc ${NAME-value}; một giá trị thay thế, ${NAME:+value} hoặc ${NAME+value}; một thông báo, ${NAME:?message} hoặc ${NAME?message}; một phép gán, ${NAME:=value} hoặc ${NAME=value}. Nó được xác định như mọi giá trị khác — theo mặc định được mang theo và nêu trong một cảnh báo credential-carried, được ghi rỗng khi thiết lập yêu cầu cho loại của nó — và cũng vậy với mọi văn bản khác bên trong ${…}, chẳng hạn ${config:name}, và văn bản đứng cạnh một tham chiếu, chẳng hạn --key=${NAME}.
Những gì bản nháp ghi để một nút tiếp cận kết nối của nó — một địa chỉ được ghi rỗng, tên của một biến, một thông tin xác thực được chọn hoặc các header mặc định được ghi rỗng, như Cách luồng được mang theo tiếp cận từng phần mô tả — là việc nối dây: nó được ghi bất kể thiết lập nói gì, được báo cáo cùng với cách nút tiếp cận kết nối của nó, và không bao giờ được báo cáo như một giá trị thông tin xác thực. Những gì nằm ngoài mọi vị trí dưới đây thuộc về tác giả xem xét, như phần cuối của mục này nói.
Những gì một định dạng đánh dấu là thông tin xác thực — được ghi rỗng với marked và all:
- Langflow — giá trị của mỗi trường mẫu được đánh dấu
password: true, kể cả một trường chứa tên của một biến toàn cục, trừ khi bản nháp ghi trường đó bằng tên của biến mà nền tảng cung cấp, như ở trên. - Flowise — thông tin xác thực mà một nút lưu tại
data.credential, do tham số thông tin xác thực của nút chọn; giá trị của mỗi đầu vào màinputParamscủa nút khai báo có kiểupassword; vàFLOWISE_CREDENTIAL_IDtrong các đầu vào của một nút, cùngcredentialhoặcFLOWISE_CREDENTIAL_IDbên trong một đối tượng cấu hình ở bất kỳ độ sâu nào của chúng, như cách một agentflow lưu cấu hình của một mô hình hay một công cụ. - n8n —
idcủa mỗi thông tin xác thực đã lưu mà một nút chọn, tạicredentials.<type>.id. Một bản xuất n8n lưu thông tin xác thực dưới dạng tham chiếu, không bao giờ lưu giá trị của nó, vànamecủa tham chiếu không được xác định: khi nhập workflow trên một phiên bản khác, n8n phân giải một thông tin xác thực cóidmà nó không có bằng loại và tên của thông tin đó. Một thông tin xác thực mà bản xuất cũ hơn chọn chỉ bằng tên thì chỉ nêu tên một thông tin xác thực và không chứa thông tin nào, nên không được xác định. Ngoài ra còn có giá trị của mỗi tham số mà n8n đánh dấu là mật khẩu trong định nghĩa các nút cơ sở của nó — chẳng hạnsecretcủa nút Crypto, hoặcpasswordcủa các nút tạo người dùng — ở bất cứ đâu trong các tham số của nút, với một nút được dùng làm công cụ của agent được đọc như chính nút đó.
Cấu hình của máy chủ MCP — được ghi rỗng với marked và all:
- Cấu hình
mcp_servercủa một nút MCP Tools trên Langflow, vàmcpServerConfigcủa một nút Flowise, viết dưới dạng văn bản JSON hoặc đối tượng: mỗi giá trị header, dù các header là một đối tượng, các hàng gồm khóa và giá trị hay các đối tượng được hợp nhất nguyên vẹn, với một mục thuộc loại khác được xác định nguyên vẹn; mỗi giá trị môi trường; địa chỉ của máy chủ; lệnh; và mọi đối số. Không định dạng nào đánh dấu địa chỉ, lệnh hay đối số là thông tin xác thực, và mỗi thứ đều có thể mang một khóa — một địa chỉ trong phần người dùng, đường dẫn hoặc truy vấn của nó — nên cả ba cũng được xác định, trên cả hai định dạng. Khi ghi rỗng, lệnh và mỗi đối số giữ các thành phần của chúng, để một cấu hình tự khởi động máy chủ vẫn được hiểu như vậy. Khi một nút MCP Tools trên Langflow được nối với một kết nối công cụ, địa chỉ của nó là việc nối dây, như ở trên, và không bao giờ được báo cáo như một giá trị thông tin xác thực. Một cấu hình Flowise viết dưới dạng văn bản mà không đọc được như một đối tượng JSON thì được xác định nguyên vẹn, vì không có gì bên trong nó có thể được xác định. - Một nút MCP Tools trên Langflow không mang trường
mcp_serverthì lưu máy chủ của nó trong các trường riêng — địa chỉ trongsse_url, các header trongheaders_input, môi trường trongenv, và toàn bộ dòng lệnh, kể cả các đối số, trongcommand— và Langflow cũng không đánh dấu trường nào trong số đó là thông tin xác thực, nên mỗi giá trị header, mỗi mục củaenv, địa chỉ và dòng lệnh đều được xác định, với các trường và mục của chúng được giữ lại khi ghi rỗng. Khienvlà một danh sách, mỗi mục được báo cáo theo vị trí của nó, vì tên biến và giá trị của biến nằm chung một văn bản. Một nút như vậy không nêu tên máy chủ MCP nào, nên không bao giờ được nối với một kết nối công cụ. - Trường
headersriêng của một nút MCP Tools trên Langflow, mà Langflow gửi đến máy chủ đè lên các header trong cấu hình của nó, trên một nút mà bản nháp không nối dây: toàn bộ giá trị của nó, được ghi rỗng với loại được giữ nguyên, như trên một nút đã nối dây, và được báo cáo một lần, dưới tênheaders. - Các thành phần MCP Tools (SSE) và MCP Tools (stdio) của Langflow, mà Langflow đánh dấu là không còn được khuyến khích dùng, mỗi thành phần lưu máy chủ trong một trường — một nút
MCPSselưu địa chỉ trongurl, một nútMCPStdiolưu toàn bộ dòng lệnh, kể cả các đối số, trongcommand— được xác định nguyên vẹn. Không thành phần nào nêu tên một máy chủ MCP, nên không thành phần nào được nối với một kết nối công cụ. - Một nút MCP client của n8n — MCP Client Tool mà một agent gọi, nút MCP Client, hoặc một client của máy chủ mà registry của n8n liệt kê — lưu địa chỉ của máy chủ trong tham số
endpointUrl, hoặcsseEndpointở phiên bản đầu tiên, và chỉ lưu các header dưới dạng thông tin xác thực mà nó chọn; địa chỉ được xác định nguyên vẹn, dù có được nối dây hay không.
Một đầu vào mà định dạng đánh dấu là không phải thông tin xác thực — chỉ được ghi rỗng với all:
- Header của yêu cầu — trên Langflow,
headerscủa một nodeAPIRequest,URLComponent,CloudflareWorkersAIEmbeddingshoặcConfluentKafkaProducervàapi_headerscủa một nodeDoclingRemote; trên Flowise,headerscủa một nodehttpAgentflow,getApiChain,postApiChain,openApiChain,apiLoader,openAPIToolkithoặcsearXNG, cácrequestsGetHeaders,requestsPostHeaders,requestsPutHeadersvàrequestsDeleteHeaderscủa các công cụ Requests, vàbaseOptions— các header mặc định mà client của một mô hình gửi — của một nodeazureChatOpenAI,azureOpenAIEmbeddings,chatCerebras,chatOpenAICustom,openAIEmbeddingsCustom,chatOpenRouter,chatSambanovahoặcopenAI; trên n8n, cácheaderParameters,jsonHeaders,headerParametersUivàheaderParametersJsoncủa một noden8n-nodes-base.httpRequest— phiên bản hiện tại giữ hai cái đầu, các phiên bản trước giữ hai cái sau — và của cùng node đó khi được dùng làm công cụ của một agent,parametersHeadersvàjsonHeaderscủa một node@n8n/n8n-nodes-langchain.toolHttpRequest, vàheaderParametersUicủa một noden8n-nodes-base.graphql. Tên của một header không mang bí mật, nên giá trị của mỗi header được định vị và tên của nó được giữ lại, bất kể các header có dạng nào: một object ánh xạ tên sang giá trị, các hàng gồm một khóa và một giá trị — trên n8n, các hàng gồm mộtnamevà mộtvalue— hoặc các object mà Langflow gộp nguyên vào các header. Mỗi header được báo cáo theo tên của nó. Một phần tử của danh sách không phải là hàng header được định vị nguyên khối và báo cáo theo vị trí của nó. Các header được viết dưới dạng văn bản được định vị nguyên khối, trừ trên Flowise và n8n, nơi văn bản chứa các header dưới dạng một object JSON: ở đó, khi được ghi rỗng, văn bản được viết lại tại chỗ, mỗi giá trị rỗng, và được báo cáo một lần cùng tên các header mà nó chứa. Văn bản n8n bắt đầu bằng=là một biểu thức mà n8n đánh giá khi workflow chạy, và được định vị nguyên khối. Khi ghi rỗng, mọi giá trị đều bị ghi rỗng, kể cả giá trị của các header không chứa bí mật nhưUser-Agent, nên một yêu cầu được nhập sẽ được gửi với các giá trị đó rỗng cho đến khi tác giả của nó khôi phục chúng. - Tham số truy vấn — trên Langflow,
query_paramscủa một nodeAPIRequesthoặcGoogleSerperAPIvàsearch_paramscủa một nodeSerpAPI,Serp,SearchAPIhoặcSearchComponent; trên Flowise,queryParamscủa một nodehttpAgentflowvàcustomParameterscủa một loadersearchApi; trên n8n, cácqueryParameters,jsonQuery,queryParametersUivàqueryParametersJsoncủa một noden8n-nodes-base.httpRequest, dù được dùng làm công cụ hay không,parametersQueryvàjsonQuerycủa một node@n8n/n8n-nodes-langchain.toolHttpRequest, vàqueryParametersvàqueryParametersJsonmà một noden8n-nodes-base.facebookGraphApigiữ trongoptionscủa nó. Mỗi cái được gửi làm truy vấn của một yêu cầu, và một tham số truy vấn có thể mang một khóa — một số API tìm kiếm nhận khóa của chúng dưới dạngapi_keytrong truy vấn — nên mỗi cái được định vị như các header: từng giá trị, giữ lại tên, bất kể các tham số có dạng nào, và mỗi cái được báo cáo theo tên; các tham số được viết dưới dạng văn bản được định vị nguyên khối, trừ trên Flowise và n8n, nơi văn bản chứa chúng dưới dạng một object JSON, mà khi được ghi rỗng sẽ được viết lại tại chỗ và báo cáo một lần cùng các tên mà nó chứa. Khi ghi rỗng, mọi giá trị đều bị ghi rỗng, kể cả giá trị của các tham số không chứa bí mật, nên một yêu cầu được nhập sẽ được gửi với chúng rỗng — hoặc, từ một node HTTP của Flowise, vốn không gửi tham số nào có giá trị rỗng, sẽ được gửi không có chúng — cho đến khi tác giả của nó khôi phục chúng. - Header mặc định và truy vấn mặc định trên một node OpenAI mà không kết nối nào tới —
default_headersvàdefault_querycủa một node LangflowOpenAIEmbeddings, vàbaseOptionscủa một node FlowisechatOpenAIhoặcopenAIEmbeddings, bất kể node nằm ở đâu, kể cả cấu hình của một agentflow cho mô hình mà nó chọn, nơi bản nháp vừa không nối dây node vừa không tìm thấy kết nối nào tới nó như nó được viết; nơi có, chúng là phần nối dây, như trên. Mỗi cái được định vị nguyên khối và, khi được ghi rỗng, giữ nguyên loại của nó — một object thành{}, một danh sách thành[], văn bản thành chuỗi rỗng — và được báo cáo một lần. - Toàn bộ một yêu cầu được viết dưới dạng dòng lệnh —
curl_inputcủa một node LangflowAPIRequestvàcurlcủa một nodeWebhook, được định vị nguyên khối, kể cả giá trị mặc định của Webhook. Không cái nào được đọc khi flow chạy: cái đầu chỉ điền các trường của node trong trình soạn thảo, cái thứ hai hiển thị một ví dụ. - Một đầu vào chứa thông tin xác thực dưới tên của một thông tin xác thực —
api_keycủa một node LangflowOlivyaComponent,verification_tokencủa mọi component Composio, vàmem0_configcủa một nodemem0_chat_memory, mà toàn bộ giá trị giữ nguyên loại khi được ghi rỗng; vàwebhookSecretvàcallbackSecretcủa một node FlowisestartAgentflowvàbearerTokencủa một nodeteradataMCP. Mỗi cái được định vị nguyên khối. Một đầu vào mà tên chỉ giống một thông tin xác thực — tên của một khóa được lưu ở nơi khác, một tên người dùng, hoặc một tùy chọn mà component khai báo là không bí mật — không được định vị.
Ngoài các giá trị mà thiết lập ghi rỗng, những gì bản nháp viết để flow tới được các phần của nó, các handle của một cạnh Langflow, được viết như trình soạn thảo Langflow viết chúng, và các ký tự carriage return được viết thành line feed bên dưới, flow được mang theo đúng như khi được xuất: không có những điều này thì nguyên từng byte.
Một kết nối trong bản nháp không mang giá trị thông tin xác thực nào: Release bản nháp gắn theo tham chiếu thông tin xác thực mà mỗi kết nối xuất trình, như Những gì bản nháp để lại cho Release mô tả.
Mọi giá trị mà thiết lập để nguyên đều đi vào bản nháp, và tác giả xem xét nó, dựa vào các cảnh báo
credential-carried. Không quy tắc nào về một trường áp dụng cho phần còn lại của flow, nên tác giả
cũng xem xét phần đó trước khi chia sẻ bản nháp: mã riêng của một component, mà flow mang theo và trong đó một
component tùy chỉnh có thể chứa một khóa; các đầu vào mà trình soạn thảo thêm vào một node ngoài những đầu vào component của nó
khai báo; phần thân mà một yêu cầu được gửi kèm, chẳng hạn của một node APIRequest hoặc httpAgentflow, vốn
có thể mang một token; các đối số mà một node trao cho client của mô hình hoặc một loader dưới dạng một object riêng,
chẳng hạn model_kwargs của một node Langflow EmbeddingModel hoặc additionalInputs của một node Flowise replicate,
vốn có thể mang một khóa dưới bất kỳ tên nào; một địa chỉ không phải của một MCP server,
vốn có thể mang một khóa trong phần người dùng hoặc truy vấn của nó; mã của một node Code của n8n, và các header hoặc
truy vấn của một node gửi yêu cầu mà importer không liệt kê ở trên; và văn bản tự do như một
prompt hoặc một tin nhắn.
Những gì bản nháp để lại cho Release
Release bản nháp mang, trên mục của nền tảng và trên mục của mỗi phần, những gì flow không thể cung cấp:
- Image của nền tảng, dưới dạng
infra.image: image do chính trình nhập chọn, ở phiên bản mà các Recipes của danh mục cho nền tảng đó được biết là chạy được —langflowai/langflow:1.6.0,flowiseai/flowise:3.1.3vàn8nio/n8n:1.110.1— dưới một chú thích nói rõ điều đó. Lần nhập không bao giờ nâng hay hạ phiên bản này để theo nguồn; khi bản xuất ghi một phiên bản nền tảng khác, nhưlast_tested_versioncủa một flow Langflow, chú thích sẽ nêu phiên bản đó. - Cổng mà nền tảng được công bố trên đó, dưới dạng
infra.published_port, chỉ với--target compose: 7860 cho Langflow, 3000 cho Flowise và 5678 cho n8n, các cổng mà mỗi nền tảng phục vụ, được Recipe Compose của nó công bố trên địa chỉ loopback của máy chủ, 127.0.0.1. Chú thích phía trên nói rằng cổng chỉ truy cập được từ máy này, bởi bất kỳ tiến trình nào chạy trên đó, và việc xóa dòng này giữ dịch vụ ở dạng nội bộ. Flow thứ hai của một lần nhập lấy cổng kế tiếp mà không flow nào trước đó lấy. Với bất kỳ đích nào khác, hoặc không có đích, giá trị này không được ghi. - Bí mật riêng của nền tảng và thông tin xác thực của mỗi kết nối mô hình, được gắn theo tham chiếu và không bao giờ dưới dạng giá trị: trên Langflow là slot
admin_password, được đọc khivalues.require_authenticationvẫn làtrue; trên Flowise là slotowner_password, bắt buộc khivalues.flow_definitionđược đặt; và, khi một phần được nối vào socketmodelcủa nền tảng, làcredentialtrên kết nối đó. Nền tảng n8n không nhận bí mật riêng nào. Cách gắn từng mục phụ thuộc vào đích, như Bí mật, cho từng đích mô tả. - Mỗi giá trị mà không nguồn nào chứa, được ghi thành chuỗi rỗng dưới một chú thích nói nó là gì: trên Flowise là
infra.owner_email, email của tài khoản chủ sở hữu, bắt buộc khivalues.flow_definitionđược đặt; và địa chỉ của mỗi máy chủ MCP được nối vào nền tảng, tứcinfra.endpointcủa phần tương ứng. Mỗi giá trị là một giá trị mà lần nhập còn thiếu, được trả lời như Tệp câu trả lời của lần nhập mô tả.
Thông tin xác thực mà một kết nối tới một công cụ hoặc một kho vector xuất trình không được soạn vào bản nháp: thông tin xác thực của kết nối như vậy sẽ dừng bản build ở nơi công cụ không công bố header nào để gửi nó, vì vậy một chú thích phía trên mục của nền tảng nêu tên nó, để bạn gắn vào nơi công cụ chấp nhận.
Secret, cho từng target
Trên --target helm, mỗi secret là một core/referenced-secret có origin là tên của một Kubernetes Secret đã có sẵn trong namespace, giữ giá trị dưới khóa dữ liệu value. Không nguồn nào cung cấp được tên đó, nên nó được ghi rỗng dưới một chú thích cho biết nó giữ gì, và thuộc các giá trị mà lần nhập còn nợ; Manifest được soạn nháp ánh xạ core/referenced-secret tới helm/k8s-existing-secret.
Trên mọi target khác, và khi không có target, mỗi secret là một core/secret-value có origin là một tham chiếu tới một biến — ${LANGFLOW_ADMIN_PASSWORD}, ${FLOWISE_OWNER_PASSWORD}, và ${OPENAI_API_KEY} cho thông tin xác thực của một kết nối mô hình — mà một target thay thế tham chiếu biến, như Docker Compose làm khi stack khởi động, đọc từ môi trường, nên không tệp nào chứa giá trị và không có gì phải nợ cho nó. Chatflow Flowise ở trên, khi được nhập mà không có target, được soạn nháp với Release này:
apiVersion: aggrega.ai/v1beta1kind: Releasemetadata: name: imported/multiple-documents-qna # environment is a drafted default, since no source names the environment this Release deploys to; change it to name the one it deploys to. environment: development version: 0.1.0 description: Draft Release imported from a source in the flowise format.spec: aggregate: imported/multiple-documents-qna # manifest: left empty, since the import was given no target; an import given a target drafts the Manifest and names it here. manifest: "" components: flowise: infra: # The image running core/ai-agent/flowise, at the version this importer drafts, which the catalog's Recipes for it are known to run; the import does not raise or lower it to follow the source. image: "flowiseai/flowise:3.1.3" # Left for the Release, since the source cannot supply it: infra.owner_email, the email address of the platform's owner account, required while values.flow_definition is set owner_email: "" features: owner_password: type: core/secret-value infra: # Attached by reference, never as a value: the owner account's password, required while values.flow_definition is set, read from the variable FLOWISE_OWNER_PASSWORD, which a target substituting variable references, as Docker Compose does when the stack starts, reads from the environment, so no file carries the value. origin: "${FLOWISE_OWNER_PASSWORD}" uses: model: chatopenai-0: features: credential: type: core/secret-value infra: # Attached by reference, never as a value: the credential flowise presents to chatopenai-0 on its model connection, read from the variable OPENAI_API_KEY, which a target substituting variable references, as Docker Compose does when the stack starts, reads from the environment, so no file carries the value. origin: "${OPENAI_API_KEY}" chatopenai-0: {}Khi không có target, lần nhập nợ hai giá trị, spec.manifest và infra.owner_email; với --target compose, chỉ email của chủ sở hữu; với --target helm, email của chủ sở hữu và tên của hai Kubernetes Secret.
Trên target compose, một secret mà chỉ Release gắn sẽ đến dưới một khóa duy nhất, value, nên mật khẩu của chủ sở hữu hoặc của quản trị viên và thông tin xác thực của một kết nối đều sẽ đến dưới khóa đó. Vì vậy Aggregate khai báo mỗi cái với một khóa riêng ở nơi nền tảng tạo một kết nối: owner_password với khóa OWNER_PASSWORD trên Flowise, admin_password với khóa LANGFLOW_SUPERUSER_PASSWORD trên Langflow, và credential của kết nối mô hình với khóa OPENAI_API_KEY trên cả ba nền tảng, mỗi cái dưới một chú thích giải thích lý do. Với --target compose, các dòng này được ghi ở trạng thái hoạt động; khi không có target, chúng được ghi ở dạng comment, như trong ví dụ ở trên, để bạn bỏ comment nếu build cho compose; với bất kỳ target nào khác, chúng không được ghi. Release gắn origin của mỗi slot, nêu cùng một kiểu hoặc không nêu kiểu nào.
Khi thiết lập attach_egress_allowlist là true, instance của nền tảng còn khai báo Feature core/egress-allowlist của thư viện chuẩn dưới features, với tên egress-allowlist, để nền tảng chỉ kết nối tới các thành phần mà các kết nối của nó tới, các pod của chính nó và DNS của cluster — phần tương ứng chiều ra của một cạnh uses như một lời gọi được khai báo. Aggregate chỉ khai báo kiểu của phần gắn kèm và không gì khác, vì phần gắn kèm của một Aggregate không mang infra, và Release được soạn nháp không ghi gì trong số đó: chú thích phía trên mục nền tảng nêu, dưới features.egress-allowlist.infra, control_plane_present, mà người vận hành đặt thành true để khẳng định rằng network plugin của cluster thực thi network policy, thiếu điều đó thì bản build dừng lại; admitted_destinations, một danh sách chứa, cho mỗi kết nối có đích mà cluster không chạy, chẳng hạn một mô hình được lưu trữ bên ngoài, một mục nêu đích và một dải địa chỉ, thiếu nó thì bản build dừng lại và nêu tên kết nối đó; và aggrega.ai/namespace cho ranh giới chứa nền tảng, vì policy được đặt trong namespace của các khối lượng công việc của nó và bản build dừng lại nếu chúng không được xuất vào namespace nào. Không khóa nào được ghi rỗng, nên không khóa nào thuộc các giá trị mà lần nhập còn nợ. Quyết định của mỗi phần được nối cho biết phần gắn kèm cho phép kết nối của nó, và việc nhập báo cáo phần gắn kèm là feature-attached. Compose không có network policy, nên một bản build compose của bản nháp như vậy dừng lại và nêu tên phần gắn kèm; nơi nền tảng tạo một kết nối, các dòng compose ở trên được ghi bên trong khối features của instance, không có khóa features thứ hai.
Mô hình mà một phần phục vụ
Một phần mà bản nháp tham chiếu, có Component khai báo một giá trị tên model — như mỗi Component mô hình
của thư viện chuẩn khai báo, và yêu cầu — được viết với tên của mô hình mà node của nó chọn,
là values.model:
- Langflow —
model_namecủa một nodeOpenAIModelhoặcAnthropicModel;modelcủa một nodeOpenAIEmbeddings; và giá trị ghi đèmodel_namecủa một nodeLanguageModelComponenthoặcEmbeddingModelnơi nó được đặt, còn nếu không thì là mô hình mà trườngmodelcủa nó chọn. - Flowise —
modelNamecủa một nodechatOpenAI,chatAnthropichoặcopenAIEmbeddings. - n8n — tham số
modelcủa một node chat, completion hoặc embeddings mà bảng của importer ánh xạ, hoặcmodelNamecủa nó trên các node Google Gemini và Vertex, được viết dưới dạng tên hoặc dạng giá trị của bộ chọn mà các node mới hơn của n8n lưu nó trong đó. n8n bỏ một tham số đặt ở giá trị mặc định ra khỏi bản export, nên một node giữ mô hình mặc định sẽ không nêu mô hình nào trong bản export.
Một Release không thể viết một giá trị. Vì vậy, nơi node không nêu mô hình nào mà bản nháp có thể viết — nó không chọn
mô hình nào, nêu mô hình qua một biến toàn cục hoặc một biểu thức chỉ được đọc khi flow chạy, lấy mô hình từ
một node khác nối với nó, hoặc thuộc một kiểu có trường mô hình mà importer không đọc — một
chú thích bên trong phần đó để lại values.model cho tác giả, và việc import báo cáo điều đó bằng
model-not-named. Một phần mà bản nháp tạo nháp được viết không có giá trị.
Cách flow được viết vào bản nháp
Flow được viết dưới dạng một khối literal YAML có chế độ chomping giữ lại các dấu xuống dòng ở cuối, để
values.flow_definition đọc lại đúng văn bản gốc của flow. Văn bản của một Aggregate được đọc như một
template, nên mỗi {{ mà flow chứa — một chatflow Flowise viết {{<node id>.data.instance}} cho
mỗi kết nối giữa hai node — được viết thành {{"{{"}}, mà phép nội suy chuyển lại thành
hai dấu ngoặc nhọn, như
Văn bản mang dấu ngoặc nhọn kép của chính nó
mô tả. Tên của một mô hình được viết theo cùng cách.
Một khối literal không thể mang mọi ký tự đúng như được viết:
- Một ký tự carriage return — thuộc một cặp CR LF, hoặc đứng riêng — được viết thành một line feed. Một tài liệu
JSON chỉ chứa ký tự này giữa các token của nó, nơi mọi khoảng trắng được đọc như nhau, nên nền tảng đọc
cùng một flow. Việc import báo cáo số lượng bằng
carriage-returns-rewritten. - Bất kỳ ký tự nào khác mà một khối literal không thể mang khiến flow không được mang theo: một
ký tự xuống dòng — U+0085, U+2028 hoặc U+2029; một ký tự điều khiển khác ngoài tab và line
feed — U+0000 đến U+001F, U+007F, và U+0080 đến U+009F; các noncharacter U+FFFE và U+FFFF; và một
byte không thuộc một chuỗi UTF-8. Khi đó
values.flow_definitionkhông được đặt, kèm một chú thích nói rõ điều này, phần còn lại được tạo nháp, và việc import báo cáodefinition-not-carriedcho mỗi loại ký tự, kèm số lượng mà flow chứa cùng dòng và cột của ký tự đầu tiên.
Flow cũng không được mang theo khi một giá trị mà bản nháp viết rỗng hoặc viết mới không nằm trong các byte
của bản export tại nơi cây đã phân tích của nó chứa giá trị đó, và việc import báo cáo definition-not-carried nêu
vị trí của giá trị đó. Khi đó định danh của flow là định danh của chính nó nếu bản nháp có thể mang nó, còn nếu không thì là một định danh
được suy ra từ định danh của các node trong flow.
Từng node một
Với layout: nodes, việc import tạo nháp mỗi node của flow thành một Component riêng, và viết:
aggregate.yaml— một Aggregate nháp được đặt tên theo flow, như Cách đặt tên cho bản nháp mô tả, kết hợp các node của flow: một mục cho mỗi node, và mỗi cạnh của flow là một kết nốiusescủa node mà nó cấp dữ liệu, với socket và alias của kết nối đều được đặt tên theo khóa của node cấp dữ liệu cho nó, nên một node được nhiều node cấp dữ liệu sẽ cho mỗi kết nối một alias riêng.- một tệp dưới
components/cho mỗi node được tạo nháp — một Component nháp tên<target_namespace>/<category>/<name>, tên lấy từ kiểu của node, ở phiên bản0.1.0, các trường giá trị của nó là các trường chuỗi của một đối tượngvaluesđóng và các trường thông tin xác thực của nó là các slot thông tin xác thực bắt buộc mà cách chuyển giao do một Recipe quyết định. release.yaml— một Release nháp cùng tên, nêu Aggregate đó, với một mục cho mỗi node.
Bản thân flow không được mang theo, và không giá trị của trường nào được đọc.
Mang theo chính luồng đã xuất
Bản nháp mặc định mang theo luồng: instance của nền tảng nhận bản xuất làm values.flow_definition, được viết như Cách luồng được viết vào bản nháp
mô tả. Một tác giả viết luồng vào một Aggregate bằng tay — vào một bản nháp được bố trí theo từng node, hoặc
vào một Aggregate của riêng mình — cũng viết theo cùng cách đó. Một Component chạy một luồng như khi được tạo ra
nhận bản xuất làm một giá trị — flow_definition trên core/ai-agent/langflow
và core/ai-agent/flowise của thư viện chuẩn — và văn bản của một Aggregate được đọc như một template, nên các dấu ngoặc nhọn kép mà
bản xuất chứa sẽ bị đọc thành các hành động template: một chatflow của Flowise viết {{<node id>.data.instance}}
cho mỗi kết nối giữa hai node, một prompt của Flowise đặt tên biến là {{question}}, và một
bản xuất Langflow mang theo mã nguồn của các component của nó, nơi các dấu ngoặc nhọn cũng có thể xuất hiện.
Hãy viết mỗi {{ trong bản xuất thành {{"{{"}}, bên trong một block scalar, và phép nội suy sẽ khôi phục
văn bản của bản xuất trước khi các Recipes của Component đọc nó;
Văn bản mang theo dấu ngoặc nhọn kép của chính nó
mô tả lý do. Một giá trị thông tin xác thực mà bản xuất chứa thuộc về một secret mà Release gắn vào, không thuộc về
Aggregate: hãy để trống nó, như bản nháp làm khi thiết lập empty_credentials yêu cầu.
# Aggregate fragment — a Flowise chatflow carried as exportedspec: components: chat: type: core/ai-agent/flowise values: chatflow_id: 3f2b8c1e-7a4d-4e9b-8c2f-1a6d5e9b0c47 flow_definition: | { "nodes": [ { "id": "llmChain_0", "data": { "name": "llmChain", "inputs": { "model": "{{"{{"}}chatOpenAI_0.data.instance}}", "prompt": "{{"{{"}}promptTemplate_0.data.instance}}" } } } ], "edges": [] }Importer MCP
importer/mcp đọc các máy chủ MCP mà cấu hình của một máy khách MCP liệt kê, hoặc một máy chủ duy nhất mà một mô tả máy chủ của registry MCP mô tả, và soạn nháp mỗi máy chủ thành một thực thể của công cụ MCP trong thư viện chuẩn, core/ai-tool/mcp. Mọi máy chủ đều là một công cụ như vậy, nên importer không cân nhắc ứng viên nào và không báo cáo quyết định ánh xạ nào.
Những gì nó đọc
- Cấu hình của một máy khách.
.mcp.jsoncủa Claude Code,claude_desktop_config.jsoncủa Claude Desktop và.cursor/mcp.jsoncủa Cursor liệt kê các máy chủ theo tên dướimcpServers;.vscode/mcp.jsoncủa Visual Studio Code liệt kê chúng dướiservers, và một tệp liệt kê máy chủ dưới cả hai được đọc dướimcpServerstrước. Một máy chủ cótypelàstdio, hoặc không nêutypenào và mang mộtcommand, được khởi động từ một dòng lệnh —commandvàargscủa nó — vớienvlàm môi trường. Một máy chủ cótypelàhttp,streamable-httphoặcsse, hoặc không nêutypelẫncommandvà mang mộturl, được truy cập tạiurlcủa nó và được gửiheaderscủa nó. - Mô tả máy chủ của registry. Tệp
server.jsonmà registry MCP công bố:namecủa nó, và gói đầu tiên của nó, hoặc, nơi nó không liệt kê gói nào, remote đầu tiên của nó. Một gói npm hoặc PyPI được khởi động từ dòng lệnh tạo bởi trình khởi chạy của nó —runtimeHintcủa nó, hoặcnpxcho npm vàuvxcho PyPI —runtimeArgumentscủa nó, gói cùng phiên bản, viết là<identifier>@<version>cho npm và<identifier>==<version>cho PyPI, vàpackageArgumentscủa nó, vớienvironmentVariableslàm môi trường. Một đối số vị trí làvaluecủa nó, hoặcdefaultcủa nó; một đối số có tên được viết là<name>=<value>nơi nó có một trong hai, và lànamecủa nó nơi nó không có cái nào. Một gói OCI chạy từ image màidentifiercủa nó nêu. Một remote được truy cập tạiurlcủa nó, được gửiheaderscủa nó. Mọi gói và remote khác mà mô tả liệt kê được nêu trong một chú thích, vì một thực thể chạy một trong số chúng.
Mọi thành phần khác của một máy chủ — cwd, envFile, auth của Cursor, hoặc một thành phần mà loại của nó không
đọc, chẳng hạn url của một máy chủ khởi động từ dòng lệnh — không được ghi ở đâu cả, và được nêu trong một
chú thích phía trên mục của máy chủ trong Release, vì không khóa hạ tầng nào của core/ai-tool/mcp
nhận nó. inputs của một cấu hình, vốn mô tả những gì Visual Studio Code nhắc nhập và không chứa
giá trị nào, không được đọc. Các máy chủ, môi trường và header của chúng giữ thứ tự mà nguồn
viết, trừ trong một cấu hình được đọc dưới dạng JSON có chú thích, vốn giữ thứ tự mà cây đã phân tích
của nó viết: thứ tự theo tên (xem Cấu hình chứa chú thích).
Một thư mục được đọc qua các cấu hình máy khách mà nó chứa — mọi tệp mang tên của một trong bốn tệp, ở bất kỳ độ sâu nào — theo thứ tự đường dẫn, và mọi máy chủ của mọi tệp được soạn nháp vào một Aggregate.
Một máy chủ trở thành gì
aggregate.yaml là một Aggregate nháp được đặt tên theo nguồn, như Cách đặt tên bản nháp mô tả, chứa một thực thể của core/ai-tool/mcp cho mỗi máy chủ. Một thực thể có khóa là tên máy chủ của nó, viết thường, với mỗi chuỗi ký tự liên tiếp không phải chữ cái hay chữ số được viết thành một dấu gạch nối, và một hậu tố số nơi một máy chủ trước đó đã lấy khóa đó. Nơi khóa không phải là tên máy chủ như được viết, hoặc lần nhập đọc nhiều tệp, một chú thích phía trên thực thể nêu máy chủ và tệp mà nó đến từ. Không agent nào được soạn nháp để sử dụng chúng.
Bên cạnh nó, release.yaml là một Release nháp cùng tên, có spec.aggregate nêu
Aggregate, mang cho mỗi thực thể các đầu vào vận hành mà nguồn nêu:
- với một máy chủ khởi động từ dòng lệnh,
infra.stdio_command, lệnh của nó rồi đến từng đối số, mỗi cái một mục; vàinfra.stdio_runtime, hệ sinh thái của trình khởi chạy,npmnơi lệnh lànpx,npmhoặcnode,pypinơi nó làuvx,uv,pythonhoặcpython3, và, với một gói registry, registry của nó,npmhoặcpypi; - với một máy chủ truy cập tại một địa chỉ,
infra.endpoint: địa chỉ không có phần người dùng, phần truy vấn và phần fragment, vì Component nhận địa chỉ không có bất kỳ phần nào mang khóa; mỗi phần bị bỏ ra được ghi trong chú thích phía trên mục, cạnh địa chỉ, như Giá trị thông tin xác thực mà một máy chủ chứa mô tả; - với một gói OCI,
infra.image; - không cho máy chủ nào, trên bất kỳ target nào,
infra.published_port: bản nháp không bao giờ công bố một máy chủ trên host; - cho môi trường của một máy chủ, slot
server_env, được gắn bằng tham chiếu theo target của lần nhập. Trên--target helm, đó là mộtcore/referenced-secretnêu một Kubernetes Secret đã có sẵn trong namespace, giữ một khóa dữ liệu cho mỗi biến, mỗi khóa được đặt tên theo biến mà nó giữ; tên của Secret được ghi rỗng, dưới một chú thích nêu các khóa dữ liệu, và thuộc các giá trị mà lần nhập còn nợ. Trên mọi target khác, và khi không có target, đó là mộtcore/referenced-secret-setvới một mục dướiinfra.entriescho mỗi biến, có khóa là tên biến và giá trị như nguồn viết, nên một tham chiếu biến như${GITHUB_TOKEN}vẫn là một tham chiếu, mà một target thay thế tham chiếu biến đọc từ môi trường.
Những gì nguồn không nêu được ghi rỗng, dưới một chú thích cho biết đó là gì: một lệnh có trình khởi chạy mà không image cầu nối nào mang sẽ để infra.stdio_runtime rỗng, và lần nhập còn nợ nó; một đối số mà mô tả registry để lại cho người dùng được ghi thành một mục rỗng, và một biến có giá trị mà nguồn không viết được ghi thành một mục có giá trị rỗng, mỗi cái được nêu trong chú thích phía trên mục.
Như mọi Release được soạn nháp, nó ghi metadata.environment là development, dưới một chú thích cho biết đây là giá trị mặc định của bản nháp cần thay đổi, và, khi không có target, ghi spec.manifest là một chuỗi rỗng mà lần nhập còn nợ. Khi được cung cấp một target, importer tự soạn nháp Manifest, vì catalog hiện thực core/ai-tool/mcp qua nhiều Recipes và chỉ importer biết mỗi máy chủ chạy thế nào: nó ánh xạ mỗi máy chủ theo khóa của nó, dưới mappings.components.name, tới realization của target tương ứng với cách máy chủ chạy — mcp-stdio-bridge cho một dòng lệnh, mcp-remote cho một địa chỉ, mcp cho một image, chẳng hạn helm/mcp-stdio-bridge hoặc compose/mcp-remote — và ánh xạ kiểu secret mà môi trường được gắn dưới dạng đó tới realization của nó, helm/k8s-existing-secret trên helm và compose/dotenv-secret-set trên compose. Lần nhập hoàn thiện Manifest đó và nêu nó trong Release, như Những gì một target thêm vào mô tả.
Một tệp .mcp.json của Claude Code liệt kê một máy chủ truy cập qua HTTP và một máy chủ khởi động bằng npx:
{ "mcpServers": { "api-server": { "type": "http", "url": "https://api.example.com/mcp", "headers": { "Authorization": "Bearer ${API_KEY}" } }, "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"], "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}" } } }}được soạn nháp thành:
apiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: imported/mcp version: 0.1.0 description: Draft Aggregate imported from a source in the mcp format.spec: components: api-server: type: core/ai-tool/mcp github: type: core/ai-tool/mcpapiVersion: aggrega.ai/v1beta1kind: Releasemetadata: name: imported/mcp # environment is a drafted default, since no source names the environment this Release deploys to; change it to name the one it deploys to. environment: development version: 0.1.0 description: Draft Release imported from a source in the mcp format.spec: aggregate: imported/mcp # manifest: left empty, since the import was given no target; an import given a target drafts the Manifest and names it here. manifest: "" components: # The headers the source sends this server, which no infrastructure key of core/ai-tool/mcp takes, since a remote server's credential is held by each consumer, on its connection to the tool: # - Authorization: "Bearer ${API_KEY}" api-server: infra: endpoint: "https://api.example.com/mcp" github: infra: stdio_command: - "npx" - "-y" - "@modelcontextprotocol/server-github" stdio_runtime: npm features: server_env: type: core/referenced-secret-set infra: # Attached by reference wherever the source names a variable: the environment github is started with, one entry per variable, each written as the source writes it, so a variable reference stays one, which a target substituting variable references, as Docker Compose does when the stack starts, reads from the environment, and an empty value is one still owed. entries: - key: "GITHUB_PERSONAL_ACCESS_TOKEN" value: "${GITHUB_TOKEN}"Khi được nhập với --target helm, Release của cùng cấu hình gắn môi trường dưới dạng Secret mà nó nêu, và Manifest mà importer soạn nháp ánh xạ mỗi máy chủ theo khóa của nó:
# release.yaml, the github entry's environment features: server_env: type: core/referenced-secret infra: # Left for the Release, since the source cannot supply it: the name of a Kubernetes Secret already in the namespace holding the environment github is started with, one data key per variable, each named as the variable it holds: GITHUB_PERSONAL_ACCESS_TOKEN. origin: ""apiVersion: aggrega.ai/v1beta1kind: Manifestmetadata: name: imported/mcp version: 0.1.0spec: mappings: components: type: {} name: api-server: helm/mcp-remote github: helm/mcp-stdio-bridge features: type: core/referenced-secret: helm/k8s-existing-secretCác giá trị thông tin xác thực mà một máy chủ nắm giữ
Mỗi giá trị trong cấu hình của một máy chủ mà Release ghi — giá trị của mỗi header, mỗi mục trong dòng lệnh của nó, địa chỉ của nó, mỗi phần của địa chỉ mà infra.endpoint bỏ ra và mỗi giá trị môi trường — đều có thể mang một khóa, và không client nào đánh dấu một giá trị là thông tin xác thực, nên quá trình nhập định vị mỗi giá trị như một thành viên trong cấu hình của một máy chủ MCP; một input của registry được đánh dấu isSecret được định vị như một giá trị mà định dạng của nó đánh dấu là thông tin xác thực. Một input của registry — một biến môi trường hoặc một header của một remote — được đọc là value của nó, hoặc default của nó khi nó không ghi giá trị nào. Theo mặc định, mỗi giá trị được mang nguyên văn vào Release và được nêu trong một cảnh báo credential-carried theo máy chủ và vị trí của nó — headers.<header>, infra.stdio_command.<position>, infra.endpoint hoặc server_env.<variable>, và một phần của địa chỉ theo url chứa nó cùng tên của phần đó, như trong “url of node remote-search is carried with its query as written (url của node remote-search được mang theo cùng query của nó như đã viết)” — không bao giờ theo giá trị của nó. Với thiết lập empty_credentials ở marked hoặc all, mỗi giá trị được ghi rỗng và được báo cáo bằng credential-emptied: một mục của dòng lệnh thành một mục rỗng và một giá trị môi trường thành một giá trị rỗng, mỗi cái được nêu trong chú thích phía trên mục; một địa chỉ thành một infra.endpoint rỗng, mà lần nhập còn nợ; và giá trị của một header hoặc một phần của địa chỉ bị bỏ khỏi chú thích, chú thích chỉ nêu tên header hoặc phần đó. infra.stdio_runtime của một client được đọc từ lệnh như Release ghi nó, nên một lệnh được ghi rỗng cũng để nó rỗng, và lần nhập còn nợ nó. Trên --target helm, Release hoàn toàn không ghi giá trị môi trường nào: Secret mà slot server_env nêu giữ chúng.
Một giá trị chỉ là một tham chiếu biến và không gì khác — tên trần ${NAME}, kể cả một biến định sẵn như ${workspaceFolder}, ${env:NAME} hoặc ${input:id} — không nắm giữ giá trị riêng nào: nó được ghi đúng như văn bản của nó bất kể thiết lập nói gì, và nó không được nêu trong cảnh báo nào, giống như một tham chiếu trong một flow. Một biến môi trường có giá trị là một tham chiếu như vậy được ghi thành giá trị của mục, tham chiếu vẫn là tham chiếu, còn một header hoặc một phần của địa chỉ có giá trị là một tham chiếu như vậy được liệt kê cùng tham chiếu mà nó đọc từ đó. Một tham chiếu mang văn bản sau một toán tử — một giá trị mặc định, một giá trị thay thế, một thông báo hoặc một phép gán, như ${NAME:-value} hoặc ${NAME-value}, có hoặc không có dấu hai chấm — nắm giữ văn bản đó, và văn bản nằm cạnh một tham chiếu cũng vậy; mỗi cái được định vị như mọi giá trị khác.
Không khóa hạ tầng nào của core/ai-tool/mcp nhận giá trị của một header: thông tin xác thực của một máy chủ từ xa do mỗi bên tiêu thụ nắm giữ, trên kết nối của nó tới công cụ, và quá trình import không tạo bản nháp bên tiêu thụ nào. Vì vậy chú thích phía trên mục của máy chủ liệt kê mỗi header mà nguồn gửi tới nó, cạnh giá trị nguyên văn của header — một chuỗi trong dấu ngoặc kép đọc lại đúng văn bản của nguồn — để bạn chuyển sang kết nối của bên tiêu thụ trình nó. Một header mà nguồn không ghi giá trị, như một input header của registry không có cả giá trị lẫn giá trị mặc định, được liệt kê là không có giá trị. Image mà một package OCI nêu tên được ghi nguyên như vậy, và không phải là giá trị mà thiết lập tác động tới.
infra.endpoint nhận địa chỉ không kèm bất kỳ phần nào mang khóa, nên các phần của địa chỉ mà nguồn ghi nhưng nó bỏ ra — phần người dùng trước @, query sau ? và fragment sau #, mọi thứ sau # đầu tiên đều là fragment — được liệt kê trong cùng chú thích đó, mỗi phần cạnh tên của nó và nguyên văn, không kèm @, ? hoặc # ngăn cách nó. Một bên tiêu thụ đọc khóa của nó từ địa chỉ sẽ tự cung cấp toàn bộ địa chỉ trên kết nối riêng của nó tới công cụ. Một máy chủ được truy cập tại https://user:pw@api.example.com/mcp?key=k, không có thiết lập nào, được tạo bản nháp thành:
# The address's user part and query are not written in infra.endpoint, which holds the address without any part that carries a key; a consumer reading its key from the address supplies the whole address on its own connection to the tool: # - user part: "user:pw" # - query: "key=k" api: infra: endpoint: "https://api.example.com/mcp"và với empty_credentials ở marked, infra.endpoint được để lại cho Release và chú thích liệt kê user part và query, mỗi cái với giá trị bị bỏ ra.
Một cấu hình chứa chú thích
Visual Studio Code đọc .vscode/mcp.json dưới dạng JSON có chú thích, và trình import MCP cũng vậy: chữ ký của nó cho tệp đó đọc tệp qua bộ phân tích phục vụ parse:jsonc, nên một cấu hình chứa chú thích // và /* */ cùng dấu phẩy cuối được nhận diện mà không cần nêu định dạng, và trình import đọc mọi nguồn liệt kê máy chủ dưới servers qua bộ phân tích đó. Một cấu hình như vậy được tạo bản nháp đúng như cùng cấu hình đó khi không có chú thích và dấu phẩy cuối. Bộ phân tích ghi các thành viên của một đối tượng theo thứ tự tên, nên các máy chủ của cấu hình như vậy, môi trường và header của chúng được tạo bản nháp theo thứ tự tên, dù cấu hình có chứa chú thích hay không; một dòng lệnh giữ nguyên thứ tự của nó. Các client khác và registry đọc tệp của chúng dưới dạng JSON, và trình import cũng vậy: một .mcp.json, claude_desktop_config.json, .cursor/mcp.json hoặc server.json chứa chú thích không được chữ ký nào nhận diện, và khi import với --format mcp thì nó dừng với parse-failed kèm lý do của bộ phân tích. Một chú thích mở bằng /* mà không bao giờ đóng được để nguyên, và bộ phân tích từ chối tệp.
Các thiết lập nó đọc
Trình import MCP đọc target_namespace và empty_credentials, như Thiết lập mô tả, và không đọc thiết lập nào khác.
Importer Compose
importer/compose đọc các service và các model mà một tệp Compose khai báo. Nó soạn mỗi service thành một instance của Component trong catalog mà image của service khớp với, hoặc của server tổng quát trong thư viện chuẩn, core/compute/server, chạy image đó; mỗi model thành một instance của runtime Docker Model Runner trong thư viện chuẩn, core/ai-model/docker-model-runner, nếu catalog của bạn có nó, và thành một Component model riêng nếu không có; cùng với một Release bên cạnh chứa những gì mỗi service khai báo cho hoạt động của nó.
Những gì nó đọc
- Các tệp. Một tệp được import riêng lẻ thì được đọc một mình. Một thư mục được đọc theo cách Compose đọc:
trong mỗi thư mục chứa tệp Compose, theo thứ tự đường dẫn của các thư mục, tệp đầu tiên có mặt
trong số
compose.yaml,compose.yml,docker-compose.ymlvàdocker-compose.yamllà tệp Compose, và tệp đầu tiên có mặt trong sốcompose.override.yml,compose.override.yaml,docker-compose.override.ymlvàdocker-compose.override.yamlđược hợp nhất đè lên nó. Các tệp khác trong số đó không được đọc. Một thư mục chứa tệp override mà không có tệp Compose thì tệp override đầu tiên được đọc một mình. Một chú thích mở đầu Aggregate được soạn nêu tên các tệp đã đọc, theo thứ tự hợp nhất, và các tệp không được đọc. Mọi service và model của mọi thư mục được soạn vào một Aggregate duy nhất. - Việc hợp nhất. Một tệp override được hợp nhất theo cách Compose hợp nhất:
imageđược thay thế;portsđược hợp nhất theo địa chỉ, cổng công bố, cổng container và giao thức,volumestheo đường dẫn trong container, vàenvironmenttheo tên biến, mục sau thế chỗ mục trước và mục mới được nối thêm;exposeđược nối thêm;depends_onvàmodelscủa một service được gộp, trong đóendpoint_varvàmodel_varcủa một mục mỗi cái thế chỗ giá trị mà tệp trước khai báo. Với một model,modelvàcontext_sizeđược thay thế cònruntime_flagsđược nối thêm. Các thẻ!resetvà!overridecủa Compose không được tôn trọng: một giá trị mang thẻ đó được hợp nhất theo cách bộ phân tích YAML đọc nó. - Một service.
imagecủa nó, và việc nó có build image dướibuildhay không;ports,expose,volumesvàenvironmentcủa nó — một mapping, hoặc một danh sách các mụcNAME=value, một tên không có giá trị thì lấy giá trị từ môi trường mà Compose chạy trong đó;depends_on, một danh sách hoặc một mapping; vàmodelscủa nó, một danh sách tên model hoặc một mapping mà các mục có thể nêu, dướiendpoint_varvàmodel_var, các biến qua đó địa chỉ và định danh của model đến được service. Mọi thành viên khác —command,healthcheck,secrets,env_filevà các thành viên còn lại — không được ghi vào đâu cả, và được nêu tên trong một chú thích phía trên mục của service trong Release. - Một model. Mỗi mục của
modelscấp cao nhất:modelcủa nó, định danh OCI của model,context_sizevàruntime_flagscủa nó, được mang nguyên văn vào một instance củacore/ai-model/docker-model-runnernếu catalog của bạn có nó, và của một Component model được soạn cho nó nếu không có; quyết định của model cho biết là cái nào, và vì sao. Mọi thành viên khác được nêu tên trong một chú thích phía trên instance của nó. - Phần còn lại. Các thành viên cấp cao nhất khác —
name,networks,volumes,secrets,configs— không được đọc, và chú thích mở đầu Aggregate nêu tên chúng.
Các service, các model và environment của một service giữ thứ tự mà tệp ghi chúng. Cây của bộ phân tích ghi các thành viên của một mapping theo thứ tự đã sắp xếp, nên thứ tự đó được đọc từ văn bản của tệp, khi chúng được viết dưới dạng block mapping; một mapping viết theo kiểu flow giữ thứ tự đã sắp xếp.
Một service là Component nào
Importer khớp một service theo repository mà image của nó nêu: tham chiếu không có tag và
digest, với tham chiếu Docker Hub viết ở dạng ngắn — postgres cho
docker.io/library/postgres:16. Nó khớp repository qua bảng image của mình, một bảng từ repository
image đến Component trong catalog mà một Recipe Compose của catalog chuẩn chạy một image của
repository đó cho. Bảng được sinh từ các Recipes Compose và các
Components của catalog chuẩn khi importer được build và được biên dịch vào trong nó, nên không Recipe nào được đọc khi một lần import
chạy và bảng chứa các label của catalog chuẩn, bất kể catalog của bạn chứa gì; thực thể
Plugin của importer nêu, trong phần mô tả, revision của hub mà bảng được sinh từ đó. Với mỗi
Recipe, bảng đọc Component mà Recipe hiện thực và image của container tên
main của nó, khi image đó tự ghi repository trong văn bản của chính nó, hoặc là một mục locals làm như vậy. Một
Recipe chạy image mà Release nêu trọn vẹn, hoặc một image mà template của nó ghép theo cách khác, không thêm
hàng nào, và một image mà Recipe chạy bên cạnh container chính cũng vậy. Hai Recipes nêu cùng một
repository cho các Components khác nhau sẽ làm dừng việc sinh bảng, nên một hàng không bao giờ nêu một trong hai.
Với Component mà một hàng nêu, bảng đọc các label của nó như khi chúng được trao cho một lần import — ở phiên bản
mà một tham chiếu nêu Component không kèm phiên bản phân giải tới, cùng những label nó kế thừa qua
extends — và ghi mọi label trừ component.aggrega.ai/category vào hàng làm traits của nó. Một
Recipe hiện thực một Component mà catalog chuẩn không có cũng làm dừng việc sinh bảng.
Một hàng được đọc như một hàng trong bảng của importer flow: Component, category mà tên của nó xếp nó vào,
traits của nó, và đoạn cuối của tên làm vendor.
Thiết lập mapping_overrides được xếp lớp lên bảng dưới định dạng compose, có khóa theo
repository, và một mục cho một repository mà
bảng đã ánh xạ sẽ thế chỗ hàng đó. Vì vậy một image mà các Recipes của catalog chuẩn không nêu — image của riêng bạn,
hoặc một image mà một Component của catalog chạy dưới repository khác — được ánh xạ bằng một mục:
with: settings: mapping_overrides: compose: bitnami/redis: component: core/datastore/redis category: datastore traits: datastore.aggrega.ai/engine: kv vendor: redisMột service có image được một hàng ánh xạ được quyết định như cách các importer flow quyết định một node: được chấm điểm so với các Components trong catalog của bạn, được tham chiếu khi reuse_mode là auto-apply-above-threshold, giá trị mặc định, và ứng viên tốt nhất là một kết quả khớp bậc cao bằng hoặc trên reuse_threshold, và được soạn thành một Component riêng nếu không, tệp của Component được soạn mở đầu bằng một chú thích nêu tên Component mà nó giống. Một hàng mang các label của Component mà nó nêu, nên khi catalog của bạn có Component đó với các label mà catalog chuẩn gán cho nó, một service được hàng đó ánh xạ là một kết quả khớp bậc cao cho nó, đạt điểm 0.90, và auto-apply-above-threshold tham chiếu nó ở reuse_threshold mặc định. Một Component mà catalog của bạn đã thay đổi label sẽ có điểm thấp hơn, tỷ lệ với phần traits của hàng mà nó không còn mang, và chỉ được tham chiếu khi nó còn ở bậc cao; category được tính một lần, trong tín hiệu riêng của nó, không tính lại như một trait. Các service soạn cùng một Component dùng chung một tệp của nó. Một service có image không được hàng nào ánh xạ, có image không nêu repository nào mà importer đọc được, hoặc tự build image của nó, là một instance của core/compute/server, bất kể catalog của bạn chứa gì. Quyết định của mỗi service được báo cáo như quyết định của mỗi node.
Một dịch vụ trở thành gì
aggregate.yaml là một Aggregate nháp được đặt tên theo dự án, như Cách đặt tên bản nháp mô tả, chứa một instance cho mỗi dịch vụ, thuộc Component mà quyết định của dịch vụ đó đã chọn, được đặt khóa như cách importer MCP đặt khóa cho một máy chủ, với một chú thích phía trên nêu tên dịch vụ và tệp mà nó đến từ đó, khi khóa không phải là tên của dịch vụ hoặc lần import đã đọc nhiều thư mục. Mỗi dịch vụ mà depends_on của một dịch vụ nêu tên là một kết nối, uses: <key>: <key>: {target: <key>}, được ghi dưới một socket và một alias đều được đặt tên theo khóa của đích. Một thành phần đọc từng kết nối của nó theo alias của kết nối đó, bất kể kết nối được nối vào socket nào, nên mỗi kết nối của một dịch vụ có alias riêng. Một biến trong môi trường của dịch vụ cũng có thể tạo ra một kết nối, cung cấp biến đó từ những gì dịch vụ mà nó trỏ tới công bố, như Môi trường và image của một dịch vụ trở thành gì mô tả. Mỗi model là một instance của core/ai-model/docker-model-runner khi catalog của workspace có nó, bất kể reuse_mode nói gì, và không Component nào được tạo nháp cho nó: instance ghi model và runtime_flags như nguồn nêu, và context_size của nguồn thành context_window, giá trị mà runtime khai báo cho độ dài ngữ cảnh của một model, được Compose Recipe của nó ghi ngược lại thành context_size của Compose. Khi catalog không có core/ai-model/docker-model-runner, model được tạo nháp thành <target_namespace>/ai-model/<key>, một Component thuộc danh mục ai-model mà values khai báo model, context_size và runtime_flags, và instance của nó ghi từng giá trị mà nguồn nêu. Mọi model đều có một quyết định cho biết trường hợp nào — mapped llm (model) to core/ai-model/docker-model-runner as a reference, NONE, hoặc một bản nháp có quyết định ghi nhận rằng catalog của workspace không có core/ai-model/docker-model-runner — và mỗi dịch vụ nêu tên model đều được kết nối với nó trong cả hai trường hợp, như với một dịch vụ mà nó phụ thuộc vào. Một dịch vụ nêu tên model ở dạng dài, với endpoint_var hoặc model_var, nêu tên các biến mà địa chỉ và định danh của model đến được dịch vụ qua đó. Không khóa nào của bản nháp chứa tên của một biến — kết nối được ghi trên một socket mang tên model, vốn không khai báo giá trị nào, và importer không được cung cấp khóa hạ tầng của Component nào — nên một chú thích phía trên kết nối nêu tên từng biến, như mục đó ghi, và quyết định của dịch vụ ghi nhận cùng câu đó:
search: type: core/compute/server uses: # The service search reads the address of the model embedder as AI_MODEL_URL and its identifier as AI_MODEL_NAME, the names its models entry gives them; no key of the draft holds either name. embedder: embedder: target: embedderMột dịch vụ nêu tên model ở dạng ngắn, hoặc không có biến nào trong hai biến, được kết nối với nó mà không có chú thích.
Bên cạnh đó, release.yaml là một Release nháp cùng tên, có spec.aggregate nêu tên Aggregate. Với một instance của core/compute/server, nó ghi infra.image, image như đã viết, và infra.port, cổng mà container lắng nghe trong mục đầu tiên của ports, hoặc của expose khi ports không có mục nào. Với --target compose, nó còn ghi infra.published_port, cổng host mà chính mục ports đó công bố, như nguồn nêu, dưới chú thích cho biết cổng này chỉ truy cập được từ máy này, bởi bất kỳ tiến trình nào chạy trên đó, và xóa dòng này sẽ giữ dịch vụ ở dạng nội bộ; một cổng host dưới 1024, mà published_port không nhận, sẽ không được ghi, và một chú thích phía trên mục nêu tên nó. Một chú thích phía trên mục của mỗi dịch vụ ghi những gì nguồn nêu mà không khóa nào của bản nháp mang — image của một dịch vụ được khớp với Component khác mà bản nháp không chuyển đổi tag, ports, expose, volumes của nó, và từng biến trong environment của nó mà bản nháp không chuyển đổi — để bạn mang sang nơi Component nhận nó. Những gì bản nháp để lại cho Release — image của một dịch vụ không nêu image nào, như dịch vụ tự build image của mình, và một cổng không phải là một số duy nhất — được ghi rỗng dưới một chú thích giải thích lý do. Một bản build chỉ đặt các instance mà Release nêu tên, nên instance của mỗi model có một mục rỗng, <key>: {}, sau các mục của dịch vụ: cả một instance của core/ai-model/docker-model-runner, vốn không nhận đầu vào nào trên Compose mà thiếu giá trị mặc định, lẫn một model được tạo nháp thành Component riêng, nên model được tạo nháp đã được đặt sẵn và build được ngay khi bạn viết Recipe hiện thực nó. Một cổng mà Component không nhận, chẳng hạn cổng dưới ngưỡng 1024 của core/compute/server, được ghi như nguồn nêu, và bản build dừng lại nêu tên nó. Release ghi metadata.environment và, khi không có target, một spec.manifest rỗng, như Release của importer MCP; khi có target, lần import tạo nháp Manifest, như Một target bổ sung những gì mô tả, ánh xạ mỗi Component tới Recipe hiện thực nó trên target đó — core/compute/server tới compose/server hoặc helm/server, và core/ai-model/docker-model-runner tới compose/docker-model-runner hoặc helm/docker-model-runner.
Một compose.yaml chạy PostgreSQL và một API riêng phụ thuộc vào nó:
services: db: image: postgres:16 environment: POSTGRES_DB: shop api: image: ghcr.io/example/shop-api:1.4.2 depends_on: - db ports: - "8080:8080" environment: CACHE_URL: redis://cache:6379/0được tạo nháp, không có thiết lập nào, trên một catalog chứa core/datastore/postgres của thư viện chuẩn, được nhập riêng và đặt tên theo tệp vì dự án không mang name nào, thành:
apiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: imported/compose version: 0.1.0 description: Draft Aggregate imported from a source in the compose format.spec: components: db: type: core/datastore/postgres # The values of core/datastore/postgres the source sets as POSTGRES_DB, the variables its Compose Recipes set from them. values: database: "shop" api: type: core/compute/server uses: db: db: target: dbapiVersion: aggrega.ai/v1beta1kind: Releasemetadata: name: imported/compose # environment is a drafted default, since no source names the environment this Release deploys to; change it to name the one it deploys to. environment: development version: 0.1.0 description: Draft Release imported from a source in the compose format.spec: aggregate: imported/compose # manifest: left empty, since the import was given no target; an import given a target drafts the Manifest and names it here. manifest: "" components: db: infra: # The tag of the image the source runs, postgres:16, the engine_version of core/datastore/postgres its Compose Recipes run. engine_version: "16" # The source also states, for the Release to carry where core/compute/server takes it: # ports: # - "8080:8080" # environment: # CACHE_URL: "redis://cache:6379/0" api: infra: image: "ghcr.io/example/shop-api:1.4.2" port: 8080Lần import báo cáo mapped db (postgres) to core/datastore/postgres as a reference, HIGH at 0.9. Dự án không có dịch vụ cache, nên CACHE_URL không tạo kết nối và vẫn nằm trong chú thích. Với reuse_mode: hints-only, db thay vào đó là type: imported/datastore/postgres, được tạo nháp trong components/imported-datastore-postgres.yaml, tệp này mở đầu bằng # resembles core/datastore/postgres (score 0.9000); reference it by setting type: core/datastore/postgres; khi đó image và môi trường của nó được ghi trong chú thích phía trên mục của nó, vì một Component được tạo nháp không khai báo giá trị nào mà các Recipes của catalog đọc. Với --target compose, Manifest ánh xạ core/datastore/postgres tới compose/postgres và core/compute/server tới compose/server; với --target helm, tới helm/postgres và helm/server.
Môi trường và image của một dịch vụ trở thành gì
Khi một dịch vụ là một instance của Component trong catalog mà hàng của image nó nêu tên, và catalog của workspace có Component đó, importer đọc image và môi trường của dịch vụ như cách các Compose Recipes của catalog chuẩn cho Component đó đọc chúng, dựa trên những gì bảng image ghi nhận về từng Recipe, và chuyển đổi chúng vào các bản nháp:
- Tag của image là khóa hạ tầng mà Recipe dùng để dựng tham chiếu image, chẳng hạn
engine_version—16chopostgres:16— được ghi trong Release dưới một chú thích nêu tên image của nguồn. - Một biến mà Recipe đặt từ một trong các giá trị của Component —
POSTGRES_DB,POSTGRES_USER— có giá trị chứa văn bản, là giá trị đó của instance,databasehoặcuser, khi Component của catalog khai báo nó, được ghi trong Aggregate dưới một chú thích nêu tên các biến. - Một biến mà Recipe đọc mật khẩu từ đó, chẳng hạn
POSTGRES_PASSWORD, có giá trị là một tham chiếu biến duy nhất, là một secret được gắn vào slot đó, được đọc từ biến mà tham chiếu nêu tên và được khai báo với khóa mà Recipe dùng để đọc nó.
Và, với mọi dịch vụ, từng biến trong môi trường của nó không được đọc theo cách trên:
- Một giá trị là tên của một dịch vụ khác trong dự án, khi hàng của dịch vụ đó nêu tên khóa
providescông bố tên host của nó, tạo ra một kết nối tới dịch vụ đó, mà khốiinjectcủa kết nối cung cấp biến từ khóa đó —CACHE_HOST: cachelàCACHE_HOSTlấy từhostcủa cache. - Một giá trị bằng với giá trị mà một dịch vụ khác đặt cho Component của nó và Component đó công bố —
DATABASE_USER: notesbên cạnh một dịch vụ PostgreSQL đặtPOSTGRES_USER: notes— tạo ra một kết nối cung cấp biến từ khóaprovidesđó. Khi nhiều dịch vụ hoặc khóa giữ giá trị đó, cái có khóa, hoặc có biến riêng, kết thúc giống như cách tên biến kết thúc sẽ được đọc, và nếu không có, cái mà các biến khác của dịch vụ chưa được đọc từ đó; nếu không, biến không được đọc. - Một giá trị là một tham chiếu biến duy nhất nêu tên một biến mà secret của một dịch vụ khác được đọc từ đó —
DATABASE_PASSWORD: ${POSTGRES_PASSWORD}— trên một instance củacore/compute/server, là một secret riêng, được gắn dưới tên biến viết thường và được đọc từ cùng biến đó, khi target ghi secret thành một giá trị mà máy chủ nhận.helm/servertừ chốicore/referenced-secret, nên với--target helmbiến như vậy vẫn nằm trong chú thích.
Mọi biến khác được để lại trong chú thích phía trên mục của dịch vụ, như nguồn ghi. Hướng dẫn từng bước import Compose trình bày một dự án có API truy cập cơ sở dữ liệu và cache của nó theo cách này, được build và chạy đúng như bản nháp.
Các giá trị thông tin xác thực mà một dịch vụ chứa
Compose không đánh dấu giá trị môi trường nào là thông tin xác thực, và importer không đọc tên biến nào để suy ra ý nghĩa của nó, nên mọi giá trị môi trường có chứa nội dung đều được xác định là một đầu vào mà định dạng của nó đánh dấu là không phải thông tin xác thực nhưng có thể mang thông tin xác thực. Theo mặc định, mỗi giá trị được mang nguyên văn vào các bản nháp — vào giá trị mà nó được chuyển đổi thành, hoặc vào chú thích phía trên mục của dịch vụ trong Release — và được nêu tên trong cảnh báo credential-carried theo dịch vụ và biến của nó — environment.<variable> — không bao giờ theo giá trị. Với thiết lập empty_credentials ở all, mỗi giá trị được ghi rỗng và được báo cáo bằng credential-emptied: chú thích nêu tên biến mà không có giá trị. Ở marked, không giá trị nào được ghi rỗng, vì Compose không đánh dấu giá trị nào. Một giá trị chỉ là một tham chiếu biến mà Compose nội suy và không gì khác — ${NAME} hoặc $NAME — không chứa giá trị riêng: nó được ghi đúng như văn bản của nó và không được nêu tên trong cảnh báo nào. Một tham chiếu mang giá trị mặc định hoặc thông báo, chẳng hạn ${NAME:-value}, chứa văn bản đó và được xác định như mọi giá trị khác. Một giá trị mà Compose đọc từ nơi khác — một env_file, tệp của một secret — không được đọc.
Các thiết lập nó đọc
Importer Compose đọc target_namespace, reuse_mode, reuse_threshold, emit_hints,
render_mode, mapping_overrides và empty_credentials, như Thiết lập mô tả, và không đọc thiết lập nào khác. Gợi ý mà emit_hints điều khiển chỉ được ghi trong tệp của Component được tạo nháp; Aggregate được tạo nháp không mang gợi ý nào.
Trình nhập Dify
importer/dify đọc một ứng dụng được xuất từ Dify dưới dạng DSL của nó, tài liệu YAML mà Dify ghi cho
một ứng dụng, và soạn thảo một Aggregate kết hợp bản cài đặt Dify của thư viện chuẩn,
core/dify, với ứng dụng được mang trong tham số app_definition của bản cài đặt. Bản
cài đặt nhập nó khi triển khai, thông qua bước mà Recipe của máy chủ API của nó kết xuất cho nó.
Những gì nó đọc
- Ứng dụng.
kind, có giá trịapp;version, phiên bản DSL mà ứng dụng được viết; vàapp, cùng vớimodecủa nó. - Một workflow hoặc một chatflow —
modeworkflowhoặcadvanced-chat— giữ đồ thị của nó dướiworkflow: mỗi nút củaworkflow.graph.nodesnêu kiểu của nó dướidata.typelà một nút của ứng dụng, theo thứ tự đồ thị liệt kê chúng, vàworkflow.environment_variableschứa các biến mà nó đọc. - Một ứng dụng chat, agent chat hoặc completion giữ cấu hình của nó dưới
model_config:modelcủa nó, mỗi cơ sở tri thức dướidataset_configs.datasets.datasetsvà mỗi công cụ dướiagent_mode.toolslà một nút của ứng dụng, được đặt tên theo vị trí của nó ở đó, chẳng hạn nhưmodel_config.model. Một ứng dụng thuộc chế độagentlà một nút,agent. - Các plugin mà nó cần. Mỗi mục của
dependenciescũng là một nút, được đặt têndependencies.<n>, thuộc kiểu mà mục đó nêu, chẳng hạn nhưmarketplace.
Không có gì khác quyết định những gì được soạn thảo: toàn bộ ứng dụng được mang theo.
Một ứng dụng trở thành gì
aggregate.yaml là một Aggregate nháp được đặt tên theo ứng dụng, như Cách đặt tên bản nháp mô tả, kết hợp một mục của core/dify, có khóa dify, mà tham số app_definition của nó mang ứng dụng như đã viết — như Cách luồng được ghi vào bản nháp mô tả cho một luồng, nên các tham chiếu {{#…#}} riêng của Dify đến bản cài đặt đúng như khi được xuất. Bản cài đặt tự nối mọi kết nối của máy chủ API của nó — cơ sở dữ liệu, bộ nhớ đệm, kho vector, sandbox, môi trường chạy plugin và proxy đầu ra của nó — nên bản nháp không soạn thảo Component nào và không nối gì cả: mọi nút vẫn nằm trong ứng dụng, và quyết định của nó nói như vậy. Bên cạnh nó, release.yaml là một Release nháp cùng tên, đặt bản cài đặt vào một ranh giới, platform, và mang những gì ứng dụng không thể cung cấp.
Một lần nhập thấy các Components của catalog trong workspace nhưng không thấy Aggregates nào của nó, nên nó không
kiểm tra rằng catalog có chứa core/dify, và một chú thích phía trên mục nói như vậy. Khi catalog
không chứa core/ai-agent/dify, máy chủ API mà core/dify chạy, lần nhập cảnh báo bằng
platform-not-in-catalog và vẫn soạn thảo mục đó.
Bí mật ứng dụng của bản cài đặt, tức khóa mà Dify dùng để ký cookie phiên và để mã hóa thông tin xác thực của nhà cung cấp mô hình mà nó lưu trữ, là tham số secret_key của core/dify, vốn không có giá trị mặc định. Vì vậy bản nháp khai báo một tham số secret_key của riêng nó — một chuỗi, bắt buộc, dài ít nhất một ký tự và không có giá trị mặc định — và truyền nó xuống mọi mục core/dify mà nó ghi, để Release đáp ứng dưới parameters của mình; một bản build mà Release để trống tham số này sẽ dừng và nêu tên nó.
Ứng dụng được nhập dưới tài khoản chủ sở hữu của bản cài đặt, mà Release nêu tên trong mục định tuyến của nó cho bản cài đặt: infra.owner_email trên component api của bản cài đặt, và slot owner_password trên component đó, được gắn dưới dạng core/referenced-secret; thiếu chúng, bản dựng sẽ dừng. Email của chủ sở hữu không phải thứ mà nguồn nào có thể cung cấp, nên nó được ghi trống dưới một chú thích cho biết nó là gì, và lần nhập ghi nhận nó là giá trị còn thiếu.
Trên mọi target, cùng mục định tuyến đó đặt infra.marketplace_enabled thành true trên các component api, worker và scheduler của bản cài đặt, mỗi cái dưới một chú thích giải thích lý do: bản cài đặt không truy cập được gì của nhà cung cấp Dify trừ khi Release cho phép, mỗi component trong ba component đọc thiết lập riêng của nó, và Dify cài đặt plugin phục vụ model của một ứng dụng, chẳng hạn của OpenAI, từ chợ plugin của nó.
Bí mật ứng dụng và mật khẩu của chủ sở hữu là các bí mật, được soạn thảo bằng tham chiếu theo target của lần nhập:
- Với
--target helm, mỗi cái nêu tên một Kubernetes Secret đã có trong namespace:secret_keylà tên của Secret, màcore/difyđọc dưới khóa dữ liệusecret-key, vàowner_passwordlà một Secret chứa mật khẩu dưới khóa dữ liệuvalue. Không tên nào trong hai tên này là thứ mà nguồn nào có thể cung cấp, nên mỗi cái được ghi trống dưới một chú thích cho biết nó là gì, và lần nhập ghi nhận cả hai là giá trị còn thiếu; Manifest được soạn thảo ánh xạcore/referenced-secrettớihelm/k8s-existing-secret. - Trên mọi target khác, và khi không có target, mỗi cái là một tham chiếu tới một biến —
secret_keydưới dạng"${DIFY_SECRET_KEY}"và mật khẩu của chủ sở hữu dưới dạng"${DIFY_OWNER_PASSWORD}", những tên mà các Recipes Dify cho Compose của catalog chuẩn đọc — mà Docker Compose đọc từ môi trường khi stack khởi động, nên không còn gì thiếu cho cả hai; với--target compose, Manifest được soạn thảo ánh xạcore/referenced-secrettớicompose/dotenv-referenced-secret.
Khi có target, Manifest ánh xạ kiểu của mỗi component mà bản cài đặt kết hợp cũng như kiểu của chính bản nháp, như Một target bổ sung những gì mô tả.
Ứng dụng workflow được tạo sẵn mà các bài kiểm thử của trình nhập này nhập, có tên Support Answers, được soạn thảo, không có thiết lập nào, như sau:
apiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: imported/support-answers version: 0.1.0 description: Draft Aggregate imported from a source in the dify format.spec: parameters: secret_key: type: string required: true minLength: 1 description: "Passed down to core/dify's secret_key parameter, which has no default; that parameter's description in core/dify says what the value is." aggregates: # An import sees the Components of the workspace's catalog and none of its Aggregates, so it does not check that the catalog holds core/dify. dify: type: core/dify parameters: secret_key: "{{ .parameters.secret_key }}" app_definition: | app: description: Answers a support question from a knowledge base and files it. ...Khi nhập với --target helm, Release được soạn thảo của nó đáp ứng secret_key, đồng thời nêu tên chủ sở hữu và bật chợ plugin trong mục định tuyến đặt bản cài đặt, với mỗi giá trị còn thiếu được ghi trống:
apiVersion: aggrega.ai/v1beta1kind: Releasemetadata: name: imported/support-answers # environment is a drafted default, since no source names the environment this Release deploys to; change it to name the one it deploys to. environment: development version: 0.1.0 description: Draft Release imported from a source in the dify format.spec: aggregate: imported/support-answers manifest: imported/support-answers parameters: # Left for the Release, since the source cannot supply it: secret_key, which the drafted Aggregate declares and passes down to core/dify; that parameter's description there says what the value is secret_key: "" boundaries: platform: aggregates: dify: components: api: infra: # Lets the installation reach Dify's plugin marketplace, which the plugin serving the application's model, such as OpenAI's, is installed from. marketplace_enabled: true # Left for the Release, since the source cannot supply it: components.api.infra.owner_email, the email of the installation's owner account the application is imported under, on the api component of core/dify owner_email: "" features: owner_password: type: core/referenced-secret infra: # Left for the Release, since the source cannot supply it: the name of a Kubernetes Secret already in the namespace holding, under the data key value, the owner account's password. origin: "" worker: infra: # Lets the installation reach Dify's plugin marketplace, which the plugin serving the application's model, such as OpenAI's, is installed from. marketplace_enabled: true scheduler: infra: # Lets the installation reach Dify's plugin marketplace, which the plugin serving the application's model, such as OpenAI's, is installed from. marketplace_enabled: trueLần nhập ghi nhận ba giá trị trống là giá trị còn thiếu. Khi nhập với --target compose, cùng Release đó ghi secret_key: "${DIFY_SECRET_KEY}" và origin: "${DIFY_OWNER_PASSWORD}", và chỉ ghi nhận email của chủ sở hữu là giá trị còn thiếu; nó cũng ghi infra.published_port trên component api, 5001, và trên front end, tức component console, 3001, mỗi cái dưới chú thích cho biết dịch vụ chỉ có thể truy cập từ máy này, bởi bất kỳ tiến trình nào chạy trên máy, và việc xóa dòng đó giữ dịch vụ ở dạng nội bộ, và, bên dưới cổng của component api, ghi infra.console_url với địa chỉ mà console được công bố, "http://127.0.0.1:3001", mà máy chủ Dify dùng làm địa chỉ của console. Hướng dẫn từng bước nhập Dify build một ứng dụng cho cả hai target và chạy nó trên Kubernetes.
Những gì Dify tự cấu hình
Dify tự cấu hình bên trong nó các nhà cung cấp của các mô hình và công cụ mà một ứng dụng gọi, và
core/ai-agent/dify không khai báo socket nào cho mô hình, nên bản nháp không nối gì. Mỗi nút nêu tên một thứ như vậy được
báo cáo bằng part-configured-in-platform, và trong quyết định của nó, theo những gì nó nêu:
- một nút
llm,question-classifierhoặcparameter-extractor, vàmodel_config.modelcủa một ứng dụng chat: mô hình, theo tên và nhà cung cấp của nó; - một nút
tool, và công cụ của một ứng dụng chat: công cụ, theo tên và nhà cung cấp của nó; - một nút
agent: chiến lược agent và plugin cung cấp nó; - một nút
knowledge-retrieval, và cơ sở tri thức của một ứng dụng chat: các cơ sở tri thức mà nó truy xuất, và mô hình mà nó dùng để định tuyến truy vấn hoặc xếp hạng lại, nếu nó nêu một mô hình. Một ứng dụng nêu tên một cơ sở tri thức bằng một định danh của bản cài đặt mà nó được xuất từ đó, và không mang theo tài liệu nào cũng như kho nào, nên mỗi cơ sở được tạo bên trong Dify, trong kho vector mà bản cài đặt nối với máy chủ API của nó; - một phụ thuộc: plugin, theo định danh mà Dify cài đặt nó, và nguồn mà Dify cài đặt nó từ đó.
Mọi nút khác được giữ trong ứng dụng mà không báo cáo gì.
Các giá trị thông tin xác thực mà một ứng dụng chứa
Trình nhập định vị, theo thứ tự ứng dụng ghi chúng:
- giá trị của mỗi biến môi trường có
value_typelàsecret, mà Dify đánh dấu là thông tin xác thực. Bản xuất của Dify ghi nó rỗng trừ khi bản xuất bao gồm bí mật; authorization.config.api_keycủa một nút yêu cầu HTTP, mà Dify đánh dấu là thông tin xác thực và xuất như đã viết;- thông tin xác thực đã lưu mà một nút
tool, hoặc một công cụ của nútagent, chọn dướicredential_id, mà Dify đánh dấu là thông tin xác thực và chỉ ghi khi bản xuất bao gồm bí mật; headersvàparamscủa một nút yêu cầu HTTP, mà Dify đánh dấu là không phải thông tin xác thực và có thể mang một thông tin xác thực, mỗi cái ở dạng toàn bộ.
Theo mặc định, mỗi mục chứa giá trị được mang như đã viết trong ứng dụng và được nêu tên trong một
cảnh báo credential-carried theo nút của nó — workflow đối với một biến môi trường — và trường của nó,
không bao giờ theo giá trị của nó. Với thiết lập empty_credentials ở marked, mỗi giá trị Dify
đánh dấu là thông tin xác thực được ghi rỗng, và ở all thì cả các header và tham số truy vấn, mỗi cái
được báo cáo bằng credential-emptied. Một giá trị chỉ là một tham chiếu biến và không gì khác thì không chứa
giá trị nào, và được mang như đã viết bất kể thiết lập nói gì và không được nêu trong cảnh báo nào, như
trong một luồng. Một giá trị được ghi rỗng trong chính văn bản của ứng dụng:
vô hướng sau khóa của nó được thay bằng '', và không gì khác bị thay đổi. Ứng dụng chỉ được mang
khi trình phân tích phục vụ parse:yaml đọc lại kết quả thành đúng ứng dụng đã xuất với chính xác
những giá trị đó bị làm rỗng; nếu không, nó không được mang, app_definition được để trống kèm một chú thích, và
definition-not-carried cho biết lý do — như với một ứng dụng trong đó một alias YAML đọc giá trị của một bí mật,
mà việc ghi rỗng giá trị đó cũng sẽ thay đổi theo. Một giá trị mà thiết lập để nguyên như đã viết không bao giờ
bị viết lại, nên nó không bao giờ ngăn ứng dụng được mang theo.
Phiên bản DSL
Khi một ứng dụng được viết bằng phiên bản DSL mới hơn 0.7.0, phiên bản mà Dify 1.17.0
— phiên bản core/ai-agent/dify chạy theo mặc định — ghi, lần nhập cảnh báo bằng
dsl-version-newer. Dify giữ việc nhập một ứng dụng như vậy để chờ xác nhận, mà bước
nhập nó khi triển khai sẽ đưa ra, vì vậy hãy kiểm tra ứng dụng với phiên bản Dify mà Release chạy.
Các thiết lập nó đọc
Trình nhập Dify đọc target_namespace, empty_credentials, layout, attach_egress_allowlist
và render_mode, như Thiết lập mô tả chúng, cùng reuse_mode, reuse_threshold,
emit_hints và mapping_overrides, vốn không thay đổi gì mà bố cục mặc định soạn thảo: mọi nút vẫn
nằm trong ứng dụng. attach_egress_allowlist không gắn gì, vì một mục của một
Aggregate được kết hợp nhận tham số và không nhận Feature nào, và khi nó là true lần nhập cảnh báo bằng
feature-not-attached. layout: nodes soạn thảo mỗi nút thành một Component riêng, như
Từng nút một mô tả, và không mang ứng dụng nào.
Trình nhập CrewAI
importer/crewai đọc các agent và các task mà một dự án CrewAI khai báo trong các tệp cấu hình của nó,
và soạn một Aggregate chứa một instance của agent CrewAI trong thư viện chuẩn,
core/ai-agent/crewai, cho mỗi agent, mỗi instance được nối với model mà cấu hình của nó chỉ định, cùng một Release
bên cạnh.
Những gì nó đọc
CrewAI giữ hành vi của một crew trong một chương trình và khai báo các agent cùng các task của nó trong các tệp cấu hình, theo một trong hai bố cục, và trình nhập đọc được cả hai:
- Một dự án cổ điển —
config/agents.yaml, mỗi agent được định khóa theo tên của nó, vàconfig/tasks.yaml, mỗi task được định khóa theo tên của nó, cả hai được đọc dưới dạng YAML. Các agent được đọc theo thứ tự màagents.yamlviết chúng. - Một dự án theo bố cục JSON-first —
crew.jsonc, liệt kê các agent của crew theo tên dướiagentsvà các task của nó dướitasks, vàagents/<name>.jsonc, mỗi agent một tệp, tất cả được đọc dưới dạng JSON có chú thích, nên chú thích và dấu phẩy cuối của chúng được đọc như CrewAI đọc. Các agent được đọc theo thứ tựcrew.jsoncliệt kê, tiếp theo là tệp của mọi agent khác theo thứ tự tên; một agent mà crew liệt kê nhưng tệp của nó không được trao cho lần nhập sẽ được nêu tên trong một chú thích và không được soạn thành gì cả. Cùng bố cục đó viết bằng JSON nghiêm ngặt —crew.jsonvàagents/<name>.json— được đọc theo cùng cách. Khi một crew hoặc một agent được viết theo cả hai cách, tệp.jsonclà tệp được đọc, như CrewAI đọc, và tệp.jsonđược nêu tên trong một chú thích là không được đọc.
Với một agent, trình nhập đọc role, goal và backstory của nó; allow_delegation và verbose, ở cấp cao nhất
của khai báo hoặc dưới settings, trong đó settings được ưu tiên, như CrewAI đọc; llm của nó; và
tên các tools của nó. Với một task, trình nhập đọc tên của nó và agent được giao task đó. Mọi thành phần khác đều
được nêu tên trong một chú thích và không được mang đi đâu cả.
Một thư mục được trao cho trình nhập dưới dạng các tệp mà chữ ký của nó chỉ định và không tệp nào khác, nên chương trình
của crew — crew.py của một dự án cổ điển, main.py của một flow, một tool mà dự án định nghĩa bằng Python — không bao giờ
được đọc. Một tệp được nhập riêng được đọc như khai báo mà hình dạng của nó thể hiện. Thư mục của một dự án
có thể chứa nhiều crew, mỗi crew được đọc từ thư mục riêng của nó.
Một dự án trở thành gì
aggregate.yaml là một Aggregate nháp được đặt tên theo crew, như Cách đặt tên bản nháp mô tả, mở đầu bằng các chú thích nêu tên các khai báo đã đọc, việc chương trình của crew không được đọc, và các task của mỗi crew cùng agent được giao từng task. Nó chứa, cho mỗi agent và được định khóa theo tên của agent, một instance của core/ai-agent/crewai với:
role,goalvàbackstorynhư đã khai báo;allow_delegationnhư đã khai báo, vàfalsekhi agent không khai báo;log_levelDEBUGcho một agent được khai báoverbose, tường thuật từng bước suy luận của nó, vàINFOcho agent không được khai báo như vậy, chỉ báo cáo tiến độ và sự cố. Mộtverbosehoặc mộtallow_delegationkhông phảitruecũng không phảifalseđược để theo giá trị mặc định của Component và được nêu tên trong một chú thích;- kết nối
modelcủa nó, được nối với instance của model màllmcủa nó chỉ định.
Một llm được viết <provider>/<model>, hoặc dưới dạng một đối tượng nêu tên model dưới model, model_name
hoặc deployment_name, chỉ định một provider và một model. Model là một instance của
Component trong catalog dành cho provider đó — core/ai-model/<provider>, với dấu gạch dưới trong tên provider được đọc
là dấu gạch nối, và azure được đọc là azure-openai — được định khóa theo tên model, với model là
values.model của nó; các agent chỉ định cùng một provider và model dùng chung một instance. Khi catalog của workspace
không chứa Component nào có tên đó, một Component sẽ được soạn, <target_namespace>/ai-model/<provider>, khai báo
giá trị model, và quyết định của nó nói rõ điều đó; nhãn model.aggrega.ai/api mà socket model
của agent dùng để chọn một Component, và một Recipe công bố endpoint và model của nó, được để lại cho bạn,
như một chú thích mở đầu nó nói. Một llm không chỉ định provider — một tên model trơn, mà CrewAI tự xác định
provider khi chương trình chạy, hoặc tên của một llm mà chương trình định nghĩa — một tham chiếu vào
chương trình, và một agent không khai báo llm, khi đó CrewAI đọc nó từ môi trường mà chương trình
chạy trong đó, đều không được nối với gì, và một chú thích phía trên agent giải thích lý do; quá trình build dừng lại và nêu tên
socket model cho đến khi có một kết nối được nối.
Một task là logic mà chương trình của crew chạy, và một tool là mã mà chương trình định nghĩa hoặc nạp: không cái nào
trở thành một Component. Mỗi cái được báo cáo trong một quyết định không chọn gì, và một tool có tên — sau khi bỏ
hậu tố Tool, các dấu gạch nối và gạch dưới — trùng với tên của một Component tool mà catalog
chứa sẽ mang Component đó làm gợi ý: search_tool và SearchTool đều gợi ý
core/ai-tool/search. core/ai-agent/crewai không khai báo socket nào cho tool, nên không có gì được nối cho
tool.
release.yaml, bên cạnh nó, là một Release nháp cùng tên chỉ định Aggregate đó. Nó ghi trống infra.image của mỗi agent — image chạy chương trình của crew, mà không khai báo nào nêu tên — dưới một chú thích cho biết nó là gì, và lần nhập ghi nhận nó là giá trị còn thiếu. Với --target compose, mục của mỗi agent cũng ghi infra.published_port, 8000, cổng mà infra.port của Component chỉ định mặc định cho chương trình, được Recipe Compose của nó công bố trên địa chỉ loopback của máy chủ, 127.0.0.1, dưới chú thích cho biết dịch vụ chỉ có thể truy cập từ máy này, bởi bất kỳ tiến trình nào chạy trên máy, và việc xóa dòng đó giữ dịch vụ ở dạng nội bộ; agent thứ hai lấy cổng trống tiếp theo, nên hai agent của dự án cổ điển được công bố trên 8000 và 8001. Nó gắn thông tin xác thực mà mỗi agent xuất trình cho model của mình dưới credential trên kết nối model của agent, bằng tham chiếu và không bao giờ dưới dạng giá trị: không khai báo nào nêu tên một biến cho nó, nên nó được đọc từ biến mà các thư viện client của nhà cung cấp đọc khóa API của chúng — OPENAI_API_KEY đối với OpenAI — dưới dạng tham chiếu ${…} trên mọi target trừ helm, và trên helm dưới dạng tên của một Kubernetes Secret, được ghi trống để lần nhập ghi nhận là giá trị còn thiếu; trên compose, kết nối model của agent khai báo nó với khóa đó. Mỗi model cũng có một mục, không chứa hạ tầng nào, nên Release đặt nó cùng với các agent. Với một model được khai báo dưới dạng một đối tượng llm, mỗi thành phần khác được ghi thành một giá trị của instance của model khi Component của catalog khai báo một giá trị mang tên đó, và nếu không thì trong một chú thích phía trên mục của model trong Release, để bạn mang nó tới nơi Component nhận nó. Như mọi Release được soạn thảo, nó ghi metadata.environment là development và, khi không có target, một spec.manifest trống mà lần nhập ghi nhận là giá trị còn thiếu; khi có target, lần nhập soạn thảo Manifest, như Một target bổ sung những gì mô tả.
Dự án cổ điển mà các bài kiểm thử của trình nhập này nhập, có hai agent đều chỉ định openai/gpt-4o, được soạn, không có thiết lập nào, như bên dưới; khi được nhập dưới dạng thư mục dự án của nó, market_brief — thư mục mà crewai create crew market_brief bố trí một dự án như vậy vào — và vì các khai báo của nó không nêu tên crew nào, nó được đặt tên theo thư mục đó:
# CrewAI declarations read:# - src/market_brief/config/agents.yaml# - src/market_brief/config/tasks.yaml# Not read: the crew's program, which runs its agents and its tasks and defines its tools; it runs in the image the Release names for each agent.# Tasks the crew's program runs, drafted as no Component:# - research_task, assigned to researcher# - brief_task, assigned to brief_writerapiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: imported/market-brief version: 0.1.0 description: Draft Aggregate imported from a source in the crewai format.spec: components: # Tools the crew's program defines or loads for this agent, drafted as no Component: search_tool. researcher: type: core/ai-agent/crewai values: role: "{topic} Market Researcher\u000A" goal: "Gather the facts about {topic} a buyer needs before a first meeting\u000A" backstory: "You have briefed sales teams for years. ..." allow_delegation: false log_level: DEBUG uses: model: gpt-4o: target: gpt-4o # For the compose target only, uncomment the lines below, which declare credential on gpt-4o: a secret the Release alone attaches arrives under the key value, so each is declared with a key of its own and no two arrive under one; the Release attaches its origin, naming this type or none. # features: # credential: # type: core/secret-value # values: # key: OPENAI_API_KEY # The agent brief_writer. # Not carried, since core/ai-agent/crewai takes no value for it: max_iter. brief-writer: type: core/ai-agent/crewai ... # The model openai/gpt-4o. gpt-4o: type: core/ai-model/openai values: model: "gpt-4o"và Release của nó, được soạn thảo không có target, như bên dưới, với mục của agent thứ hai được lược bỏ ở đây và đánh dấu ...; lần nhập ghi nhận spec.manifest và image của mỗi agent là giá trị còn thiếu:
spec: aggregate: imported/market-brief # manifest: left empty, since the import was given no target; an import given a target drafts the Manifest and names it here. manifest: "" components: researcher: infra: # Left for the Release, since the source cannot supply it: infra.image, the container image running the crew's program image: "" uses: model: gpt-4o: features: credential: type: core/secret-value infra: # Attached by reference, never as a value: the credential researcher presents to gpt-4o on its model connection (the source names no variable for it, so it is read from the one OpenAI's client libraries read the API key from), read from the variable OPENAI_API_KEY, which a target substituting variable references, as Docker Compose does when the stack starts, reads from the environment, so no file carries the value. origin: "${OPENAI_API_KEY}" brief-writer: ... gpt-4o: {}Khi đó mỗi agent được render chạy image mà bạn trả lời, nhận endpoint và tên của model dưới dạng OPENAI_BASE_URL và MODEL, các biến mà CrewAI đọc chúng từ đó.
Các giá trị thông tin xác thực mà một khai báo chứa
Một llm được viết dưới dạng đối tượng có thể mang một khóa — dưới api_key, trong một địa chỉ, trong các header. Mỗi thành phần của nó ngoài thành phần nêu tên model mà không phải số hay boolean là một giá trị có thể mang khóa, mà CrewAI không đánh dấu là thông tin xác thực. Theo mặc định, mỗi thành phần chứa giá trị được mang nguyên văn — dưới dạng một giá trị của instance của model khi Component của nó khai báo một giá trị như vậy, và nếu không thì vào chú thích phía trên mục của model nó trong Release — và được nêu tên trong một cảnh báo credential-carried theo agent và thành phần của nó, chẳng hạn llm.api_key, không bao giờ theo giá trị. Với thiết lập empty_credentials ở all, mỗi thành phần được viết không có giá trị và được báo cáo bằng credential-emptied; ở marked, mỗi thành phần được mang đi, vì CrewAI không đánh dấu thành phần nào. Tên của một thành phần không được đọc theo ý nghĩa của nó. Mọi thành phần khác mà một khai báo chứa nhưng bản nháp không mang — cấu hình của một tool, inputs của một crew — đều được nêu tên, không bao giờ kèm giá trị.
Các thiết lập nó đọc
Trình nhập CrewAI đọc target_namespace, empty_credentials và render_mode, như
Thiết lập mô tả, và không thiết lập nào khác.
Importer LangGraph
importer/langgraph đọc các graph mà cấu hình của một ứng dụng LangGraph, langgraph.json, khai báo, và soạn thảo một Aggregate chứa một instance của agent LangGraph trong thư viện chuẩn, core/ai-agent/langgraph, cho mỗi graph, mỗi instance được nối với kho dữ liệu mà checkpointer của nó lưu trạng thái và với một model, cùng một Release bên cạnh mang môi trường mà cấu hình nêu ra. Importer đọc cấu hình đó, và không bao giờ đọc mã của các graph.
Những gì nó đọc
Một ứng dụng LangGraph giữ các graph trong mã và khai báo chúng trong langgraph.json: dưới
graphs, id của mỗi graph ánh xạ tới đường dẫn import của graph trong mã ứng dụng —
./src/agent/graph.py:graph, hoặc module:attr — hoặc tới một đối tượng nêu đường dẫn đó dưới path và
mô tả graph dưới description. Importer đọc, theo thứ tự cấu hình viết chúng:
graphs— id của mỗi graph, đường dẫn import và mô tả của nó;checkpointer—backendcủa nó:default, tức PostgreSQL và là giá trị LangGraph dùng khi không nêu backend nào;mongo, một cơ sở dữ liệu dùng giao thức của MongoDB; hoặccustom, một checkpointer do mã ứng dụng định nghĩa tạipath;store— kho bộ nhớ, không nêu backend nào: LangGraph giữ nó trong cơ sở dữ liệu PostgreSQL mà server của nó dùng;env— môi trường mà ứng dụng chạy cùng: một đối tượng ánh xạ tên biến tới giá trị, hoặc đường dẫn của một tệp môi trường gồm các dòngKEY=VALUE.
Các thành phần cấu hình image server mà langgraph build build — dependencies, source, python_version, node_version, base_image, image_distro, dockerfile_lines, pip_config_file, pip_installer, keep_pkg_tools, api_version — được nêu tên trong một chú thích và không được mang đi đâu, vì image mà Release nêu tên là image riêng của ứng dụng; mọi thành phần khác cũng vậy, trong đó có cấu hình riêng của server như auth, http và webhooks, và index và ttl của store cùng ttl và serde của checkpointer cũng vậy.
Một thư mục được giao cho importer dưới dạng langgraph.json và không tệp nào khác, nên cả mã của
ứng dụng lẫn tệp môi trường đều không bao giờ được đọc từ đó. Một tệp môi trường chỉ đến được
importer khi with.sources của importer giao nó, và không bao giờ được phân tích: với tệp mà
env của cấu hình nêu — được khớp theo đoạn cuối của đường dẫn nó nêu — chỉ tên các biến
được đọc, và một tệp môi trường mà không cấu hình nào nêu được ghi tên trong một chú thích là không được đọc.
Khi import không được giao tệp mà cấu hình nêu, Aggregate ghi tên tệp đó là chưa được giao
và hướng dẫn nêu nó dưới with.sources của importer, còn các biến của nó được để lại cho Release:
plugins: importer: - uri: importer/langgraph:<version> with: sources: - ./local.envMột cấu hình được import riêng lẻ sẽ được đọc bất kể tên của nó. Một thư mục có thể chứa nhiều ứng dụng, mỗi ứng dụng được đọc từ thư mục riêng của nó.
Một ứng dụng trở thành gì
aggregate.yaml là một Aggregate nháp được đặt tên theo graph, như Cách đặt tên bản nháp mô tả, mở đầu bằng các chú thích nêu các cấu hình đã đọc, các tệp môi trường chỉ được đọc lấy tên biến, việc mã của ứng dụng không được đọc, và những gì bản nháp không mang theo. Nó chứa, cho mỗi graph và theo khóa là id của graph, một instance của core/ai-agent/langgraph với:
graph_entrypoint, đường dẫn import của graph, như cấu hình viết;description, mô tả của graph, khi cấu hình có cung cấp;- kết nối
checkpointer_dbcủa nó, được nối với kho dữ liệu của ứng dụng; - kết nối
modelcủa nó, được nối tới model của ứng dụng.
recursion_limit không được ghi, nên giá trị mặc định của Component, 25, được giữ nguyên. Cấu hình không nêu model nào, nên bản nháp chứa một instance của core/ai-model/openai, có khóa model, mà mọi graph gọi tới: model được giao cho client OpenAI của agent. values.model của nó được ghi trống, dưới một chú thích cho biết cấu hình không nêu model nào, và lần nhập ghi nhận nó là giá trị còn thiếu.
Backend của checkpointer là kho dữ liệu mà mọi graph của ứng dụng được nối tới: default, hoặc một checkpointer không nêu backend nào, là một instance của core/datastore/postgres, có khóa postgres. mongo là FerretDB, vốn dùng giao thức của MongoDB, chạy trên PostgreSQL với tiện ích mở rộng DocumentDB: một instance của core/datastore/ferretdb, có khóa ferretdb, mà mọi graph được nối tới, và một instance của core/datastore/documentdb, có khóa documentdb, mà kết nối backend của FerretDB đi tới, với khối inject của nó chuyển những gì DocumentDB công bố dưới các tên mà FerretDB đọc; một mật khẩu duy nhất, đọc từ biến FERRETDB_PASSWORD, được gắn trên DocumentDB, trên kết nối của FerretDB tới nó và trên kết nối của mỗi graph tới FerretDB. Khi catalog của workspace không có Component nào mang tên của kho dữ liệu PostgreSQL, một Component được soạn thảo, <target_namespace>/datastore/postgres, khai báo host và port mà kết nối checkpointer_db của agent đọc, và quyết định của nó nói rõ điều này; một Recipe chạy kho dữ liệu và công bố chúng được để lại cho bạn, như một chú thích ở đầu nó cho biết. Khi catalog không có Component FerretDB hoặc không có Component DocumentDB, checkpointer mongo không được nối tới kho dữ liệu nào. Một checkpointer custom, hoặc một backend mà importer không ánh xạ tới kho dữ liệu nào, không nối gì cả, và một chú thích phía trên mỗi graph cùng quyết định của checkpointer giải thích lý do; quá trình build dừng lại và nêu tên socket checkpointer_db cho đến khi một kho dữ liệu được nối vào. Store được báo cáo trong một quyết định không chọn gì.
Mật khẩu của kho dữ liệu là một bí mật mà bản nháp gắn bằng tham chiếu, trên slot password của chính kho dữ liệu và trên kết nối checkpointer_db của mỗi graph, và thông tin xác thực mà mỗi graph xuất trình cho model trên kết nối model của nó cũng vậy: được đọc từ POSTGRES_PASSWORD (hoặc FERRETDB_PASSWORD) và OPENAI_API_KEY, vì cấu hình không nêu biến nào cho cả hai, dưới dạng tham chiếu ${…} trên mọi target trừ helm, và trên helm dưới dạng tên của một Kubernetes Secret, được ghi trống để lần nhập ghi nhận là giá trị còn thiếu. Trên compose, Aggregate khai báo mỗi cái với khóa mà Recipe của nó đọc, như Bí mật, cho từng target mô tả cho một nền tảng.
release.yaml, bên cạnh nó, là một Release nháp cùng tên, nêu Aggregate đó. Các chú thích phía trên mục của graph đầu tiên cho biết image của mỗi graph là gì — image riêng của ứng dụng, tức mã của nó có cài LangGraph, chứ không phải image server mà langgraph build build — các biến được truyền cho nó và khối inject: nào thay thế tên nào trong số đó. Mục của mỗi graph ghi trống infra.image của nó, image chạy ứng dụng, dưới một chú thích cho biết nó là gì, và lần nhập ghi nhận nó là giá trị còn thiếu; trong khi nó chưa được đặt, Recipe Docker Compose chạy agent quickstart riêng của catalog, vốn đọc các biến mặc định. Với --target compose, mục của mỗi graph cũng ghi infra.published_port, 8000, cổng mà infra.port của Component chỉ định mặc định cho ứng dụng, được Recipe Compose của nó công bố trên địa chỉ loopback của máy chủ, 127.0.0.1, dưới chú thích cho biết dịch vụ chỉ có thể truy cập từ máy này, bởi bất kỳ tiến trình nào chạy trên máy, và việc xóa dòng đó giữ dịch vụ ở dạng nội bộ; graph thứ hai lấy cổng trống tiếp theo. Kho dữ liệu và model cũng có các mục, nên Release đặt chúng cùng với các graph. Một chú thích phía trên graph đầu tiên của ứng dụng nêu môi trường mà cấu hình của nó khai báo, như Môi trường mà một cấu hình nêu ra mô tả. Như mọi Release được soạn thảo, nó ghi metadata.environment là development và, khi không có target, một spec.manifest trống mà lần nhập ghi nhận là giá trị còn thiếu; khi có target, lần nhập soạn thảo Manifest, như Một target bổ sung những gì mô tả.
Ứng dụng Python mà các bài kiểm thử của importer này import, khai báo hai graph, một checkpointer không nêu backend nào, một store và một env viết dưới dạng đối tượng, được soạn thảo, không có thiết lập nào, như bên dưới; khi được import dưới dạng thư mục của nó, support_desk — được đặt tên, như ở đây, theo package nơi các graph của nó được định nghĩa — với hai graph có id khác nhau, nó được đặt tên theo thư mục đó:
# LangGraph configurations read:# - langgraph.json# Not read: the application's code, which defines each graph; it runs in the image the Release names for each graph.# Not carried, since they configure the server image langgraph build builds, and the image the Release names is the application's own: dependencies, python_version.# Not carried, since core/ai-agent/langgraph takes no value for them: http.# The store configures the memory store, which LangGraph keeps in the PostgreSQL database its server uses; not carried, since core/ai-agent/langgraph takes no value for it: index, ttl.# Not carried, since core/ai-agent/langgraph takes no value for them: checkpointer.ttl.apiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: imported/support-desk version: 0.1.0 description: Draft Aggregate imported from a source in the langgraph format.spec: components: triage: type: core/ai-agent/langgraph values: graph_entrypoint: "./src/support_desk/triage.py:make_graph" description: "Routes an incoming ticket to the {team} that owns it." uses: checkpointer_db: postgres: target: postgres # For the compose target only, uncomment the lines below, which declare credential on postgres: a secret the Release alone attaches arrives under the key value, so each is declared with a key of its own and no two arrive under one; the Release attaches its origin, naming this type or none. # features: # credential: # type: core/secret-value # values: # key: POSTGRES_PASSWORD model: model: target: model # For the compose target only, uncomment the lines below, ... support: type: core/ai-agent/langgraph ... # The database the configuration's checkpointer keeps each graph's state in, PostgreSQL. postgres: type: core/datastore/postgres # For the compose target only, uncomment the lines below, ... # The model every graph calls, which the configuration does not name. model: type: core/ai-model/openai values: # Left for the author, since the configuration names no model: values.model, the name of the model core/ai-model/openai serves. model: ""spec: aggregate: imported/support-desk # manifest: left empty, since the import was given no target; an import given a target drafts the Manifest and names it here. manifest: "" components: # Each graph's image is the application's own, not the server image langgraph build builds: its code, with LangGraph installed. # It is handed, for its code to read, the graph to run as LANGGRAPH_GRAPH_ENTRYPOINT, the model's name as OPENAI_MODEL, the checkpointer store's host and port as LANGGRAPH_CHECKPOINTER_HOST and LANGGRAPH_CHECKPOINTER_PORT, its user and database, where the store publishes them, as LANGGRAPH_CHECKPOINTER_USER and LANGGRAPH_CHECKPOINTER_DATABASE, and a password attached on the checkpointer_db connection as LANGGRAPH_CHECKPOINTER_PASSWORD. # It is also handed the model's address as OPENAI_BASE_URL and a key attached on the model connection as OPENAI_API_KEY, which the OpenAI client library reads, and recursion_limit as LANGGRAPH_DEFAULT_RECURSION_LIMIT, which LangGraph reads. # An inject: block on the graph's own instance, through an entry reading graph_entrypoint alone, replaces LANGGRAPH_GRAPH_ENTRYPOINT with the name it writes; one on the model connection replaces OPENAI_MODEL, and one on the checkpointer_db connection the store's host, port, user and database, with the names it writes. # The environment langgraph.json states for its application, for the Release to carry where core/ai-agent/langgraph takes it for each of its graphs: # SUPPORT_QUEUE: "..." # OPENAI_API_KEY: "..." # MAX_TICKETS: "25" triage: infra: # Left for the Release, since the source cannot supply it: infra.image, the container image running the application image: "" uses: checkpointer_db: postgres: features: credential: type: core/secret-value infra: # Attached by reference, never as a value: the credential triage presents to postgres on its checkpointer_db connection, the password of postgres (the configuration names no variable for it), read from the variable POSTGRES_PASSWORD, which a target substituting variable references, as Docker Compose does when the stack starts, reads from the environment, so no file carries the value. origin: "${POSTGRES_PASSWORD}" model: model: features: credential: type: core/secret-value infra: # Attached by reference, never as a value: the credential triage presents to model on its model connection (the source names no variable for it, so it is read from the one OpenAI's client libraries read the API key from), read from the variable OPENAI_API_KEY, which a target substituting variable references, as Docker Compose does when the stack starts, reads from the environment, so no file carries the value. origin: "${OPENAI_API_KEY}" ... postgres: features: password: type: core/secret-value infra: # Attached by reference, never as a value: the password of postgres (the configuration names no variable for it), read from the variable POSTGRES_PASSWORD, which a target substituting variable references, as Docker Compose does when the stack starts, reads from the environment, so no file carries the value. origin: "${POSTGRES_PASSWORD}" model: {}Lần nhập ghi nhận bốn giá trị còn thiếu: spec.manifest, image của mỗi graph và tên của model. Khi chúng đã được trả lời, mỗi graph được render để chạy image mà bạn trả lời, nhận địa chỉ kho dữ liệu của nó dưới dạng LANGGRAPH_CHECKPOINTER_HOST và LANGGRAPH_CHECKPOINTER_PORT, người dùng và cơ sở dữ liệu mà kho dữ liệu công bố dưới dạng LANGGRAPH_CHECKPOINTER_USER và LANGGRAPH_CHECKPOINTER_DATABASE — PostgreSQL công bố cả hai, còn với một kho dữ liệu không công bố cái nào thì không biến nào trong hai biến được render — endpoint cùng tên của model dưới dạng OPENAI_BASE_URL và OPENAI_MODEL, khóa mà thông tin xác thực model của nó chuyển giao dưới dạng OPENAI_API_KEY, đường dẫn import của nó dưới dạng LANGGRAPH_GRAPH_ENTRYPOINT và giới hạn số bước của nó dưới dạng LANGGRAPH_DEFAULT_RECURSION_LIMIT. Thông tin xác thực gắn trên kết nối checkpointer_db của nó cũng cung cấp cho nó mật khẩu của kho dữ liệu dưới dạng LANGGRAPH_CHECKPOINTER_PASSWORD.
Môi trường mà một cấu hình nêu ra
Mọi biến mà env của cấu hình nêu là một đầu vào để Release cung cấp, và không biến nào được
soạn thảo thành một ô thông tin xác thực: LangGraph không đánh dấu biến nào là bí mật, và tên của một biến không được đọc
để suy ra ý nghĩa. core/ai-agent/langgraph không nhận giá trị nào cho môi trường, nên Release nêu
nó trong một chú thích phía trên graph đầu tiên của ứng dụng.
- Một
envviết dưới dạng đối tượng là một phần của cấu hình, nên các giá trị của nó được mang nguyên văn vào chú thích đó, theo thứ tự cấu hình viết chúng. Mỗi giá trị có nội dung đều có thể mang một thông tin xác thực, mà LangGraph không đánh dấu: theo mặc định mỗi giá trị được mang nguyên văn và được nêu tên trong một cảnh báocredential-carriedtheo cấu hình và biến của nó, chẳng hạnenv.OPENAI_API_KEY, không bao giờ theo giá trị của nó. Với thiết lậpempty_credentialsởall, mỗi giá trị được ghi không có giá trị và được báo cáo bằngcredential-emptied; ởmarkedmỗi giá trị được mang theo, vì LangGraph không đánh dấu giá trị nào. - Một
envnêu một tệp nêu một tệp mà cấu hình chỉ trỏ tới, thường chứa các bí mật cục bộ. Tệp chỉ được đọc khiwith.sourcescủa importer giao nó. Chú thích nêu tên từng biến mà tệp nêu, để Release cung cấp, và không giá trị nào của tệp được đọc: không giá trị nào đến được bản nháp, quyết định hay chẩn đoán, bất kể thiết lập là gì. Một giá trị được đặt trong dấu nháy trải qua nhiều dòng là một giá trị, nên một dòng bên trong nó không bao giờ bị coi là một biến, và một dòng không nêu biến nào được nêu theo số dòng. Khi import không được giao tệp — luôn như vậy với một thư mục, vốn không bao giờ giao tệp — Aggregate ghi tên tệp là chưa được giao, kèm cách giao nó, và các biến của nó được để lại cho Release.
Các thiết lập nó đọc
Importer LangGraph đọc target_namespace, empty_credentials và render_mode, như
Thiết lập mô tả, và không đọc thiết lập nào khác.
Importer Google ADK
importer/google-adk đọc các agent mà một ứng dụng xây dựng trên Agent Development Kit (ADK) của Google khai báo trong các tệp Agent Config của nó — root_agent.yaml và các cấu hình mà các sub-agent của nó nêu tên — và soạn thảo một Aggregate chứa một instance của agent ADK trong thư viện chuẩn, core/ai-agent/google-adk, cho mỗi cây agent, được nối tới mô hình mà cây đó nêu tên khi ADK gửi các yêu cầu của mô hình đó tới Gemini API, cùng một Release bên cạnh. Importer đọc các cấu hình đó, và không bao giờ đọc mã của ứng dụng.
ADK nêu rằng tính năng Agent Config của nó mang tính thử nghiệm. Mô hình của một agent mặc định là một mô hình Gemini; ADK phục vụ mô hình của một số nhà cung cấp khác theo tên thông qua các lớp riêng của nó, chẳng hạn claude-sonnet-4-5 và gpt-4o, và các mô hình khác thông qua một chuỗi mô hình LiteLLM. Socket model của agent chỉ chấp nhận Gemini API, nên importer nối một mô hình mà ADK gửi tới Gemini API và để lại mọi mô hình khác cho bạn, như Một cây agent trở thành gì mô tả.
Những gì nó đọc
Lệnh adk create --type=config của ADK ghi ra root_agent.yaml, cấu hình của agent gốc của một ứng dụng,
cùng một tệp môi trường bên cạnh. Một cấu hình khai báo một agent:
name,descriptionvàagent_class— lớp mà ADK dùng để xây dựng agent, làLlmAgentkhi cấu hình không nêu lớp nào;model— mô hình mà agent yêu cầu — hoặcmodel_code, một tham chiếu tới mã xây dựng mô hình của nó;tools— mỗi công cụ theoname, với cácargsmà cấu hình của nó truyền cho công cụ;generate_content_config— các tùy chọn cho các yêu cầu gửi tới mô hình của agent, trong đó cóhttp_options;sub_agents— mỗi mục là mộtconfig_path, đường dẫn của một cấu hình khác tính từ thư mục của cấu hình nêu tên nó, hoặccode, một agent do mã của ứng dụng xây dựng.
Một thư mục được truyền cho importer dưới dạng các tệp root_agent.yaml của nó và không tệp nào khác, và một
cấu hình được nhập riêng lẻ được đọc như một gốc, bất kể tên của nó. Cây của mỗi gốc được đọc từ gốc
trước, các sub-agent của mỗi agent theo thứ tự agent đó liệt kê. Cấu hình mà một mục sub_agents nêu tên
bằng config_path chỉ được đọc khi with.sources của importer truyền nó vào, được so khớp theo đoạn cuối
của đường dẫn; cấu hình nào mà lần nhập không được truyền vào thì được nêu tên trong Aggregate và trong quyết định của nó là không được truyền,
kèm cách truyền nó, và agent của nó không được đọc:
plugins: importer: - uri: importer/google-adk:<version> with: sources: - ./my_agent/code_tutor_agent.yaml - ./my_agent/math_tutor_agent.yamlMột config_path là đường dẫn tuyệt đối, hoặc dẫn ra ngoài thư mục của cấu hình nêu tên nó, sẽ không được
đọc, vì ADK cũng từ chối nó. Một tệp mà with.sources truyền vào nhưng không cấu hình nào nêu tên sẽ được nêu trong một
chú thích là không được đọc, và không phần nào của nó được đọc; một tệp được truyền vào chỉ được đọc như một cấu hình mà cây của một gốc
nêu tên, nên một lần nhập không chứa root_agent.yaml nào và không có tệp nào được nhập riêng lẻ sẽ không đọc cây nào và
báo cáo mỗi tệp dưới no-nodes. Mã của ứng dụng — các công cụ, callback, schema và agent mà một
cấu hình nêu tên bằng mã của chúng — và tệp môi trường không bao giờ được truyền vào, và importer không đọc
cả hai: ứng dụng tự nạp các cấu hình của nó, từ image mà Release nêu tên. Một
thư mục có thể chứa nhiều ứng dụng, mỗi ứng dụng được đọc từ root_agent.yaml riêng của nó.
Các thành phần khác của một cấu hình — trong đó có instruction của một agent — được ứng dụng đọc
từ chính cấu hình của nó, nên bản nháp không mang theo thành phần nào trong số đó.
Một cây agent trở thành gì
ADK phục vụ một ứng dụng từ agent gốc của nó, với mọi agent mà các cấu hình của nó nêu tên được xây dựng bên trong, và core/ai-agent/google-adk chạy một ứng dụng như vậy. Vì thế aggregate.yaml, một Aggregate nháp được đặt tên theo agent gốc, như Cách đặt tên bản nháp mô tả, chứa, cho mỗi cây agent và được khóa theo tên agent gốc của cây, một instance của core/ai-agent/google-adk với:
description, mô tả của agent gốc, khi cấu hình của nó có mô tả;- kết nối
modelcủa nó, được nối tới mô hình mà cây nêu tên khi ADK gửi các yêu cầu của mô hình đó tới Gemini API.
Các chú thích phía trên nó nêu tên các agent khác của cây, vốn không trở thành instance riêng; mỗi sub-agent không được đọc, và lý do — do mã của ứng dụng xây dựng, một cấu hình mà lần nhập không được truyền vào, hoặc một cấu hình ADK từ chối; các công cụ mà các agent của cây nêu tên, những công cụ ADK cung cấp sẵn và những công cụ mã của ứng dụng định nghĩa; các agent có lớp — LoopAgent, ParallelAgent hoặc SequentialAgent — bị ADK ngừng khuyến nghị để chuyển sang Workflow; và, khi mô hình của cây đã được nối, các mô hình mà những agent khác của cây yêu cầu, mỗi mô hình kèm theo họ mô hình mà ADK dùng để phục vụ nó. Mỗi mục được báo cáo trong một quyết định không chọn gì.
Agent đầu tiên của cây, tính từ gốc, nêu tên một mô hình hoặc mã xây dựng mô hình sẽ quyết định mô hình của instance. Một mô hình được nêu tên mà ADK gửi các yêu cầu của nó tới Gemini API — một tên mô hình ADK phục vụ qua lớp Gemini của nó, chẳng hạn gemini-2.5-flash, ngoại trừ tên tài nguyên Vertex AI, hoặc một tên ADK phục vụ qua lớp Gemma của nó — là một instance của core/ai-model/gemini, phục vụ mô hình đó và được khóa theo nó, và các cây nêu tên cùng một mô hình dùng chung một instance. Khi catalog của workspace không chứa core/ai-model/gemini, một bản sẽ được soạn thảo, <target_namespace>/ai-model/gemini, mang nhãn model.aggrega.ai/api: gemini mà socket model của agent chọn, và quyết định của nó nói rõ điều đó; một Recipe công bố endpoint và mô hình của nó được để lại cho bạn, như một chú thích ở đầu nó cho biết. Một mô hình mà ADK phục vụ theo bất kỳ cách nào khác — một chuỗi mô hình LiteLLM như openai/gpt-4o, một tên tài nguyên Vertex AI, hoặc một tên như claude-sonnet-4-5 hay gpt-4o, mà ADK phục vụ qua Anthropic hoặc OpenAI — không được nối tới gì: socket model của agent nhận một mô hình Gemini, và agent không đọc tên mô hình nào từ môi trường của nó, nên bạn nối một mô hình Gemini vào đó và nêu tên mô hình ấy trong cấu hình của agent. Chú thích phía trên instance và quyết định của agent gốc nêu tên mô hình và họ mô hình mà ADK dùng để phục vụ nó. Một mô hình do mã của ứng dụng xây dựng, hoặc một cây không nêu tên mô hình nào — khi đó ADK dùng mô hình mặc định của nó — cũng không được nối tới gì, và một chú thích phía trên instance giải thích lý do. Bất cứ khi nào mô hình không được nối tới gì, bản build dừng lại và nêu tên socket model cho tới khi có một mô hình được nối. Trong các mô hình mà những agent khác của một cây yêu cầu, mô hình nào được ADK gửi yêu cầu tới Gemini API thì không cần kết nối riêng: client Gemini của ADK gửi các yêu cầu của nó bằng khóa mà kết nối của instance cung cấp. Việc ứng dụng truy cập Gemini qua Gemini API hay qua Vertex AI được quyết định bởi môi trường của nó, thứ mà lần nhập không đọc; socket model của agent chỉ chấp nhận Gemini API.
Các bài kiểm thử của importer này cũng nhập một agent gốc đơn lẻ nêu tên openai/gpt-4o, có instance được soạn thảo như sau:
spec: components: # The agent tree of root_agent.yaml, served from its root agent routed_agent. # The model connection is left for the author, since the model openai/gpt-4o, which routed_agent names, is one ADK serves through LiteLLM, not through the Gemini API, while core/ai-agent/google-adk takes a Gemini model on its model socket and reads no model name from its environment, so the author wires a Gemini model there and names that model in routed_agent's configuration; the build halts naming the socket until one is wired. routed-agent: type: core/ai-agent/google-adk values: description: "Answers questions with a model another provider serves."release.yaml, bên cạnh nó, là một Release nháp cùng tên, nêu tên Aggregate đó. Mục của mỗi instance ghi infra.image của instance — image chạy ứng dụng xây dựng trên ADK, chứa các cấu hình của nó — ở dạng trống, dưới một chú thích cho biết nó là gì, và lần nhập ghi nhận nó là giá trị còn thiếu. Với --target compose, mục còn ghi infra.published_port, 8000, cổng mà ứng dụng lắng nghe, được Recipe Compose của nó công bố trên địa chỉ loopback của máy chủ, 127.0.0.1, dưới chú thích cho biết cổng này chỉ truy cập được từ máy này, bởi bất kỳ tiến trình nào chạy trên đó, và việc xóa dòng này giữ dịch vụ ở dạng nội bộ; một cây thứ hai nhận cổng trống kế tiếp. Khi mô hình của instance đã được nối, mục gắn thông tin xác thực mà instance xuất trình cho mô hình đó dưới credential trên kết nối model của nó, bằng tham chiếu và không bao giờ dưới dạng giá trị: không cấu hình nào nêu tên một biến cho nó, nên nó được đọc từ GOOGLE_API_KEY, biến mà các thư viện client Gemini API của Google đọc khóa từ đó, dưới dạng tham chiếu ${…} trên mọi target trừ helm, và trên helm dưới dạng tên của một Kubernetes Secret, được ghi trống để lần nhập ghi nhận là còn thiếu; trên compose, kết nối model khai báo nó với khóa đó. Một mô hình đã được nối cũng có một mục, không chứa hạ tầng nào, nên Release đặt nó cùng với instance. Các giá trị mà các cấu hình của cây truyền cho công cụ và cho các yêu cầu mô hình được ghi trong một chú thích phía trên mục đó, như Các giá trị thông tin xác thực mà một cấu hình chứa mô tả. Giống như mọi Release được phác thảo, nó ghi metadata.environment là development và, khi không có target, một spec.manifest trống mà lần nhập ghi nhận là còn thiếu; khi được cung cấp một target, lần nhập phác thảo Manifest, như Một target bổ sung những gì mô tả.
Ứng dụng mà các bài kiểm thử của importer này nhập, gồm một agent gốc nêu tên cấu hình của hai sub-agent và một sub-agent do mã xây dựng, được nhập dưới dạng thư mục của nó với hai cấu hình được nêu tên dưới with.sources, được soạn thảo, không có thiết lập nào, dưới tên agent gốc của nó, tutor_root, như sau:
# Google ADK agent configurations read:# - root_agent.yaml# - code_tutor_agent.yaml# - math_tutor_agent.yaml# Not read: the application's code, which defines the tools, callbacks and agents a configuration names by their code, nor the environment file ADK's scaffold writes beside root_agent.yaml; the application runs in the image the Release names for each instance, and loads its configurations itself.# ADK states that its Agent Config is experimental. An agent's model is a Gemini model by default; ADK serves some other providers' models by name through classes of its own, such as claude-sonnet-4-5 and gpt-4o, and others through a LiteLLM model string.apiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: imported/tutor-root version: 0.1.0 description: Draft Aggregate imported from a source in the google-adk format.spec: components: # The agent tree of root_agent.yaml, served from its root agent tutor_root. # Sub-agents ADK builds inside this application, drafted as no instance of their own: code_tutor_agent, math_tutor_agent. # Not read: a sub-agent of tutor_root, which is built by the application's code at tutor_agents.review_agent, which the import does not read. # Tools ADK ships, which run inside the application, drafted as no Component: google_search. # Tools the application's code defines, drafted as no Component: tutor_tools.make_snippet_runner. # Models other agents of the tree ask for, ...: gemini-pro-latest (math_tutor_agent, served through Gemini). tutor-root: type: core/ai-agent/google-adk values: description: "Learning assistant that tutors {{`{{`}} students }} in code and math." uses: model: gemini-flash-latest: target: gemini-flash-latest # For the compose target only, uncomment the lines below, which declare credential on gemini-flash-latest: a secret the Release alone attaches arrives under the key value, so each is declared with a key of its own and no two arrive under one; the Release attaches its origin, naming this type or none. # features: # credential: # type: core/secret-value # values: # key: GOOGLE_API_KEY # The model gemini-flash-latest. gemini-flash-latest: type: core/ai-model/gemini values: model: "gemini-flash-latest"Một văn bản mà bản nháp sao chép từ một cấu hình vào Aggregate, trong một giá trị hoặc trong một chú thích, ghi mỗi
{{ thành {{`{{`}}, một action có kết quả là hai dấu ngoặc nhọn, để mô tả, và một tên chứa
hai dấu ngoặc nhọn trong một chú thích, được đọc lại đúng như đã viết khi Aggregate được đánh giá.
spec: aggregate: imported/tutor-root # manifest: left empty, since the import was given no target; an import given a target drafts the Manifest and names it here. manifest: "" components: # The configurations also hand these values to their tools and their model requests, which the application reads from its own configurations, written here for review: # code_tutor_agent tools.tutor_tools.make_snippet_runner.args.api_key: "..." # code_tutor_agent tools.tutor_tools.make_snippet_runner.args.sandbox: "python3.12" # code_tutor_agent tools.tutor_tools.make_snippet_runner.args.timeout_seconds: 20 # math_tutor_agent generate_content_config.http_options.headers: "..." # math_tutor_agent generate_content_config.http_options.timeout: 30000 tutor-root: infra: # Left for the Release, since the source cannot supply it: infra.image, the container image running the application built on ADK, holding its configurations image: "" uses: model: gemini-flash-latest: features: credential: type: core/secret-value infra: # Attached by reference, never as a value: the credential tutor-root presents to gemini-flash-latest on its model connection (the source names no variable for it, so it is read from the one Google's Gemini API's client libraries read the API key from), read from the variable GOOGLE_API_KEY, which a target substituting variable references, as Docker Compose does when the stack starts, reads from the environment, so no file carries the value. origin: "${GOOGLE_API_KEY}" gemini-flash-latest: {}Khi image đã được trả lời, instance được render chạy image đó và nhận thông tin xác thực dưới dạng GOOGLE_API_KEY, thứ mà client Gemini của ADK gửi tới Gemini API, còn mô hình được render thành một Service truy cập địa chỉ của Gemini API.
Các giá trị thông tin xác thực mà một cấu hình chứa
Một cấu hình có thể trao một khóa cho một công cụ, trong args của nó, hoặc cho các yêu cầu đến mô hình của nó, trong
http_options của generate_content_config — các header, địa chỉ và các đối số của
client của chúng. Mỗi thành phần trong args của một công cụ và trong các tùy chọn HTTP đó được ghi vào chú thích phía trên
mục của instance trong Release, đúng như cấu hình của nó ghi, và mỗi thành phần là văn bản, đối tượng hoặc
danh sách đều có thể mang một thông tin xác thực, trong khi ADK không đánh dấu thành phần nào cả: theo mặc định, mỗi thành phần được giữ nguyên như đã ghi và được nêu tên
trong một cảnh báo credential-carried theo agent và trường của nó, chẳng hạn
tools.tutor_tools.make_snippet_runner.args.api_key, không bao giờ theo giá trị của nó. Với
thiết lập empty_credentials ở all, mỗi thành phần được ghi không có giá trị và được báo cáo bằng
credential-emptied; ở marked, mỗi thành phần được giữ nguyên, vì ADK không đánh dấu thành phần nào. Một số hoặc một giá trị boolean không mang
khóa nào, và được ghi đúng như cấu hình ghi. ADK không mở rộng tham chiếu biến nào trong một
cấu hình, nên mọi giá trị đều được đọc đúng như đã ghi; tệp môi trường, nơi thường chứa khóa mà
client Gemini của ADK đọc, không bao giờ được đọc, bất kể thiết lập nói gì.
Các thiết lập nó đọc
Importer Google ADK đọc target_namespace, empty_credentials và render_mode, như
Thiết lập mô tả, và không đọc thiết lập nào khác.
Importer Agent Framework
importer/agent-framework đọc một declarative agent của Microsoft Agent Framework — tài liệu YAML thuộc kind Prompt mà một ứng dụng xây dựng trên Agent Framework dùng để nạp một agent — và tạo bản nháp một Aggregate chứa một instance của agent Agent Framework trong thư viện chuẩn, core/ai-agent/agent-framework, được nối tới mô hình OpenAI mà nó nêu tên, cùng một Release bên cạnh. Importer đọc các declarative agent, và không bao giờ đọc mã của ứng dụng. Agent Framework phát hành các gói declarative-agent của mình dưới dạng bản phát hành trước (prerelease).
Những gì nó đọc
Một declarative agent khai báo:
name,displayNamevàdescription, cácinstructionscủa nó và các schema của đầu vào và đầu ra;model—idcủa mô hình,providerphục vụ mô hình, API mà client của nó gửi yêu cầu tới (apiType), cácoptionscủa các yêu cầu, vàconnectioncủa nó: một kết nốikeytrình một khóa, được viết dướikeyhoặcapiKey, tới mộtendpoint; một kết nốiremotekết nối tới mộtendpoint; một kết nốireferencenêu tên một kết nối mà ứng dụng phân giải; hoặc một kết nốianonymouskhông trình gì cả;tools— mỗi công cụ thuộc mộtkind: mộtfunctioncó mã do ứng dụng gắn vào, một công cụweb_search,file_searchhoặccode_interpreterdo provider của mô hình chạy, hoặc một máy chủmcpđược kết nối tạiurlcủa nó, vớiapprovalModemà các lời gọi của nó áp dụng, cácallowedToolscủa máy chủ mà agent được phép gọi và mộtconnectionriêng.
Một thành phần được viết dưới dạng =Env.NAME được Agent Framework đọc từ biến môi trường NAME chỉ khi ứng dụng nạp declarative agent bằng AgentFactory(safe_mode=False), thiết lập bảo mật riêng của Agent Framework, và có sẵn một runtime .NET, còn nếu không thì được lấy làm văn bản của biểu thức đúng như được viết; mọi thành phần khác bắt đầu bằng = là một biểu thức do ứng dụng tính toán. Importer không đọc cái nào trong hai: nó nêu tên một tham chiếu theo biến của tham chiếu đó, và nêu một biểu thức là một biểu thức.
Một tệp được import riêng được đọc như một declarative agent, bất kể tên của nó là gì, và mỗi tệp mà
with.sources của importer chuyển vào được đọc như một declarative agent khác, vì vậy một lần import tạo bản nháp cho nhiều agent:
plugins: importer: - uri: importer/agent-framework:<version> with: sources: - ./agents/triage.yaml - ./agents/writer.yamlMột thư mục không bao giờ được chuyển cho importer: chữ ký của nó không nêu tên tệp nào, nên một lần import một thư mục
không nêu định dạng sẽ không nhận ra nó, còn một lần import nêu --format agent-framework sẽ bị từ chối theo
An importer that declares no file patterns is handed a directory (Một importer không khai báo mẫu tệp nào được chuyển cho một thư mục)
trước khi bất kỳ tệp nào trong đó được mở. Thay vào đó, hãy import từng declarative agent như một tệp riêng. Một nguồn
mà từ đó Agent Framework không dựng được prompt agent nào — nguồn có kind không phải Prompt, ở bất kỳ kiểu chữ hoa thường nào,
cũng không phải Agent — được báo cáo dưới no-nodes. Mã của ứng dụng — chương trình nạp từng
declarative agent và các hàm mà nó gắn vào các công cụ — không bao giờ nằm trong số các nguồn:
ứng dụng tự nạp các declarative agent của mình, từ image mà Release nêu tên.
Một declarative agent trở thành gì
aggregate.yaml, một Aggregate nháp được đặt tên theo agent, như Cách đặt tên bản nháp mô tả, chứa, cho mỗi declarative agent và theo khóa là tên của nó, một instance của core/ai-agent/agent-framework với:
display_namevàdescription, làdisplayNamevàdescriptioncủa agent, nếu agent có nêu chúng;- kết nối
modelcủa nó, được nối tới mô hình mà nó nêu tên, nếu mô hình đó được nối.
Các chỉ dẫn, các schema của đầu vào và đầu ra, template, metadata và các tùy chọn của các yêu cầu tới mô hình được ứng dụng đọc từ declarative agent, và được nêu tên trong một chú thích phía trên instance. Một công cụ hàm, một công cụ do provider của mô hình chạy và một công cụ thuộc bất kỳ kind nào khác cũng được nêu tên trong một chú thích, và được báo cáo trong một quyết định không chọn gì cả.
Một mô hình có provider là OpenAI và nêu một id là một instance của core/ai-model/openai,
phục vụ id đó và có khóa là id đó: socket model của agent chấp nhận một mô hình phục vụ API OpenAI, và
runtime cung cấp địa chỉ, tên và khóa của mô hình đó trong các biến mà các client OpenAI của Agent Framework
đọc. Các agent nêu cùng một mô hình tại cùng một địa chỉ dùng chung một instance. Nếu catalog của workspace
không có core/ai-model/openai, một mô hình sẽ được tạo bản nháp, <target_namespace>/ai-model/openai, mang
nhãn model.aggrega.ai/api: openai mà socket model của agent chọn, và quyết định của nó nói rõ điều đó; một
Recipe công bố endpoint và mô hình của nó được để lại cho bạn, như một chú thích ở đầu nó cho biết. Một id
được viết dưới dạng tham chiếu để lại values.model của mô hình cho bạn, với một chú thích phía trên mô hình nêu tên
biến; bản build dừng lại và nêu tên nó cho đến khi nó được đặt. Một kết nối anonymous được viết thành
unauthenticated: true của kết nối. Một mô hình của bất kỳ provider nào khác — AzureOpenAI, Anthropic — một mô hình
nêu provider của nó dưới dạng tham chiếu hoặc không nêu provider nào, trong trường hợp đó Agent Framework dùng provider mặc định mà
ứng dụng đặt, và một mô hình không nêu id nào đều không được nối tới gì cả, và một chú thích phía trên instance giải thích
lý do; bản build dừng lại và nêu tên socket model cho đến khi có một mô hình được nối.
Một công cụ thuộc kind mcp không được tạo bản nháp thành Component nào hay kết nối nào: Agent Framework gửi máy chủ tới nhà cung cấp của mô hình dưới dạng một công cụ được lưu trữ (hosted tool), và chính nhà cung cấp, không phải ứng dụng, kết nối tới máy chủ tại url của nó, vì vậy địa chỉ này phải truy cập được từ nhà cung cấp, nên không có gì mà bản nháp triển khai kết nối tới nó. Một chú thích phía trên instance của agent nêu tên máy chủ, nói rõ điều đó, và nêu mô tả, approvalMode và allowedTools mà declarative agent nêu cho máy chủ; url của máy chủ được viết, đầy đủ, trong chú thích phía trên mục của agent trong Release, và quyết định của nó không chọn gì cả.
release.yaml, bên cạnh nó, là một Release nháp cùng tên nêu tên Aggregate đó. Mục của agent ghi infra.image của agent — image chạy ứng dụng xây dựng trên Agent Framework, chứa declarative agent của nó — ở dạng trống, dưới một chú thích cho biết nó là gì, và lần nhập ghi nhận nó là giá trị còn thiếu. Với --target compose, mục đó cũng ghi infra.published_port, 8000, cổng mà infra.port của Component chỉ định mặc định cho ứng dụng, được Recipe Compose của nó công bố trên địa chỉ loopback của máy chủ, 127.0.0.1, dưới chú thích cho biết dịch vụ chỉ có thể truy cập từ máy này, bởi bất kỳ tiến trình nào chạy trên máy, và việc xóa dòng đó giữ dịch vụ ở dạng nội bộ. Khi mô hình của agent đã được nối, mục gắn thông tin xác thực mà agent trình cho mô hình đó dưới credential trên kết nối model của nó, bằng tham chiếu và không bao giờ dưới dạng giá trị: được đọc từ biến mà declarative agent nêu tên cho khóa của nó, viết là =Env.NAME, và nếu không thì từ OPENAI_API_KEY, biến mà các thư viện client của OpenAI đọc khóa từ đó; dưới dạng tham chiếu ${…} trên mọi target trừ helm, và trên helm dưới dạng tên của một Kubernetes Secret, được ghi trống để lần nhập ghi nhận là còn thiếu; trên compose, kết nối model khai báo nó với khóa đó. Các giá trị mà declarative agent nêu cho mô hình và các máy chủ MCP của nó — các khóa, và url của từng máy chủ — được viết trong một chú thích phía trên mục của agent, như Các giá trị thông tin xác thực mà một declarative agent chứa mô tả. Mỗi mô hình đã nối có một mục, nên Release đặt nó cùng với agent. Endpoint mà kết nối của nó nêu được viết thành infra.endpoint của mô hình, và một endpoint được viết dưới dạng tham chiếu được nêu tên bên cạnh mục của nó, địa chỉ riêng của Component được dùng cho đến khi nó được đặt; một kết nối không nêu endpoint nào để mục đó không chứa hạ tầng nào, địa chỉ riêng của Component vẫn giữ nguyên. Giống như mọi Release được phác thảo, nó ghi metadata.environment là development và, khi không có target, một spec.manifest trống mà lần nhập ghi nhận là còn thiếu; khi được cung cấp một target, lần nhập phác thảo Manifest, như Một target bổ sung những gì mô tả.
Declarative agent mà các bài kiểm thử của importer này import, thuộc provider OpenAI với một kết nối khóa, một máy chủ MCP trình một khóa riêng, một công cụ hàm và một công cụ tìm kiếm web, được import như một tệp riêng, được tạo bản nháp, không có thiết lập nào, dưới name của nó, LearnAgent, như sau:
# Not read: the application's code, which loads each declarative agent and binds the functions of its function tools; the application runs in the image the Release names for each instance, and loads its declarative agents itself.apiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: imported/learnagent version: 0.1.0 description: Draft Aggregate imported from a source in the agent-framework format.spec: components: # The declarative agent LearnAgent. # Read by the application from the declarative agent, and taken by no key of core/ai-agent/agent-framework: instructions, outputSchema, the options of its model requests (temperature, topP). # Function tools, whose code the application binds, drafted as no Component: GetRelease. # Tools the model's provider runs, drafted as no Component: search. # The MCP server microsoft_learn, drafted as no Component and no connection, since Agent Framework sends it to the model's provider as a hosted tool, and the provider, not the application, reaches it at its url, which must therefore be reachable from the provider; its url is written above learnagent's entry in the Release. # Stated by the declarative agent for microsoft_learn: its description, "Get information from Microsoft Learn."; its approval mode, never; the tools of the server it allows, microsoft_docs_search, microsoft_docs_fetch. learnagent: type: core/ai-agent/agent-framework values: display_name: "Learn Assistant" description: "Answers questions about {{`{{`}} product }} from the Microsoft Learn content." uses: model: gpt-4-1-mini: target: gpt-4-1-mini # For the compose target only, uncomment the lines below, which declare credential on gpt-4-1-mini: a secret the Release alone attaches arrives under the key value, so each is declared with a key of its own and no two arrive under one; the Release attaches its origin, naming this type or none. # features: # credential: # type: core/secret-value # values: # key: OPENAI_API_KEY # The model gpt-4.1-mini, which LearnAgent names with the OpenAI provider. gpt-4-1-mini: type: core/ai-model/openai values: model: "gpt-4.1-mini"Một văn bản mà bản nháp sao chép từ một declarative agent vào Aggregate, trong một giá trị hoặc trong một chú thích, viết
mỗi {{ thành {{`{{`}}, để nó đọc lại đúng như nguyên bản sau khi Aggregate được đánh giá.
spec: aggregate: imported/learnagent # manifest: left empty, since the import was given no target; an import given a target drafts the Manifest and names it here. manifest: "" components: # The declarative agent also states these values for its model and its MCP servers, written here for review: # - model.connection.key: "..." # - tools.microsoft_learn.url: "https://learn.microsoft.com/api/mcp?session=..." # - tools.microsoft_learn.connection.key: "..." learnagent: infra: # Left for the Release, since the source cannot supply it: infra.image, the container image running the application built on Agent Framework, holding its declarative agent image: "" uses: model: gpt-4-1-mini: features: credential: type: core/secret-value infra: # Attached by reference, never as a value: the credential learnagent presents to gpt-4-1-mini on its model connection (the source names no variable for it, so it is read from the one OpenAI's client libraries read the API key from), read from the variable OPENAI_API_KEY, which a target substituting variable references, as Docker Compose does when the stack starts, reads from the environment, so no file carries the value. origin: "${OPENAI_API_KEY}" gpt-4-1-mini: infra: endpoint: "https://llm-gateway.example.com/v1"Khi image đã được trả lời, agent được render chạy image đó và được cung cấp endpoint của mô hình dưới dạng OPENAI_BASE_URL, id của mô hình dưới dạng OPENAI_MODEL và thông tin xác thực của nó dưới dạng OPENAI_API_KEY, và mô hình được render thành một Service kết nối tới host của nó. Không biến nào mang địa chỉ của máy chủ MCP: chính nhà cung cấp của mô hình, không phải ứng dụng, kết nối tới nó.
Các giá trị thông tin xác thực mà một declarative agent nắm giữ
Khóa mà một kết nối key trình ra — được viết dưới key hoặc apiKey, trên mô hình hoặc trên một máy chủ MCP — là thành phần duy nhất mà Agent Framework đánh dấu là thông tin xác thực: đó là giá trị duy nhất mà trình nạp của nó che đi khỏi những gì nó ghi log. Mỗi khóa mà một declarative agent viết dưới dạng literal được viết vào chú thích phía trên mục của agent trong Release, đúng như declarative agent viết nó, và theo mặc định được mang theo nguyên văn và được nêu tên trong một cảnh báo credential-carried theo agent và trường của nó, chẳng hạn model.connection.key, không bao giờ theo giá trị của nó. url của một máy chủ MCP, được viết đầy đủ trong cùng chú thích đó và được nêu tên theo trường của nó — tools.microsoft_learn.url of node LearnAgent is carried as written — là một thành phần trong cấu hình của một máy chủ MCP, và endpoint của một mô hình đã được nối là một đầu vào mà Agent Framework đánh dấu không phải thông tin xác thực. Với thiết lập empty_credentials ở marked, các khóa và các url của các máy chủ MCP được viết mà không có giá trị — chú thích chỉ nêu tên mỗi cái theo trường của nó — và được báo cáo với credential-emptied, còn endpoint của mô hình được mang theo; ở all, infra.endpoint của mô hình cũng bị bỏ ra, được nêu tên trong chú thích phía trên mục của nó là để lại cho Release, và địa chỉ mặc định của Component được dùng cho đến khi nó được đặt. Một giá trị được viết dưới dạng =Env.NAME không chứa giá trị nào, nên nó được nêu tên theo biến của nó, cùng với điều kiện mà theo đó Agent Framework đọc nó từ môi trường — model.connection.key, written as =Env.OPENAI_API_KEY, which Agent Framework reads … — bất kể thiết lập nói gì, và không được báo cáo dưới mã nào trong hai mã trên; một giá trị được viết dưới dạng bất kỳ biểu thức nào khác được nêu tên là một biểu thức và không bao giờ được viết ra.
Các thiết lập nó đọc
Importer Agent Framework đọc target_namespace, empty_credentials và render_mode, như Thiết lập mô tả chúng, và không đọc thiết lập nào khác.
Một target bổ sung những gì
Một lần import được cung cấp một target — --target trên aggrega import, hoặc target trên công cụ import của trợ lý và phương thức aggrega/import của phiên, nêu tên một năng lực của provider như compose hoặc helm — sẽ chuyển target đó cho importer, nên importer phác thảo cho target đó: mỗi secret ở dạng mà target đó đọc, và các dòng chỉ target đó cần được ghi ở trạng thái có hiệu lực, còn các dòng chỉ một target khác cần thì bị lược bỏ. Trên compose, các dòng đó bao gồm infra.published_port ở bất cứ đâu importer công bố một dịch vụ trên địa chỉ loopback của máy chủ, như phần của từng importer nêu; một cổng do importer chọn không bao giờ lấy số mà một cổng khác của Release đã lấy. Sau đó lần import phác thảo Manifest bên cạnh những gì importer đã phác thảo, dù importer nào đã chạy: manifest.yaml, nằm bên cạnh Release đã phác thảo và được đặt tên, đánh phiên bản như Release đó — hoặc, khi importer không phác thảo Release nào, nằm bên cạnh Aggregate đã phác thảo và được đặt tên, đánh phiên bản như Aggregate đó.
Với mỗi loại component và mỗi loại feature mà các bản phác thảo cần — trên các component của Aggregate đã phác thảo, các kết nối của chúng và các hệ thống con của nó, trên các Aggregates của catalog mà nó kết hợp, như core/dify, và trên các phần đính kèm của Release đã phác thảo — Manifest ánh xạ loại đó tới Recipe, hoặc với một loại feature là feature recipe, của năng lực đó mà catalog của workspace cung cấp cho loại ấy: cái duy nhất hiện có, nhiều phiên bản của cùng một cái được tính là một; hoặc, khi có nhiều cái mang tên khác nhau, cái được đặt theo tên của chính loại đó, như helm/postgres cho core/datastore/postgres. Một loại không có cái nào, hoặc có nhiều cái nhưng không cái nào được đặt tên như vậy, sẽ không được ánh xạ, một cảnh báo nêu tên nó và lý do, và một lần build các bản phác thảo sẽ dừng lại, nêu tên từng instance hoặc phần đính kèm của loại đó cho đến khi bạn ánh xạ nó.
Khi chỉ importer biết Recipe nào trong số nhiều Recipes được áp dụng, nó tự phác thảo Manifest — MCP importer ánh xạ mỗi server, theo khóa của nó, tới phần hiện thực của cách server đó chạy, và một importer gắn một secret theo tên sẽ ánh xạ core/referenced-secret tới helm/k8s-existing-secret — và lần import hoàn thiện nó: mỗi ánh xạ do importer viết mà catalog cung cấp cho loại và năng lực đó được giữ lại, mọi ánh xạ khác bị loại bỏ kèm một cảnh báo, và các loại mà nó để lại được ánh xạ như trên.
spec.manifest của Release đã phác thảo, được ghi trống khi không có target, được đặt thành tên của Manifest, chú thích phía trên nó bị bỏ đi, và không có gì khác trong Release thay đổi. aggrega import mô tả đầy đủ điều này.
Thiết lập
Một importer nhận các thiết lập của mục plugins.importer gắn nó vào, dưới
with.settings, như Importer nào biến một nguồn thành bản nháp
mô tả. Khi không có mục nào, hoặc không có thiết lập nào, mọi thiết lập nhận giá trị mặc định.
plugins: importer: - uri: importer/langflow:<version> with: settings: target_namespace: payments reuse_mode: hints-only| Thiết lập | Mặc định | Chức năng |
|---|---|---|
target_namespace | imported | Namespace mà các thực thể được phác thảo được đặt tên bên dưới: <target_namespace>/<category>/<name> cho một Component, và <target_namespace>/<name> cho Aggregate và Release, trong đó <name> là tên riêng của nguồn, nếu không có thì là tên thư mục của nó hoặc tên tệp của nó không kèm phần mở rộng, nếu vẫn không có thì là flow, được viết bằng chữ thường với mỗi chuỗi ký tự khác chữ cái và chữ số ASCII được thay bằng một dấu gạch nối, như Cách đặt tên một bản phác thảo mô tả. |
reuse_mode | auto-apply-above-threshold | auto-apply-above-threshold tham chiếu Component của catalog khớp nhất cho một node mà bản nháp cấp cho một Component riêng, khi kết quả khớp thuộc bậc cao và đạt điểm bằng hoặc cao hơn reuse_threshold, và soạn nháp mọi node còn lại. hints-only soạn nháp mọi node như vậy và không tham chiếu Component nào của catalog, ghi lại một kết quả khớp mạnh dưới dạng gợi ý. Mọi giá trị khác được đọc là hints-only. |
reuse_threshold | 0.85 | Điểm mà từ mức đó trở lên auto-apply-above-threshold tham chiếu một Component. Chỉ được đọc trong chế độ đó; 0 được đọc là giá trị mặc định. |
emit_hints | true | Tệp của một Component được soạn nháp có mở đầu bằng một chú thích nêu tên Component của catalog mà nó giống hay không, đối với kết quả khớp bậc cao hoặc bậc trung bình. Aggregate nháp mang cùng chú thích đó phía trên mục của node ấy, và phía trên một mục được tham chiếu là một chú thích nêu tên ứng viên tốt thứ hai có thể thay thế cho nó, hoặc cho biết không ứng viên nào đạt điểm trên 0. false bỏ các chú thích này. |
render_mode | human | human ghi các bản nháp mô tả ở trên. llm không ghi bản nháp nào, mà thay vào đó ghi toàn bộ hồ sơ quyết định — mọi node, các ứng viên được cân nhắc và lựa chọn được đưa ra — thành một tài liệu duy nhất, import-decisions.json, để một công cụ khác đọc. Mọi giá trị khác được đọc là human. |
mapping_overrides | không có | Các ánh xạ được xếp chồng lên bảng riêng của importer, được khóa theo định dạng rồi theo loại node — với importer Compose là theo kho image. Mỗi mục nêu tên component mà một node thuộc loại đó ánh xạ tới và, tùy chọn, category của nó, các traits — nhãn và giá trị của chúng — mà một Component khớp mang, và một từ vendor có trong tên của nó. Một mục cho loại node mà bảng đã ánh xạ sẽ thay thế hàng của bảng. Chỉ các mục dưới định dạng đang được nhập mới được đọc. |
layout | platform | platform soạn nháp nền tảng chạy flow, mang theo flow, với mỗi phần của nó là một Component riêng được nối với nền tảng, như Nền tảng mang flow mô tả. nodes soạn nháp mọi node thành một Component riêng, như Từng node một mô tả. Với importer Dify, platform soạn nháp bản cài đặt Dify mang ứng dụng, như Một ứng dụng trở thành gì mô tả. Mọi giá trị khác được soạn nháp như platform, và quá trình nhập cảnh báo bằng unknown-layout. |
empty_credentials | none | Những giá trị thông tin xác thực nào được ghi rỗng trong flow mà nền tảng mang, như Các giá trị thông tin xác thực mà flow chứa liệt kê, trong Release mà importer MCP soạn nháp, như Các giá trị thông tin xác thực mà một server chứa liệt kê, trong Release mà importer Compose soạn nháp, như Các giá trị thông tin xác thực mà một service chứa liệt kê, trong ứng dụng mà importer Dify mang, như Các giá trị thông tin xác thực mà một ứng dụng chứa liệt kê, trong Release mà importer CrewAI soạn nháp, như Các giá trị thông tin xác thực mà một khai báo chứa liệt kê, trong Release mà importer LangGraph soạn nháp, như Môi trường mà một cấu hình nêu liệt kê, trong Release mà importer Google ADK soạn nháp, như Các giá trị thông tin xác thực mà một cấu hình chứa liệt kê, và trong Release mà importer Agent Framework soạn nháp, như Các giá trị thông tin xác thực mà một agent khai báo chứa liệt kê. none không ghi rỗng giá trị nào: mỗi giá trị được mang nguyên như đã viết và được nêu tên trong một cảnh báo credential-carried. marked ghi rỗng những gì một định dạng đánh dấu là thông tin xác thực và mọi thành phần trong cấu hình của một server MCP. all ghi rỗng thêm cả các đầu vào mà một định dạng đánh dấu là không phải thông tin xác thực nhưng có thể chứa thông tin xác thực — header của yêu cầu, tham số truy vấn, một yêu cầu được viết dưới dạng dòng lệnh, một đầu vào được đặt tên theo một khóa. Những gì bản nháp ghi để một node kết nối được tới kết nối của nó vẫn được ghi bất kể thiết lập này. Mọi giá trị khác làm dừng quá trình nhập, không soạn nháp gì, với unknown-empty-credentials. Bản nháp tạo theo từng node không đọc giá trị nào, nên cũng không đọc thiết lập này. |
attach_egress_allowlist | false | true gắn Feature core/egress-allowlist của thư viện chuẩn vào mỗi instance nền tảng mà bản nháp ghi, dưới tên egress-allowlist, không thiết lập infra nào của nó, như Những gì bản nháp để lại cho Release mô tả. false không gắn gì. Một bản nháp không ghi nền tảng nào, dưới layout: nodes, và bản nháp của importer Dify, có mục cho bản cài đặt Dify không nhận Feature nào, đều không gắn gì bất kể thiết lập này, và khi nó là true thì quá trình nhập cảnh báo bằng feature-not-attached. Mọi giá trị không phải boolean được đọc là false. |
Một thiết lập mà importer không biết sẽ bị bỏ qua.
with: settings: mapping_overrides: langflow: AzureOpenAIModel: component: acme/ai-model/azure-openai category: ai-model vendor: azureNhững gì một lần nhập báo cáo
Mỗi importer lõi báo cáo những gì nó không thể làm, và những gì nó đã làm thay cho tác giả, dưới dạng
chẩn đoán. Lệnh in từng chẩn đoán ra standard error dưới dạng <severity>: <message>, trước dòng dành cho
mỗi node; phương thức aggrega/import của phiên trình soạn thảo và công cụ import của trợ lý trả về từng chẩn đoán
kèm theo code của nó.
| Mã | Mức độ | Được báo cáo khi |
|---|---|---|
parse-failed | halt | Nguồn không phân tích được: trình phân tích của nó từ chối nguồn, và thông báo mang lý do của trình phân tích. |
no-nodes | warn | Nguồn không chứa node nào mà importer nhận ra — với importer MCP là không có server nào, với importer Compose là không có service và không có model nào, với importer CrewAI là một crew không khai báo agent nào, với importer LangGraph là một cấu hình không khai báo graph nào, với importer Google ADK là một cấu hình gốc không khai báo agent nào, hoặc mỗi tệp mà with.sources giao cho một lần nhập đều không chứa cấu hình gốc nào, và với importer Agent Framework là một nguồn không khai báo prompt agent nào. |
unknown-layout | warn | layout không phải platform cũng không phải nodes; flow được soạn thảo như platform. |
unknown-empty-credentials | halt | empty_credentials chứa một giá trị khác none, marked hoặc all, được nêu tên cùng với thiết lập; lần nhập không soạn thảo gì. |
platform-not-in-catalog | warn | Catalog của workspace không chứa Component nào mang tên của nền tảng, nên không có phần nào được nối với nó; với importer Dify là không có core/ai-agent/dify, và core/dify vẫn được kết hợp như thường. |
part-not-placed | warn | Một phần của flow không được nối với socket nào của nền tảng, kèm lý do; nó vẫn nằm trong flow. |
socket-selector-unreadable | warn | Bộ chọn mà một socket của nền tảng khai báo không đọc được, nên không có phần nào được nối với nó; một lần cho mỗi socket. |
credential-carried | warn | Một giá trị thông tin xác thực được mang nguyên như đã viết trong flow mà bản nháp mang, hoặc trong Release mà importer MCP, Compose, CrewAI, LangGraph, Google ADK hoặc Agent Framework soạn thảo, được nêu tên theo node của nó — hoặc server, service, agent hay cấu hình của nó — và trường của nó, không bao giờ theo giá trị của nó, kèm giá trị empty_credentials sẽ ghi nó thành rỗng. |
credential-emptied | warn | Một giá trị thông tin xác thực được ghi thành rỗng trong flow mà bản nháp mang, hoặc trong Release mà importer MCP, Compose, CrewAI, LangGraph, Google ADK hoặc Agent Framework soạn thảo, ở nơi empty_credentials yêu cầu, được nêu tên theo node của nó — hoặc server, service, agent hay cấu hình của nó — và trường của nó. |
carriage-returns-rewritten | warn | Các ký tự carriage return của flow được ghi thành line feed, kèm số lượng. |
definition-respelled | warn | Các giá trị của luồng được viết theo cách viết mà chính các công cụ của nền tảng dùng để đọc chúng, vẫn là các giá trị ấy, kèm theo đó là những giá trị nào và lý do: các handle cạnh của một luồng Langflow, được viết như trình soạn thảo của Langflow viết chúng. Một giá trị mà bản nháp viết để luồng tới được một phần, hoặc một giá trị có thể mang thông tin xác thực, không bao giờ bị viết lại — nó vẫn là giá trị của phần nối dây, hoặc của empty_credentials — và cảnh báo đếm từng giá trị không được viết lại. |
definition-not-carried | warn | Flow không được mang trong values.flow_definition, hoặc ứng dụng của importer Dify không được mang trong parameters.app_definition, kèm lý do. |
part-reads-connection | warn | Cách flow tiếp cận một phần đã nối thông qua kết nối của nó, hoặc cách một kết nối tiếp cận một node mà bản nháp không nối với socket nào như nó được viết. |
part-address-in-flow | warn | Flow tiếp cận một phần đã nối theo cách khác ngoài kết nối của nó, kèm cách thức. |
model-not-named | warn | values.model của một phần được tham chiếu được để lại cho tác giả, kèm lý do. |
feature-attached | info | attach_egress_allowlist đã gắn core/egress-allowlist vào một nền tảng được soạn thảo, kèm những gì của nó mà Release thiết lập; một lần cho mỗi instance nền tảng. |
feature-not-attached | warn | attach_egress_allowlist là true và bản nháp không ghi nền tảng nào, hoặc kết hợp bản cài đặt Dify, mà mục của nó không nhận Feature nào, nên không có gì được gắn. |
part-configured-in-platform | warn | Một node của ứng dụng Dify nêu tên thứ mà Dify tự cấu hình — một model và provider của nó, một công cụ, một cơ sở tri thức, một chiến lược agent, một plugin — nên bản nháp không nối phần nào cho nó. |
dsl-version-newer | warn | Một ứng dụng Dify được viết bằng một phiên bản DSL mới hơn phiên bản mà phiên bản Dify do core/ai-agent/dify chạy theo mặc định ghi ra. |
Một lần nhập được cung cấp target sẽ báo cáo, sau các chẩn đoán của importer, những gì việc soạn thảo Manifest phát hiện: một warn nêu tên mỗi loại component hoặc feature mà Manifest để lại chưa ánh xạ và lý do, và một info khi Release được soạn thảo đã nêu tên một Manifest hoặc không có Release được soạn thảo nào tham chiếu nó. Đó là chẩn đoán của chính lần nhập chứ không phải của một importer, và không mang mã nào; Một target bổ sung những gì mô tả chúng. Sau đó mọi lần nhập đều báo cáo, cũng như của chính nó, một warn cho mỗi giá trị mà các bản nháp vẫn còn thiếu, nêu tên tệp nháp, đường dẫn khóa và mô tả của nó, và, dưới --offline, khi nó đã soạn thảo một Release và không còn thiếu gì, một info nêu tên lệnh aggrega pull cần chạy tiếp theo, như Tệp câu trả lời của lần nhập mô tả.
Được phát hành cùng mỗi bản phát hành của trình biên dịch
Mỗi bản phát hành của trình biên dịch xây dựng mười importer từ mã nguồn đã được gắn thẻ và sinh các thực thể Plugin
của chúng từ chính các importer, nên khả năng, các chữ ký nhận diện, các hàm host
và phần mô tả của một thực thể là những gì importer của nó báo cáo. Bản phát hành ký và công bố cả mười,
importer/langflow, importer/flowise, importer/n8n, importer/mcp, importer/compose, importer/dify, importer/crewai, importer/langgraph, importer/google-adk và importer/agent-framework ở phiên bản của bản phát hành, bên cạnh các
plugin lõi khác, và ghi lại các thực thể của chúng cùng với các thực thể của các plugin lõi khác cho catalog
tiêu chuẩn.