Цепочки (треды) | Agent Inbox

Что такое Thread?

Thread — ресурс API, представляющий одну беседу. Это контейнер, в котором связанные Messages идут в хронологическом порядке, как тред в обычном почтовом клиенте.

Threads создаются автоматически. Когда агент отправляет Message не как ответ на предыдущее, начинается новый Thread. Все последующие ответы попадают в тот же Thread, сохраняя контекст.

Запросы к `Threads`

Хотя Threads создаются неявно, их можно получать двумя способами: в рамках одного Inbox или по всей Organization.

Список `Threads` по `Inbox`

Стандартный способ — все беседы, связанные с одним агентом или Inbox.

1 # You'll need an inbox ID to list threads from.
2 inbox_id = "inbound-agent@agentinbox.space"
3 
4 # This retrieves all threads within the specified Inbox
5 
6 inbox_threads = client.inboxes.threads.list(inbox_id=inbox_id)

Список `Threads` по всей `Organization`

Одна из сильных сторон Agent Inbox: без inbox_id можно получить Threads из каждого Inbox в Organization. Организационный запрос нужен для:

Супервизорских агентов: мониторинг бесед парка других агентов.
Аналитических панелей: видимость по всем ящикам организации.
Сложных сценариев: маршрутизация и эскалация между агентами с разными правами.

1 # By not providing an inbox_id, we get all threads in the organization
2 all_threads = client.threads.list()
3 
4 print(f"Found {all_threads.count} threads across the entire organization.")

Скоро: семантический поиск по организации

Мы развиваем семантический поиск для org-wide списка цепочек. Скоро можно будет находить Threads по смыслу Messages, а не только по ключевым словам.

Получение одного `Thread`

По ID возвращается объект Thread с перечнем связанных Messages и их идентификаторов. Типичный сценарий: просмотреть сообщения в цепочке и вызвать messages.reply для последнего.

1 thread_id = "thread_456def"
2 
3 # This retrieves a single thread and its messages
4 
5 thread = client.threads.get(
6 thread_id="thread_id"
7 )
8 
9 print(f"Retrieved thread {thread.thread_id} with {len(thread.messages)} messages.")

Копировать в Cursor / Claude

Скопируйте один из блоков ниже в Cursor или Claude, чтобы за один раз передать полное описание API цепочек.

1 """
2 Agent Inbox Threads — copy into Cursor/Claude.
3 
4 Setup: pip install agentinbox python-dotenv. Set AGENTINBOX_API_KEY in .env.
5 
6 API reference:
7 - inboxes.threads.list(inbox_id, limit?, page_token?, labels?, before?, after?, ascending?)
8 - inboxes.threads.get(inbox_id, thread_id)
9 - inboxes.threads.get_attachment(inbox_id, thread_id, attachment_id)
10 - inboxes.threads.delete(inbox_id, thread_id)
11 - threads.list(limit?, page_token?, labels?) — org-wide, all inboxes
12 - threads.get(thread_id) — org-wide
13 - threads.get_attachment(thread_id, attachment_id)
14 
15 Errors: SDK raises on 4xx/5xx. Rate limit: 429 with Retry-After.
16 """
17 import os
18 from dotenv import load_dotenv
19 from agentinbox import Agentinbox
20 
21 load_dotenv()
22 client = Agentinbox(api_key=os.getenv("AGENTINBOX_API_KEY"))
23 
24 inbox_id = "agent@agentinbox.space"
25 
26 # Per-inbox threads
27 inbox_threads = client.inboxes.threads.list(inbox_id=inbox_id, limit=20)
28 if inbox_threads.threads:
29     thread = client.inboxes.threads.get(inbox_id, inbox_threads.threads[0].thread_id)
30 
31 # Org-wide threads
32 all_threads = client.threads.list(limit=50)
33 if all_threads.threads:
34     single = client.threads.get(all_threads.threads[0].thread_id)
35     print(f"Thread has {len(single.messages)} messages")

Что такое Thread?

Запросы к Threads

Список Threads по Inbox

Список Threads по всей Organization