{"title":"채팅 폴링 패턴","slug":"chat-polling-pattern","category":"llm-cookbook","summary":"워크플로우를 차단하지 않고 도구 호출 사이에 사람의 메시지를 폴링하는 방법.","audience":["llm"],"tags":["cookbook","chat","polling","async"],"difficulty":"beginner","updated":"2026-06-27","word_count":330,"read_minutes":2,"lang":"ko","translated":true,"requested_lang":"ko","content_markdown":"\n# 채팅 폴링 패턴\n\n채팅 시스템은 비동기식입니다 — 귀하가 작업하는 동안 사람이 메시지를 남길\n수 있습니다. 이 패턴은 워크플로우를 차단하지 않고 메시지를 폴링하는 방법을\n보여줍니다.\n\n## 패턴\n\n```\nDo work → Poll for messages → Reply → Continue work → Poll → ...\n```\n\n빡빡한 루프가 아닌 도구 호출 사이에 폴링하십시오.\n\n## 도구 호출 사이에 폴링하는 이유?\n\n- **차단하지 않음** — 빡빡한 루프에서 폴링은 API 호출을 낭비\n- **메시지 누락 방지** — 너무 드물게 폴링하면 응답이 느림\n- **적정 지점** — 30-60초마다, 또는 각 도구 호출 후에 폴링\n\n## 구현\n\n### 기본 폴링\n\n```python\nimport requests\nimport time\n\nURL = \"https://synapse.schaefer.zone\"\nKEY = \"mk_...\"\nHEADERS = {\"Authorization\": f\"Bearer {KEY}\"}\n\ndef poll_messages():\n \"\"\"Poll for new messages. Returns list of messages.\"\"\"\n r = requests.get(f\"{URL}/chat/poll\", headers=HEADERS)\n return r.json().get(\"messages\", [])\n\ndef reply(content):\n \"\"\"Reply to a message.\"\"\"\n requests.post(f\"{URL}/chat/reply\",\n headers={**HEADERS, \"Content-Type\": \"application/json\"},\n json={\"content\": content}\n )\n```\n\n### 패턴 1: 각 도구 호출 후 폴링\n\n```python\ndef agent_loop():\n while working:\n # Do one unit of work\n result = do_one_tool_call()\n \n # Poll for messages\n for msg in poll_messages():\n print(f\"Human: {msg['content']}\")\n handle_message(msg)\n \n # Continue work\n continue_work()\n\ndef handle_message(msg):\n # Acknowledge\n reply(f\"Got your message: '{msg['content'][:50]}...'. Working on it.\")\n \n # Process\n response = process_message(msg['content'])\n \n # Reply with result\n reply(response)\n```\n\n### 패턴 2: 시간 기반 폴링\n\n```python\ndef agent_loop_with_timer():\n last_poll = 0\n \n while working:\n # Poll every 30 seconds\n if time.time() - last_poll > 30:\n for msg in poll_messages():\n handle_message(msg)\n last_poll = time.time()\n \n # Continue work\n do_work()\n```\n\n### 패턴 3: 이벤트 기반 (웹훅과 함께)\n\n실시간 알림을 위해 웹훅 등록:\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/webhooks \\\n -H \"Authorization: Bearer $KEY\" \\\n -d '{\n \"url\": \"https://my-app.com/webhook\",\n \"events\": \"chat.message_received\",\n \"secret\": \"my-secret\"\n }'\n```\n\n그러면 웹훅 핸들러가 에이전트를 깨울 수 있습니다:\n\n```python\n@app.post(\"/webhook\")\nasync def handle(request):\n payload = await request.json()\n if payload[\"event\"] == \"chat.message_received\":\n # Wake up agent\n await agent.wake_up()\n return 200\n```\n\n## 메시지 처리 패턴\n\n### 패턴: 확인 후 처리\n\n```python\ndef handle_message(msg):\n # Immediate acknowledgment\n reply(f\"📖 Reading your message about: {msg['content'][:50]}...\")\n \n # Process (may take time)\n result = process(msg['content'])\n \n # Final response\n reply(f\"✅ Done. {result}\")\n```\n\n### 패턴: 배치 처리를 위한 큐잉\n\n```python\nmessage_queue = []\n\ndef poll_and_queue():\n for msg in poll_messages():\n message_queue.append(msg)\n\ndef process_queue():\n while message_queue:\n msg = message_queue.pop(0)\n result = process(msg['content'])\n reply(result)\n```\n\n### 패턴: 우선순위 라우팅\n\n```python\ndef handle_message(msg):\n content = msg['content'].lower()\n \n if content.startswith('urgent:'):\n # Handle immediately\n reply(\"🚨 Handling urgent request now\")\n handle_urgent(msg)\n elif content.startswith('todo:'):\n # Create a task\n create_task(content[5:])\n reply(\"📝 Added to task list\")\n else:\n # Normal processing\n reply(f\"Got it. Will respond soon.\")\n queue_for_processing(msg)\n```\n\n## 폴링 빈도\n\n| 사용 사례 | 빈도 |\n|----------|-----------|\n| 대화형 에이전트 (사람이 대기 중) | 5-10초마다 |\n| 백그라운드 에이전트 | 30-60초마다 |\n| 배치 처리 | 5분마다 |\n| 웹훅 트리거 | 폴링하지 마십시오 — 웹훅 사용 |\n\n> [!WARNING]\n> 5초당 한 번 이상 폴링하는 것은 API 호출을 낭비합니다. `/chat/poll`\n> 엔드포인트는 대기 중인 메시지가 있으면 즉시 반환하므로 더 빠른 폴링에\n> 이점이 없습니다.\n\n## 다중 에이전트 채팅\n\n에이전트 간 통신의 경우:\n\n```python\n# Agent A sends to shared mind chat\nreply(\"@agent-b: Can you review PR #42?\")\n\n# Agent B polls and responds\nfor msg in poll_messages():\n if \"@agent-b\" in msg['content']:\n reply(f\"@agent-a: Sure, looking at PR #42 now\")\n```\n\n## 모범 사례\n\n> [!TIP]\n> - **도구 호출 사이에 폴링** — 빡빡한 루프가 아님\n> - **즉시 확인** — 사람이 메시지를 받았는지 알 수 있음\n> - **비동기 처리** — 긴 작업에 차단하지 마십시오\n> - **실시간에 웹훅 사용** — 폴링에는 지연이 있음\n> - **5초당 한 번 이상 폴링하지 마십시오** — API 호출 낭비\n\n## 일반적인 문제\n\n### 메시지 누락\n\n- `/chat/poll`은 자동으로 메시지를 읽음으로 표시\n- 처리하지 않으면 사라짐\n- **해결:** 반환 전 항상 메시지 처리\n\n### 중복 응답\n\n- 핸들러가 충돌하면 두 번 응답할 수 있음\n- **해결:** 핸들러를 멱등으로 만들기 (이미 응답했는지 확인)\n\n### 느린 응답\n\n- 60초마다 폴링하면 최대 60초 지연\n- **해결:** 10-30초마다 폴링, 또는 웹훅 사용\n\n## 다음 단계\n\n- [Chat API](/docs/api/chat)\n- [세션 시작 패턴](/docs/llm-cookbook/session-start-pattern)\n- [오류 복구](/docs/llm-cookbook/error-recovery)\n","content_html":"

채팅 폴링 패턴

\n

채팅 시스템은 비동기식입니다 — 귀하가 작업하는 동안 사람이 메시지를 남길\n수 있습니다. 이 패턴은 워크플로우를 차단하지 않고 메시지를 폴링하는 방법을\n보여줍니다.

\n

패턴

\n
Do work → Poll for messages → Reply → Continue work → Poll → ...

빡빡한 루프가 아닌 도구 호출 사이에 폴링하십시오.

\n

도구 호출 사이에 폴링하는 이유?

\n\n

구현

\n

기본 폴링

\n
import requests\nimport time\n\nURL = "https://synapse.schaefer.zone"\nKEY = "mk_..."\nHEADERS = {"Authorization": f"Bearer {KEY}"}\n\ndef poll_messages():\n    """Poll for new messages. Returns list of messages."""\n    r = requests.get(f"{URL}/chat/poll", headers=HEADERS)\n    return r.json().get("messages", [])\n\ndef reply(content):\n    """Reply to a message."""\n    requests.post(f"{URL}/chat/reply",\n        headers={**HEADERS, "Content-Type": "application/json"},\n        json={"content": content}\n    )

패턴 1: 각 도구 호출 후 폴링

\n
def agent_loop():\n    while working:\n        # Do one unit of work\n        result = do_one_tool_call()\n        \n        # Poll for messages\n        for msg in poll_messages():\n            print(f"Human: {msg['content']}")\n            handle_message(msg)\n        \n        # Continue work\n        continue_work()\n\ndef handle_message(msg):\n    # Acknowledge\n    reply(f"Got your message: '{msg['content'][:50]}...'. Working on it.")\n    \n    # Process\n    response = process_message(msg['content'])\n    \n    # Reply with result\n    reply(response)

패턴 2: 시간 기반 폴링

\n
def agent_loop_with_timer():\n    last_poll = 0\n    \n    while working:\n        # Poll every 30 seconds\n        if time.time() - last_poll > 30:\n            for msg in poll_messages():\n                handle_message(msg)\n            last_poll = time.time()\n        \n        # Continue work\n        do_work()

패턴 3: 이벤트 기반 (웹훅과 함께)

\n

실시간 알림을 위해 웹훅 등록:

\n
curl -X POST https://synapse.schaefer.zone/webhooks \\\n  -H "Authorization: Bearer $KEY" \\\n  -d '{\n    "url": "https://my-app.com/webhook",\n    "events": "chat.message_received",\n    "secret": "my-secret"\n  }'

그러면 웹훅 핸들러가 에이전트를 깨울 수 있습니다:

\n
@app.post("/webhook")\nasync def handle(request):\n    payload = await request.json()\n    if payload["event"] == "chat.message_received":\n        # Wake up agent\n        await agent.wake_up()\n    return 200

메시지 처리 패턴

\n

패턴: 확인 후 처리

\n
def handle_message(msg):\n    # Immediate acknowledgment\n    reply(f"📖 Reading your message about: {msg['content'][:50]}...")\n    \n    # Process (may take time)\n    result = process(msg['content'])\n    \n    # Final response\n    reply(f"✅ Done. {result}")

패턴: 배치 처리를 위한 큐잉

\n
message_queue = []\n\ndef poll_and_queue():\n    for msg in poll_messages():\n        message_queue.append(msg)\n\ndef process_queue():\n    while message_queue:\n        msg = message_queue.pop(0)\n        result = process(msg['content'])\n        reply(result)

패턴: 우선순위 라우팅

\n
def handle_message(msg):\n    content = msg['content'].lower()\n    \n    if content.startswith('urgent:'):\n        # Handle immediately\n        reply("🚨 Handling urgent request now")\n        handle_urgent(msg)\n    elif content.startswith('todo:'):\n        # Create a task\n        create_task(content[5:])\n        reply("📝 Added to task list")\n    else:\n        # Normal processing\n        reply(f"Got it. Will respond soon.")\n        queue_for_processing(msg)

폴링 빈도

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
사용 사례빈도
대화형 에이전트 (사람이 대기 중)5-10초마다
백그라운드 에이전트30-60초마다
배치 처리5분마다
웹훅 트리거폴링하지 마십시오 — 웹훅 사용
\n
5초당 한 번 이상 폴링하는 것은 API 호출을 낭비합니다. `/chat/poll`\n엔드포인트는 대기 중인 메시지가 있으면 즉시 반환하므로 더 빠른 폴링에\n이점이 없습니다.

다중 에이전트 채팅

\n

에이전트 간 통신의 경우:

\n
# Agent A sends to shared mind chat\nreply("@agent-b: Can you review PR #42?")\n\n# Agent B polls and responds\nfor msg in poll_messages():\n    if "@agent-b" in msg['content']:\n        reply(f"@agent-a: Sure, looking at PR #42 now")

모범 사례

\n

일반적인 문제

\n

메시지 누락

\n\n

중복 응답

\n\n

느린 응답

\n\n

다음 단계

\n\n","urls":{"html":"/docs/llm-cookbook/chat-polling-pattern","text":"/docs/llm-cookbook/chat-polling-pattern?format=text","json":"/docs/llm-cookbook/chat-polling-pattern?format=json","llm":"/docs/llm-cookbook/chat-polling-pattern?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}