# راه‌اندازی عامل هوش مصنوعی

## لینکی که باید به عامل بدهید

این نشانی دقیق را به عامل بدهید:

`https://api.expense-budget-tracker.com/v1/`

این نشانی، سند کشف عمومی و مرجع اصلی برای عامل‌های هوش مصنوعی است. این سند به عامل می‌گوید فرایند احراز هویت را چطور شروع کند، بعد سراغ کدام مسیرها برود، از چه روش احراز هویتی استفاده کند و شِمای زمان اجرا و پیاده‌سازی متن‌باز را از کجا پیدا کند.

این راهنما اتصال مستقیم از طریق Agent API را برای عامل‌های ترمینال و کلاینت‌های HTTP توضیح می‌دهد. اگر کلاینت شما از MCP پشتیبانی می‌کند، به‌جای آن از [اتصال‌دهندهٔ MCP](/fa/docs/mcp-connector/) میزبانی‌شده استفاده کنید؛ این اتصال‌دهنده به `https://mcp.expense-budget-tracker.com/mcp` وصل می‌شود و بدون فرایند دریافت `ApiKey` این صفحه، به‌صورت تعاملی با OAuth در مرورگر مجوز می‌گیرد.

## کارهایی که کاربر انجام می‌دهد

1. Claude Code، Codex، OpenClaw یا هر عامل دیگری را باز کنید که بتواند درخواست HTTP بفرستد.
2. به عامل بگویید با استفاده از `https://api.expense-budget-tracker.com/v1/` به Expense Budget Tracker متصل شود.
3. وقتی عامل آدرس ایمیل خواست، همان ایمیلی را بدهید که با آن از Expense Budget Tracker استفاده می‌کنید.
4. صندوق ورودی ایمیل خود را برای کد ۸ رقمی بررسی کنید.
5. آن کد را برای عامل بفرستید.
6. اجازه دهید عامل `ApiKey` برگردانده‌شده را بیرون از حافظهٔ گفت‌وگو ذخیره کند و بعد کار وارد کردن داده، پرس‌وجو یا بودجه‌بندی را ادامه دهد.

در جریان ورود، نیازی نیست هیچ کلیدی را دستی کپی و جای‌گذاری کنید. عامل بعد از تأیید کد ایمیل، اتصال خودش را برقرار می‌کند.

## کارهایی که عامل انجام می‌دهد

روند کامل به این صورت است:

1. `GET https://api.expense-budget-tracker.com/v1/`
2. پاسخ کشف را بخواند و به‌جای اینکه مراحل بعدی را از قبل به‌صورت ثابت تعریف کند، همان اقدام‌هایی را دنبال کند که پاسخ برمی‌گرداند
3. ایمیل کاربر را با `POST` به `bootstrapUrl` برگردانده‌شده بفرستد
4. `otpSessionToken` و اقدام مربوط به `verify_code` را دریافت کند
5. کد ۸ رقمی ایمیل را از کاربر بپرسد
6. `code`، `otpSessionToken` و یک `label` برای اتصال را با `POST` به `https://auth.expense-budget-tracker.com/api/agent/verify-code` بفرستد
7. یک `ApiKey` جدید دریافت کند
8. آن کلید را بیرون از حافظهٔ گفت‌وگو ذخیره کند، ترجیحاً با نام `EXPENSE_BUDGET_TRACKER_API_KEY`
9. با `Authorization: ApiKey <key>` درخواست `GET https://api.expense-budget-tracker.com/v1/me` را بفرستد
10. `GET https://api.expense-budget-tracker.com/v1/workspaces`
11. در صورت نیاز، با `POST /v1/workspaces` یک فضای کاری ایجاد کند
12. با `POST /v1/workspaces/{workspaceId}/select` یک فضای کاری پیش‌فرض ذخیره کند
13. رابطه‌های مجاز را با `GET https://api.expense-budget-tracker.com/v1/schema` بررسی کند
14. داده‌ها را از طریق `POST https://api.expense-budget-tracker.com/v1/sql/query` بخواند و نوشتن‌های تأییدشده را از طریق `POST https://api.expense-budget-tracker.com/v1/sql/execute` ارسال کند

انتخاب فضای کاری صریح است، اما فقط به همان درخواست محدود نمی‌ماند. بعد از `POST /v1/workspaces/{workspaceId}/select`، فضای کاری انتخاب‌شده برای همان کلید API ذخیره می‌شود؛ بنابراین در فراخوانی‌های بعدی `/v1/sql/query` و `/v1/sql/execute` لازم نیست `X-Workspace-Id` را بفرستید. با این حال، اگر بخواهید برای یک درخواست مشخص موقتاً فضای کاری ذخیره‌شده را نادیده بگیرید، همچنان می‌توانید `X-Workspace-Id` را ارسال کنید. مسیر سازگاری `POST /v1/sql` فقط برای اسکریپت‌های اتمیک چنددستوری است، نه خواندن یا نوشتن عادی.

اگر کاربر دقیقاً یک فضای کاری داشته باشد و آن کلید هنوز هیچ انتخاب ذخیره‌شده‌ای نداشته باشد، بک‌اند همان فضای کاری را به‌طور خودکار ذخیره و استفاده می‌کند.

## عامل باید چه چیزی را ذخیره کند

کلیدی که از `verify-code` برمی‌گردد بلندمدت است. فقط به حافظهٔ گفت‌وگو تکیه نکنید.

- اگر کاربر اجازهٔ نوشتن فایل بدهد، آن را در یک فایل محلی `.env` با این قالب ذخیره کنید: `EXPENSE_BUDGET_TRACKER_API_KEY='<PASTE_KEY_HERE>'`
- در غیر این صورت، آن را در شل فعلی با `export EXPENSE_BUDGET_TRACKER_API_KEY='<PASTE_KEY_HERE>'` تنظیم کنید و از کاربر بخواهید آن را در جایی پایدار ذخیره کند

درخواست‌های احراز هویت‌شده از این هدرها استفاده می‌کنند:

- `Authorization: ApiKey <key>`
- `X-Workspace-Id: <workspaceId>` فقط وقتی که بخواهید فضای کاری ذخیره‌شده را برای یک درخواست مشخص موقتاً نادیده بگیرید یا هنوز هیچ فضای کاری‌ای ذخیره نشده باشد

## اگر شما یک عامل هوش مصنوعی هستید

با این دستور شروع کنید:

```bash
curl https://api.expense-budget-tracker.com/v1/
```

بعد همان اقدام‌هایی را دنبال کنید که سرور برمی‌گرداند. اگر سند کشف از قبل مراحل بعدی را مشخص کرده است، آن‌ها را به‌صورت ثابت در کد یا دستورالعمل‌ها ننویسید.

بعد از `verify-code`، `ApiKey` برگردانده‌شده را به‌صورت امن ذخیره کنید. بعد این مسیرها را بارگذاری کنید:

- `/v1/me` برای دریافت اطلاعات حساب
- `/v1/workspaces` برای دیدن فضاهای کاری در دسترس
- `/v1/schema` برای رابطه‌ها و ستون‌های مجاز SQL
- `/v1/openapi.json` یا `/v1/swagger.json` فقط وقتی کلاینت نشانی‌های متداول مشخصات را بررسی می‌کند؛ این مسیرها پیوندهای کشف و کد منبع را برمی‌گردانند، نه مشخصات API

## نمونه پرامپت برای کاربران

### Claude Code

```text
با استفاده از https://api.expense-budget-tracker.com/v1/ به Expense Budget Tracker من وصل شو.
هر وقت لازم شد از ایمیل حسابم استفاده کن، کد ۸ رقمی را از من بپرس، ApiKey برگردانده‌شده را بیرون از حافظهٔ گفت‌وگو ذخیره کن، سپس آخرین صورت‌حساب بانکی من را از ~/Downloads وارد کن.
```

### Codex

```text
از https://api.expense-budget-tracker.com/v1/ برای اتصال به حساب Expense Budget Tracker من استفاده کن.
ایمیلم را بپرس، منتظر کد ایمیل بمان، کلید را ذخیره کن، /schema را بررسی کن و بعد جدیدترین تراکنش‌هایم را نشان بده.
```

### OpenClaw

```text
از طریق https://api.expense-budget-tracker.com/v1/ خودت را به Expense Budget Tracker وصل کن.
بعد از ورود، فضاهای کاری من را فهرست کن، یکی را به‌عنوان پیش‌فرض این کلید ذخیره کن و فایل CSV جدیدی را که بارگذاری کرده‌ام وارد کن.
```

## بعد از راه‌اندازی چه کارهایی می‌توانید انجام دهید

- صورت‌حساب‌های بانکی یا خروجی کارت را وارد کنید
- تراکنش‌ها را با دسته‌بندی‌های فعلی‌تان دسته‌بندی کنید
- ماندهٔ حساب‌ها را با داده‌های بانک تطبیق دهید
- هزینه‌ها را بر اساس دسته‌بندی، بازهٔ زمانی، فروشنده یا حساب پرس‌وجو کنید
- ردیف‌های بودجهٔ ماه بعد را به‌روزرسانی کنید

برای مسیرهای سطح پایین‌تر و جزئیات احراز هویت، [مرجع API](/fa/docs/api/) را ببینید.

---
*[نسخه HTML این صفحه را ببینید](https://expense-budget-tracker.com/fa/docs/agent-setup/)*

*کلاینت‌های راه‌دور MCP سازگار با OAuth می‌توانند به این نشانی متصل شوند `https://mcp.expense-budget-tracker.com/mcp` با دسترسی OAuth Bearer. مجوز الزامی `expenses:read` است. کلاینت همچنین می‌تواند مجوز اختیاری `expenses:write` را درخواست کند؛ این مجوز در صفحه رضایت OAuth نمایش داده می‌شود و برای تغییر داده‌ها لازم است.*

*ایجنت‌های خط فرمان و HTTP مستقیم می‌توانند با شروع از این نشانی از Agent API جداگانه استفاده کنند `GET https://api.expense-budget-tracker.com/v1/` و برای دریافت ApiKey پاسخ شناسایی سرویس را دنبال کنند.*

*نکته: برای دریافت نسخه Markdown تمیز هر صفحه، `.md` را به هر آدرس این سایت اضافه کنید.*