توسعهٔ تعامل agent

پس از نصب و احراز هویت برنامهٔ agent، آن برنامه می‌تواند در کارهای Pulse مشارکت کند. Agent session یک اجرا را دنبال می‌کند و activityها پیشرفت، سؤال‌ها و پاسخ برنامه را برای افراد قابل‌دیدن می‌سازند.

این راهنما همان مسیری را دنبال می‌کند که برنامه طی می‌کند: شخصی Issue را تفویض یا برنامه را منشن می‌کند، Pulse session باز می‌کند و وب‌هوک می‌فرستد، سپس برنامه از طریق activityها پاسخ می‌دهد. وضعیت session خودکار از همین activityها به دست می‌آید.

نمونه‌ها از REST API و فیلدهای snake_case در Pulse استفاده می‌کنند. برای ثبت برنامه، OAuth، نگهداری توکن و امضای وب‌هوک، مرجع راه‌اندازی برنامه را ببینید.

Agent session

Session درخواست یک شخص را به کار برنامه روی Issue یا Comment وصل می‌کند. وقتی شخصی Issue را به برنامه تفویض یا آن را در Comment @منشن کند، Pulse session می‌سازد. وب‌هوک created شامل درخواست، context مرتبط و شناسهٔ session است. افراد می‌توانند کار را دنبال کنند، پاسخ دهند یا Stop را بزنند.

وضعیت‌های session

شما هرگز state را تنظیم نمی‌کنید. Pulse آن را از آخرین activity شما به دست می‌آورد.

پیام یک نفر روی sessionای با وضعیت complete، error یا stale آن را دوباره به pending باز می‌کند و prompted را برایتان می‌فرستد.

URL خارجی session

اگر برنامه صفحهٔ اجرای خودش را دارد، URL خارجی بگذارید تا افراد از session پالس آن را باز کنند. ثبت URL ظرف ۱۰ ثانیه پس از created، هنگام شروع کار برنامه، پاسخ اولیه نیز محسوب می‌شود.

افراد را به UI خودتان برای این session لینک دهید (حداکثر ۱۰ لینک، هر url یکتا و https://، label تا ۶۰ نویسه). فهرست را با external_urls جایگزین کنید، یا با added_external_urls و removed_external_urls تغییرش دهید (نه هر دو با هم):

{ "added_external_urls": [{ "label": "Open in Scout", "url": "https://scout.acme.example/runs/42" }] }

{ "removed_external_urls": ["https://scout.acme.example/runs/42"] }

Pull request در session

وقتی برنامه pull request منتشر کرد، URL امن HTTPS آن را با برچسبی روشن، مثلاً Open pull request، به external_urls اضافه کنید. Pulse آن را کنار لینک‌های خارجی دیگر session نشان می‌دهد. برای pull request فیلد جداگانه‌ای در session یا API پیشنهاد مخزن وجود ندارد.

{ "added_external_urls": [{ "label": "Open pull request", "url": "https://github.com/acme/app/pull/88" }] }

نتیجه و کاری را که باید انسان بررسی کند در response نهایی بنویسید؛ لینک خارجی به‌تنهایی پیام پایان کار نیست.

وب‌هوک‌های session

پیش از استفادهٔ افراد، رویدادهای session را فعال کنید. Pulse رویداد AgentSessionEvent را به endpoint نصب برنامه می‌فرستد. امضا را بررسی کنید، تکراری‌ها را با data.event_id کنار بگذارید، ظرف ۵ ثانیه پاسخ دهید و درخواست را در پس‌زمینه پردازش کنید.

محموله‌های کامل created و prompted، شامل prompt_context به‌شکل XML، در مرجع محمولهٔ رویدادها آمده‌اند. تحویل وب‌هوک ممکن است تکرار شود؛ retry نباید کار تکراری آغاز کند.

ساخت پیش‌دستانهٔ session

برنامه می‌تواند روی Issue یا Commentی که به آن دسترسی دارد session بسازد، حتی اگر کسی آن را تفویض یا منشن نکرده باشد.

POST /agent-sessions با یک issue_id یا comment_id که installation شما پوشش می‌دهد، کاری را شروع می‌کند که کسی تفویض نکرده است:

{ "issue_id": "6ab5b0024f48187cbd3ce990" }

پاسخ، session جدید است (201)، با app user شما به‌عنوان creator. برای آن هیچ وب‌هوک created فرستاده نمی‌شود. روی یک Comment، برای هر برنامه در هر نخ فقط یک session باز وجود دارد: اگر session شما از قبل وجود داشته باشد، با 200 برمی‌گردد.

Agent activity

Activityها سابقهٔ گفتگو در یک اجرا هستند. برنامه برای تأیید شروع thought، هنگام انجام کار action، برای تصمیم انسانی elicitation و در پایان response یا error می‌فرستد. افراد می‌توانند prompt بفرستند؛ برنامه نمی‌تواند.

هنگام ادامهٔ اجرا، activityها را بخوانید، نه Commentهای قابل‌ویرایش Issue را. هر activity نویسنده و seq افزایشی دارد؛ با after_seq موارد رسیده از گام قبلی را بگیرید. بهترین شیوه‌های تعامل نمونهٔ کامل خواندن را نشان می‌دهد.

فرستادن activityهای agent

یک Idempotency-Key تا ۶۴ نویسه بفرستید و در retry همان را نگه دارید: درخواست تکراری activity اصلی را با 201 برمی‌گرداند و چیز تازه‌ای ذخیره نمی‌کند.

POST https://api.trypulse.tech/api/v1/agent-sessions/sess_01J9Z3K8T5N2/activities
Authorization: Bearer $APP_ACCESS_TOKEN
X-Workspace-ID: 6a34cfb024a3b4ed28806e3b
Idempotency-Key: scout-sess_01J9Z3K8T5N2-1
Content-Type: application/json

{ "content": { "type": "thought", "body": "Looking at PUL-123…" } }

یک action گذرا، و سپس نتیجهٔ آن:

{ "ephemeral": true, "content": { "type": "action", "action": "Searching code", "parameter": "Retry-After" } }

{ "content": { "type": "action", "action": "Searched code", "parameter": "Retry-After", "result": "3 files match" } }

پاسخ 201 همان activity ذخیره‌شده است:

{
  "id": "act_01J9Z3M1A2",
  "seq": 4,
  "type": "action",
  "content": { "type": "action", "action": "Searched code", "parameter": "Retry-After", "result": "3 files match" },
  "ephemeral": false,
  "superseded_by_seq": null,
  "signal": null,
  "signal_metadata": null,
  "author": {
    "kind": "app",
    "id": "6ab5a2d134765b14d76a6b12",
    "name": "Scout",
    "avatar_url": "https://images.trypulse.tech/avatars/scout.png"
  },
  "created_at": "2026-09-25T09:12:05.410Z"
}

کار را با یک response تمام کنید، یا با یک error وقتی یک نفر باید اقدامی انجام دهد:

{ "content": { "type": "response", "body": "Fixed in https://github.com/acme/app/pull/88: retries now honour `Retry-After`." } }

محمولهٔ activity

Pulse پنج نوع activity از برنامه می‌پذیرد. content.type شکل محموله را تعیین می‌کند و شکل نامعتبر پاسخ 422 VALIDATION_ERROR می‌گیرد. body از Markdown پشتیبانی می‌کند. هر نمونه را برای دیدن فیلدها باز کنید.

{ "content": { "type": "thought", "body": "در حال خواندن Issue و Commentهای اخیر هستم." } }

{ "content": { "type": "elicitation", "body": "کلاینت Go را هم به‌روز کنم؟" } }

prompt پیام شخص است. ارسال آن از برنامه پاسخ 422 PROMPT_IS_HUMAN_ONLY می‌گیرد.

پیشنهاد مخزن

رویداد created ممکن است در prompt_context یک <repository-hint> داشته باشد. این یک سرنخ از تیم Issue است، نه مجوز git یا انتخاب قطعی مخزن. از اعتبارنامهٔ خودتان استفاده کنید و پیش از نوشتن کد مخزن را تأیید کنید.

<repository-hint repository="pulse/pulse-api"/>

Pulse endpoint معادل issueRepositorySuggestions ندارد. اگر سرنخ نبود یا مبهم بود، پیش از تغییر مخزن با elicitation از شخص بپرسید.

سیگنال‌ها

سیگنال به activity نیت اضافه می‌کند. stop از شخص می‌خواهد برنامه کار را رها کند؛ برنامه می‌تواند auth یا select را به elicitation وصل کند تا اتصال حساب یا انتخابی را بخواهد. سیگنال را همراه محتوای activity بررسی کنید. سیگنال‌ها محموله و رفتار پاسخ را توضیح می‌دهد.

Activityهای گذرا

thought یا action می‌تواند در زمان کار موقت باشد. با ephemeral: true،‏ activity بعدی برنامه جای آن را در پنل می‌گیرد. نمونهٔ اصلی با superseded_by_seq در فهرست می‌ماند تا گفتگو قابل بازسازی باشد.

{ "ephemeral": true, "content": { "type": "action", "action": "Searching code", "parameter": "Retry-After" } }

فقط thought و action این ویژگی را دارند. پاسخ یا سؤال باید قابل‌دیدن بماند.

Planهای agent

Plan یک چک‌لیست در سطح session برای کار چندمرحله‌ای است. در هر درخواست PATCH /agent-sessions/{session_id}، کل آرایهٔ plan را جایگزین کنید؛ Pulse گام تکی را جدا به‌روز نمی‌کند. Plan حداکثر ۵۰ مورد دارد.

هر بار کل آرایه را بفرستید:

PATCH https://api.trypulse.tech/api/v1/agent-sessions/sess_01J9Z3K8T5N2
Content-Type: application/json

{
  "plan": [
    { "content": "Read the issue and its threads", "status": "completed" },
    { "content": "Draft the change", "status": "inProgress" },
    { "content": "Report back", "status": "pending" }
  ]
}

status یکی از pending، inProgress، completed یا canceled است؛ content تا ۵۰۰ نویسه.

پیشنهادها

Session تازه را سریع تأیید کنید، کار طولانی را با به‌روزرسانی مفید روشن نگه دارید و با نتیجه‌ای پایان دهید که شخص بتواند بر اساسش عمل کند. Stop را پیش از کارهای صف‌شده انجام دهید. بهترین شیوه‌های تعامل پیگیری، تغییر دسترسی و تحویل کار را پوشش می‌دهد. برای endpointها و محمولهٔ کامل رویدادها مرجع API را بخوانید.