# Trình tác tử AI và MCP
Bạn đang xây dựng một tác nhân AI có thể thực hiện các phép tính chiêm tinh học thực sự thay vì những ảo giác? AstroWay kết nối với **Claude (Anthropic), ChatGPT-4 (OpenAI), Llama 3.3 (Groq), DeepSeek, Google Gemini, Mistral** — thông qua MCP, tệp `llms.txt` hoặc các cuộc gọi HTTP trực tiếp. Có ba cách tích hợp — hãy chọn theo loại tác nhân của bạn:
- **`llms.txt`** — tệp khám phá dành cho các tác nhân đọc tài liệu (Cursor IDE, Windsurf, Claude trong trình duyệt, các pipeline RAG tùy chỉnh trên LangChain/LlamaIndex).
- **MCP Server** — zero-code cho Claude Desktop, Cursor IDE, Windsurf, VS Code (llm CLI) và bất kỳ máy khách tương thích MCP nào (bao gồm cả GPT với MCP thông qua OpenAI Realtime API).
- **HTTP API** — truy cập trực tiếp từ tác nhân hoặc framework của riêng bạn (LangChain, LlamaIndex, AutoGen, CrewAI).
## llms.txt — khám phá dành cho tác nhân AI
Trang web cung cấp hai tệp có thể đọc được bởi máy ở định dạng [llms.txt](https://llmstxt.org/):
- **[`/llms.txt`](https://api.astroway.info/llms.txt)** — chỉ mục tất cả các trang tài liệu được nhóm theo phần (API Reference, Use Cases, Examples, Products). Nhỏ gọn, vừa trong bất kỳ *context window* nào.
- **[`/llms-full.txt`](https://api.astroway.info/llms-full.txt)** — toàn bộ nội dung tài liệu dưới dạng tệp plain-text. Phù hợp để lập chỉ mục ngoại tuyến vào cơ sở dữ liệu vector hoặc nhập một lần vào *context*.
### Khi nào nên sử dụng
| Tình huống | Tệp |
|---|---|
| Cursor/Windsurf "hãy đọc tài liệu astroway và giúp tôi tích hợp" | `/llms.txt` (tác nhân sẽ tự kéo các phần cần thiết) |
| Pipeline RAG/CSDL vector riêng cho bot FAQ | `/llms-full.txt` (một lần fetch — toàn bộ corpus) |
| Claude/ChatGPT trong trình duyệt: "đây là API của chúng tôi, hãy xây dựng một máy khách" | Dán `/llms-full.txt` vào prompt |
| Tác nhân sản xuất thực hiện các cuộc gọi | MCP Server hoặc HTTP API (xem bên dưới) |
### Ví dụ: pull vào tác nhân của riêng bạn
```ts
const docs = await fetch('https://api.astroway.info/llms-full.txt').then(r => r.text());
const systemPrompt = `You are an integration assistant for AstroWay API.
Documentation:
${docs}
When the user asks how to do X, return a working code snippet using their API key.`;
```
## MCP Server (được khuyến nghị cho Claude Desktop)
Model Context Protocol (MCP) là tiêu chuẩn mở để kết nối các công cụ với các mô hình AI. Máy chủ MCP của AstroWay cung cấp 25 công cụ cho các phép tính và diễn giải chiêm tinh.
### Thiết lập cho Claude Desktop
Thêm vào `claude_desktop_config.json`:
```json
{
"mcpServers": {
"astroway": {
"command": "npx",
"args": ["@astroway/mcp"],
"env": {
"ASTROWAY_API_KEY": "aw_live_your_key_here"
}
}
}
}
```
Sau khi khởi động lại Claude Desktop, bạn sẽ thấy 25 công cụ chiêm tinh.
### Những gì MCP Server có thể làm
| Công cụ | Chức năng |
|---|---|
| `natal_chart` | Tính toán biểu đồ natal |
| `synastry` | Tính toán synastry giữa hai người |
| `daily_horoscope` | Lập biểu đồ tử vi hàng ngày |
| `interpret_natal` | Diễn giải biểu đồ natal bằng AI |
| `human_design` | Bản đồ Human Design đầy đủ |
| `transits` | Các transit hiện tại |
Tổng cộng có 25 công cụ bao phủ các phép tính chính và diễn giải bằng AI.
### Ví dụ hội thoại với Claude
> **Người dùng:** Hãy xây dựng biểu đồ natal cho người sinh ngày 14 tháng 7 năm 1990 lúc 14:30 tại Kyiv. Ý nghĩa của Mặt Trời trong Cự Giải ở nhà 10 là gì?
>
> **Claude:** *Sử dụng `natal_chart` để tính toán, sau đó `interpret_placement` để diễn giải. Trả về vị trí hành tinh với dữ liệu thực tế và diễn giải có ý nghĩa.*
## HTTP API
Đối với các tác nhân AI không hỗ trợ MCP — hãy sử dụng HTTP API trực tiếp.
### Để tạo nội dung
```ts
// Tác nhân AI gọi /interpret/natal để diễn giải
const r = await fetch('https://api.astroway.info/v1/interpret/natal', {
method: 'POST',
headers: {
'X-Api-Key': process.env.ASTROWAY_API_KEY!,
'Content-Type': 'application/json',
},
body: JSON.stringify({
date: '1990-07-14',
time: '14:30:00',
timezoneOffset: 3,
latitude: 50.4501,
longitude: 30.5234,
}),
});
const result = await r.json();
// result.text — diễn giải AI sẵn sàng
// result.disclaimer — disclaimer để hiển thị
```
```python
r = requests.post(
'https://api.astroway.info/v1/interpret/natal',
headers={'X-Api-Key': os.environ['ASTROWAY_API_KEY']},
json={
'date': '1990-07-14',
'time': '14:30:00',
'timezoneOffset': 3,
'latitude': 50.4501,
'longitude': 30.5234,
},
)
result = r.json()
# result['text'] — diễn giải AI sẵn sàng
# result['disclaimer'] — disclaimer để hiển thị
```
```bash frame="terminal"
curl -X POST https://api.astroway.info/v1/interpret/natal \
-H "X-Api-Key: $ASTROWAY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"date": "1990-07-14",
"time": "14:30:00",
"timezoneOffset": 3,
"latitude": 50.4501,
"longitude": 30.5234
}'
```
```php
'https://api.astroway.info/v1/']);
$r = $aw->post('interpret/natal', [
'headers' => ['X-Api-Key' => getenv('ASTROWAY_API_KEY')],
'json' => [
'date' => '1990-07-14',
'time' => '14:30:00',
'timezoneOffset' => 3,
'latitude' => 50.4501,
'longitude' => 30.5234,
],
]);
$result = json_decode($r->getBody(), true);
// $result['text'] — diễn giải AI sẵn sàng
// $result['disclaimer'] — disclaimer để hiển thị
```
### Để tính toán + LLM của riêng bạn
```ts
// 1. Lấy dữ liệu thô qua /chart (rẻ hơn — 20 tín dụng)
const chart = await fetch('https://api.astroway.info/v1/chart', { ... });
const data = await chart.json();
// 2. Truyền dữ liệu vào LLM của bạn
const prompt = `Interpret this natal chart: ${JSON.stringify(data.planets)}`;
const llmResponse = await myLLM.generate(prompt);
```
## Các kịch bản
### Trợ lý chiêm tinh cá nhân
MCP Server + Claude/ChatGPT. Người dùng đặt câu hỏi — tác nhân tính toán và diễn giải. Ngân sách: gói Free cho mục đích cá nhân.
### Bot tạo nội dung cho mạng xã hội
Tạo biểu đồ tử vi hàng ngày cho 12 cung hoàng đạo thông qua `/horoscope/daily`. 12 yêu cầu mỗi ngày = 240 tín dụng. Gói Free có đủ dự phòng.
### Nền tảng huấn luyện AI
`/interpret/natal` + `/interpret/transits` cho mỗi khách hàng. 100 khách hàng/ngày = 10.000 tín dụng/ngày. Gói Pro.