Thiết lập agent

Last updated 6 thg 11, 2026 Xem dưới dạng Markdown Thiết lập tác nhân

Kết nối AstroWay API với AI agent qua MCP (Model Context Protocol). Danh mục có sẵn theo hai cách, cả hai đều dùng key aw_test_* / aw_live_* của bạn:

Hosted (HTTP): https://mcp.astroway.info/mcp, không cần cài đặt, xác thực bằng Bearer token.
Stdio (npx): npx @astroway/mcp, tiến trình con chạy cục bộ, xác thực qua biến môi trường, hoạt động offline.

Nhận key miễn phí trong dashboard, sau đó chọn client của bạn.

Một domain thay vì cả danh mục

843 tool trong một phản hồi là 3.4 MB mà agent phải đọc hết trước khi chọn được một tool. Phần lớn client bỏ cuộc từ lâu trước đó.

https://mcp.astroway.info/mcp/<domain> chỉ trả về một lĩnh vực thay vì tất cả. Config giữ nguyên, chỉ URL thay đổi.

Domain	URL	Số tool	Kích thước `tools/list`
Lõi chiêm tinh	`/mcp/core`	104	389 KB
Chiêm tinh Vệ Đà	`/mcp/vedic`	192	970 KB
Huyền học Trung Hoa	`/mcp/chinese`	60	202 KB
Hy Lạp hóa và truyền thống	`/mcp/hellenistic`	59	240 KB
Tarot	`/mcp/tarot`	79	209 KB
Thần số học	`/mcp/numerology`	64	158 KB
Human Design	`/mcp/human-design`	27	125 KB
Dự báo	`/mcp/forecast`	43	209 KB
Quan hệ	`/mcp/relationships`	42	247 KB
Tâm lý	`/mcp/psychological`	28	107 KB
Bói toán và huyền bí	`/mcp/divination`	79	185 KB
Luận giải ứng dụng	`/mcp/applied`	45	148 KB
Báo cáo	`/mcp/reports`	42	209 KB
Nền tảng	`/mcp/platform`	42	119 KB

Đo trên production ngày 2026-09-21. /mcp vẫn trả về toàn bộ danh mục, nên không có gì đã cấu hình trước đây bị hỏng. Kiểm tra số dư và ước tính chi phí một lần gọi có trong mọi domain, vì một agent chỉ giới hạn ở chiêm tinh Vệ Đà vẫn cần biết một lần gọi tốn bao nhiêu.

GET /domains trả về chính danh sách này dưới dạng JSON, không cần key. Domain không tồn tại là lỗi 404 kèm danh sách các domain thật, chứ không lặng lẽ trả về cả 843 tool.

Tài liệu không cần key: `/mcp/docs`

Câu hỏi đầu tiên của agent không bao giờ là “tính bản đồ sao”. Nó là “API này làm được gì, một lần gọi trông như thế nào và tôi sẽ tốn bao nhiêu”. Cả ba câu đều trả lời được mà không cần key: https://mcp.astroway.info/mcp/docs không tiêu tốn credit nào, nên cũng không yêu cầu xác thực.

Tool	Chức năng
`find_endpoint`	Tìm trong toàn bộ 770 operation. Với mỗi operation trả về method, URL, giá bằng credit, gói, các trường body bắt buộc và liên kết tới tài liệu tham khảo
`search_docs`	Tìm trong 281 trang hướng dẫn, tiếng Ukraina và tiếng Anh, kèm danh sách các mục của từng trang
`read_doc`	Trả về một trang dưới dạng markdown
`list_docs`	Toàn bộ mục lục, nhóm theo chuyên mục

700 trong số 770 operation có giá, 37 operation khác được đánh dấu là trả lời mà không cần key. Nghĩa là có thể tính chi phí của một kịch bản trước cả khi có tài khoản.

curl https://mcp.astroway.info/mcp/docs \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"find_endpoint","arguments":{"query":"solar return","limit":2}}}'

read_doc chỉ đọc những trang có trong mục lục. Mọi đường dẫn khác đều bị từ chối, và không có request nào được gửi ra ngoài.

Yêu cầu ít hơn toàn bộ phản hồi

Mỗi tool nhận thêm hai tham số ngoài các tham số riêng của nó: fields (danh sách đường dẫn phân tách bằng dấu phẩy, tính từ data) và precision (giữ bao nhiêu chữ số thập phân). Chúng được chuyển vào cùng API như khi gọi qua REST, và chênh lệch về token không phải chuyện nói suông.

Gọi bản đồ sao cá nhân qua MCP	Byte
không tham số, như trước 21.09.2026	91 737
không tham số, hôm nay	72 484
`precision: 2`	61 356
`fields: "planets.name,planets.longitude,houses.cusp"` cộng `precision: 2`	1 182

Đo trên production ngày 2026-09-21. Số credit như nhau ở cả bốn dòng: người đọc phản hồi mới là người trả cho phần chênh lệch.

Đường dẫn không khớp với trường nào sẽ được trả lại trong _fields_unmatched. Một danh sách không khớp được gì là 400 FIELDS_UNKNOWN kèm danh sách, chứ không phải phản hồi rỗng. Mô tả đầy đủ cả hai tham số: quy ước API.

Chọn client của bạn

Claude Desktop Hosted MCP qua config

Claude Code Một lệnh CLI

Cursor Hosted MCP qua config

VS Code Copilot Chat, Agent mode

Windsurf Cascade MCP

Cline Gói npx stdio

Codex CLI Gói npx stdio

CI / raw HTTP

Hoàn toàn không cần client - endpoint hosted nói JSON-RPC qua HTTP. Liệt kê tool với Bearer token:

curl https://mcp.astroway.info/mcp \
-H "Authorization: Bearer aw_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Function calling không cần MCP

Nếu agent của bạn dùng function calling của OpenAI hoặc Anthropic chứ không phải MCP, hãy yêu cầu API trả về định nghĩa tool có sẵn và truyền thẳng cho model. Chúng được sinh ra từ tài liệu OpenAPI, nên schema mà model điền vào chính là schema mà endpoint kiểm tra.

curl "https://api.astroway.info/v1/agent/tools?format=openai" \
-H "X-Api-Key: aw_live_YOUR_KEY"

Phản hồi gồm hai nửa. tools khớp chính xác với hợp đồng của nhà cung cấp và không mang theo gì của chúng tôi, nên có thể đưa thẳng vào lời gọi model: một key thừa bên trong object tool là lỗi 400 phía họ. executors cho biết cách thực thi từng tool và có đúng những key mà model sẽ trả về:

{
"tools": [
  { "type": "function", "function": { "name": "astroway_post_chart", "description": "Natal chart...",
    "parameters": { "type": "object", "required": ["date", "time", "latitude", "longitude"], "properties": { "...": {} } } } }
],
"executors": {
  "astroway_post_chart": { "method": "POST", "path": "/v1/chart", "credits": 20, "group": "Core" }
},
"count": 26, "totalMatched": 26, "totalAvailable": 751, "truncated": false
}

Sau đó executor của bạn chỉ còn năm dòng: tìm tên trong executors, gửi các argument của model dưới dạng JSON body tới đường dẫn đó kèm X-Api-Key của bạn, trả phản hồi về cho model. Không tool nào chứa thông tin xác thực, nên danh sách này an toàn để cache.

Bạn chọn những gì model nhìn thấy. Mặc định là bộ khởi đầu gồm 26 tool được tuyển chọn, không phải cả danh mục: OpenAI giới hạn một request ở 128 function, và model bắt đầu chọn kém đi từ lâu trước giới hạn đó. Thu hẹp hoặc mở rộng bằng select=all, select=group:Vedic, select=paths:/chart,/synastry, lọc bên trong bằng q=, giới hạn bằng limit= (tối đa 128). Không gì biến mất một cách lặng lẽ: totalMatched và notes cho biết những gì còn nằm ngoài. Thêm format=anthropic để nhận { name, description, input_schema }.

Lời gọi này miễn phí và không tiêu tốn credit.

Dùng key model của riêng bạn

Trên các endpoint mà chúng tôi sinh văn bản, bạn có thể tự trả tiền token. Hai header, gửi cả hai hoặc không gửi cái nào:

curl https://api.astroway.info/v1/ai/explain-aspect \
-H "X-Api-Key: aw_live_YOUR_KEY" \
-H "X-Provider: anthropic" \
-H "X-Provider-Key: sk-ant-YOUR_PROVIDER_KEY" \
-H "Content-Type: application/json" \
-d '{"planet1":"Saturn","planet2":"Moon","aspectType":"Square"}'

X-Provider là một trong openai, anthropic, google, groq, mistral, openrouter, deepseek, together; địa chỉ của từng nhà cung cấp được cố định phía chúng tôi và không bao giờ lấy từ request. X-Provider-Model là tùy chọn và ghi đè model mặc định.

Không có fallback sang chuỗi của chúng tôi. Nếu key của bạn không hoạt động, bạn nhận được status và thông báo của nhà cung cấp, chứ không phải một phản hồi do chúng tôi trả tiền: fallback lặng lẽ sẽ tiêu token của chúng tôi cho một request mà bạn cho là của mình, và không thể nào nhận ra điều đó.

Lời gọi như vậy tốn 5 credit thay cho giá của endpoint. Chúng tôi vẫn tính bản đồ, dựng prompt và chạy các cơ chế bảo vệ; phần completion là do bạn mua.

Key của bạn không được ghi log, không được lưu và không được cache ở bất kỳ đâu. Nó đi qua header, vì body của request được hash thành hai cache key, còn nhật ký request của chúng tôi hoàn toàn không ghi header. Lỗi từ nhà cung cấp có trích dẫn key của bạn sẽ được che đi trước khi vào log của chúng tôi hay phản hồi của bạn. Lời gọi dùng key của bạn bỏ qua cả hai cache theo cả hai chiều: nó không bao giờ nhận phản hồi do chúng tôi tạo, và phản hồi của nó không bao giờ đến tay người khác.

Các header có trong đặc tả. Mọi đường dẫn chấp nhận chúng đều khai báo X-Provider, X-Provider-Key và X-Provider-Model trong /v1/openapi.json, nên client được sinh tự động sẽ nối chúng như bất kỳ tham số nào khác, và không cần tới trang này. Chúng chỉ được khai báo ở những nơi chúng tôi thực sự gọi model: gửi chúng tới /chart thì được, nhưng sẽ không có gì xảy ra, và bạn trả giá thông thường của endpoint.

Đặc tả máy đọc được

Muốn kết nối trực tiếp REST API hoặc đưa đặc tả cho agent của riêng bạn?

AGENTS.md: /AGENTS.md, hướng dẫn cho agent (những gì gọi được không cần key, hợp đồng request, phong bì phản hồi, header giới hạn)
OpenAPI: /v1/openapi.json
llms.txt: /llms.txt · toàn văn /llms-full.txt
Postman: /postman/astroway-api.json
SDK: TypeScript, Python, PHP