문서 설명: AI Chat v2는 기존 대화 인터페이스의 간단한 호출 방식을 유지하면서, 멀티모달 입력, 구조화된 이벤트 스트림, 자동 도구 호출, 일시 중지 및 재개, 비동기 실행과 세션 관리를 추가합니다. 이 글은 거의 코드를 다시 작성하지 않아도 되는 마이그레이션에서 시작하여, 이러한 변화가 실제 제품 개발에 어떤 영향을 미치는지 명확히 설명합니다.
많은 채팅 인터페이스는 데모 단계에서는 모두 사용하기 좋습니다. 질문을 전달하고, 모델이 한 단락의 텍스트를 반환할 때까지 기다린 뒤, 그 텍스트를 페이지에 표시하면 됩니다.
제품이 계속 발전하면, 일은 더 이상 “한마디 묻고, 한마디 답하는” 것에 그치지 않습니다. 사용자는 PDF와 스크린샷을 업로드하고, 모델은 웹페이지를 조회하고 파일을 읽으며, 이미 권한이 부여된 GitHub, Notion 등의 도구까지 호출해야 합니다. 하나의 작업은 여러 라운드에 걸쳐 지속될 수 있고, 중간에 정보가 부족하여 멈추고 추가 질문을 할 수도 있습니다. 이때 인터페이스가 여전히 계속 늘어나는 하나의 텍스트 문자열만 반환한다면, 프런트엔드는 모델이 무엇을 하고 있는지 알기 어렵고, 백엔드도 작업이 실제로 끝났는지 판단하기 어렵습니다.
Ace Data Cloud AI Chat v2 API가 해결하는 것이 바로 이 문제입니다. 기존의 대화 방식을 뒤엎지 않고, 간단한 호출과의 호환성을 기반으로 한 번의 응답을 프로그램이 인식하고 처리할 수 있는 이벤트로 나눕니다. 본문은 본문대로, 도구 호출은 도구 호출대로, 인용, 파일, 오류 및 최종 상태는 각각 명확한 위치를 가집니다.

그림: AI Chat v2는 더 이상 전체 작업을 하나의 텍스트로 압축하지 않고, 입력, 도구 및 출력 이벤트가 구조를 유지하도록 합니다.
¶ 마이그레이션은 먼저 주소 하나를 바꾸는 것부터 시작할 수 있습니다
프로젝트가 기존 /aichat/conversations를 사용하고 있다면, 먼저 메시지 구조를 다시 작성할 필요도 없고, 먼저 Agent 인터페이스를 만들 필요도 없습니다. V2는 기존의 model, question, stateful, id, references, preset 등의 필드를 계속 허용합니다. 최소 마이그레이션은 요청 주소를 다음으로 바꾸기만 하면 됩니다:
https://api.acedata.cloud/aichat2/conversations
가장 기본적인 요청도 여전히 짧습니다:
curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \
-H 'accept: application/json' \
-H 'authorization: Bearer YOUR_API_TOKEN' \
-H 'content-type: application/json' \
-d '{
"model": "YOUR_SUPPORTED_MODEL",
"question": "请概括这份需求里最重要的三个问题。",
"stateful": true
}'
일반 JSON 모드에서 인터페이스는 여전히 익숙한 결과를 반환합니다:
{
"answer": "...",
"id": "conversation-uuid"
}
반환된 id를 저장하고, 다음 요청에 같은 id를 포함하면 대화를 계속할 수 있습니다. stateful의 기본값은 true이며, 저장된 세션의 컨텍스트를 로드하고 이어갈지 제어하는 데 사용됩니다.
이 단계는 실제 프로젝트에 매우 적합합니다. 먼저 인증, 모델, 지연 시간과 기존 비즈니스가 정상인지 검증한 뒤, 새로운 기능을 점진적으로 연동할 수 있습니다. 마이그레이션을 인터페이스 리팩터링과 같은 배포에 묶을 필요는 없습니다.
¶ 파일과 이미지가 대화에 들어오면 순서도 정보가 됩니다
기존의 question은 순수 텍스트에 적합합니다. “먼저 보고서를 보고, 다음으로 스크린샷과 대조한 뒤, 마지막으로 결론을 내려라”와 같은 작업에서는 단순한 첨부 파일 목록만으로는 충분히 정확하지 않습니다. V2는 구조화된 message 배열을 추가하여, 텍스트, 이미지, 파일을 순서대로 넣을 수 있습니다:
{
"model": "YOUR_SUPPORTED_MODEL",
"stateful": true,
"message": [
{
"type": "text",
"text": "阅读报告,并把其中的趋势与后面的仪表盘截图进行对照。"
},
{
"type": "file_url",
"file_url": {"url": "https://example.com/report.pdf"}
},
{
"type": "image_url",
"image_url": {"url": "https://example.com/dashboard.png"}
}
]
}
사용 가능한 콘텐츠 블록에는 text, image_url, file_url이 포함됩니다. 중요한 것은 단지 “첨부 파일을 지원한다”는 점이 아니라, 콘텐츠 간의 관계가 전송 과정에서 사라지지 않는다는 점입니다. 클라이언트는 모델에 어느 부분이 작업 설명인지, 어느 파일이 원본 자료인지, 다음으로 무엇을 비교해야 하는지를 명확하게 알릴 수 있습니다.
기존 클라이언트의 원활한 마이그레이션을 위해 V2는 여전히 references를 인식합니다. 이미지 확장자에 해당하는 URL은 이미지로 처리되고, 그 외 URL은 파일로 처리됩니다. 단순히 인터페이스만 업그레이드한다면 기존 방식을 잠시 유지할 수 있습니다. 입력 순서가 이해에 영향을 미친다면 message 사용을 권장합니다.
¶ 스트리밍 응답은 더 이상 “입력 중”만을 의미하지 않습니다
전통적인 스트리밍 출력에는 일반적으로 텍스트 증분만 있습니다. 모델이 검색을 시작하거나 파일을 읽거나 외부 도구를 호출하면, 페이지는 멈춘 것처럼 보이고 사용자는 작업이 계속되는지 알 수 없으며 개발자도 명확한 상태를 얻을 수 없습니다.
AI Chat v2는 accept 요청 헤더를 통해 세 가지 응답 방식을 제공합니다:
| 사용 시나리오 | accept |
반환 방식 |
|---|---|---|
| 간단한 서버 측 요청 | application/json |
완료 후 {answer, id} 반환 |
| Node, Python, CLI 또는 Worker | application/x-ndjson |
줄마다 하나의 JSON 이벤트 |
| Web 프런트엔드 | text/event-stream |
SSE 이벤트 스트림 |
NDJSON 및 SSE 모드에서 반환되는 것은 단순한 token이 아니라, 유형이 있는 이벤트 집합입니다. text_delta는 본문 증분에 사용되고, tool_use는 모델이 도구 호출을 준비하고 있음을 나타내며, tool_result는 도구 결과를 반환하고, citation은 인용 출처를 제공하며, card와 artifact는 별도로 표시할 수 있는 카드 또는 산출물을 담고, error는 이번 라운드의 실패를 나타내며, done은 사용량과 종료 사유를 제공합니다.
아래 Python 소비 측은 본문을 이어 붙이는 동시에 핵심 상태를 유지합니다:
import json
import os
import requests
url = "https://api.acedata.cloud/aichat2/conversations"
headers = {
"accept": "application/x-ndjson",
"authorization": f"Bearer {os.environ['ACEDATA_API_TOKEN']}",
"content-type": "application/json",
}
payload = {
"model": os.environ["ACEDATA_CHAT_MODEL"],
"question": "检索资料,给出带来源的简要结论。",
"stateful": True,
}
with requests.post(url, json=payload, headers=headers,
stream=True, timeout=120) as response:
response.raise_for_status()
answer = []
for raw_line in response.iter_lines():
if not raw_line:
continue
event = json.loads(raw_line)
event_type = event.get("type")
if event_type == "text_delta":
answer.append(event.get("content", ""))
elif event_type == "tool_use":
print("开始调用:", event.get("tool_name"))
elif event_type == "tool_result":
print("工具是否失败:", event.get("is_error"))
elif event_type == "error":
raise RuntimeError(event.get("message", "未知错误"))
elif event_type == "done":
print("用量:", event.get("usage"))
print("终止原因:", event.get("terminal_reason"))
print("".join(answer))
제품이 최종 텍스트만 신경 쓴다면 모든 text_delta.content를 이어 붙이면 됩니다. 관찰 가능한 Agent 인터페이스를 만들고자 한다면 도구 호출, 인용, 산출물 및 상태를 각각 렌더링할 수 있습니다. 두 요구 사항은 동일한 인터페이스를 사용하므로, “단순 채팅”과 “복잡한 작업”을 위해 두 세트의 프로토콜을 유지할 필요가 없습니다.
¶ 도구 호출은 기본적으로 사용할 수 있지만, 제품은 여전히 경계를 명확히 그려야 합니다
V2는 모델이 작업 필요에 따라 웹 검색, 페이지 추출, 파일 읽기 등의 내장 기능을 호출할 수 있게 합니다. 사용자가 해당 서비스를 연결하고 권한을 부여한 후에는 MCP 도구를 사용하여 GitHub, Notion 등의 외부 데이터를 처리할 수도 있습니다.
스트림에는 각각 tool_use와 tool_result가 나타나며, 둘은 tool_id를 통해 연결됩니다. 프런트엔드는 이를 바탕으로 실제 진행 상황을 표시할 수 있고, 백엔드는 각 도구의 소요 시간과 실패 지점을 기록할 수 있습니다.
도구를 자동으로 호출할 수 있다고 해서 실행 범위를 무제한으로 열어 두어야 한다는 의미는 아닙니다. max_turns는 하나의 요청에서 Agent 반복 라운드 수를 제한하는 데 사용되며, 문서에 제시된 범위는 1—500입니다. 1로 설정하면 이번 라운드에서는 모델 호출을 한 번만 수행하고, 도구 호출로 계속 진입하지 않습니다. 프로덕션 환경에서는 작업 복잡도, 응답 시간 및 비용 예산을 고려하여 능동적으로 설정해야 하며, 장기간 큰 기본 상한에 의존해서는 안 됩니다.
Webhook, CI/CD 또는 모니터링 작업의 경우 V2는 async: true를 지원합니다. 작업은 백그라운드에서 실행될 수 있고, 조회 또는 callback_url을 통해 결과를 가져올 수 있습니다. 그러나 전송, 게시, 쓰기와 관련된 작업은 allowed_skills, allowed_mcp_servers 또는 unattended_policy를 통해 명시적으로 사전 권한을 부여해야 합니다.
연결은 “접근할 수 있는가”를 해결하고, 권한 정책은 “이번에 사용자를 대신해 행동할 수 있는가”를 해결합니다. 이 두 가지는 혼동해서는 안 됩니다.
¶ Agent에 정보가 부족할 때, 작업이 이미 완료된 척할 필요는 없습니다
복잡한 작업은 구체적인 문제에서 자주 막힙니다. 어느 채널에 게시할지, 어떤 형식을 사용할지, 기존 파일을 덮어쓸지 등이 그것입니다. V2는 이를 위해 ask_user_question 이벤트를 제공합니다. 이벤트가 나타난 후 세션은 사용자 입력을 기다리는 상태로 진입합니다.
클라이언트는 현재 세션의 id와 해당 tool_id를 저장하고, 질문을 표시하여 답변을 수집한 다음, 동일한 세션 id를 사용해 tool_results를 통해 답변을 다시 전달합니다. 그러면 작업은 일시 중단 지점에서 계속될 수 있습니다. 이 메커니즘은 승인 노드를 만드는 데에도 적합합니다. 모델이 자료가 부족할 때 스스로 추측하게 하는 것보다, 누락된 선택을 사용자에게 돌려주는 편이 낫습니다.
¶ 세션 자체도 관리할 수 있습니다
V2는 동일한 엔드포인트에 경량 세션 CRUD를 추가했으며, action을 통해 retrieve, retrieve_batch, update, delete를 구분합니다.
retrieve_batch는 전체 messages를 포함하지 않는 요약을 반환하므로 세션 사이드바에 적합합니다. 사용자가 실제로 세션을 열 때는 다시 retrieve를 호출하여 본문을 읽습니다. 긴 세션의 경우에도 서버 측 컨텍스트 정리는 저장된 원본 메시지를 요약으로 덮어쓰지 않습니다. 계속해서 글을 수정하거나, 숫자를 확인하거나, 게시를 준비해야 할 때는 여전히 원문을 읽어야 하며, 요약으로 본문을 대체해서는 안 됩니다.
¶ 출시 전에는 “텍스트가 반환되는가”만 검증하지 마세요
Agent 인터페이스를 연동한 후 일부 텍스트를 받았다고 해서 이번 라운드가 신뢰성 있게 완료되었다는 의미는 아닙니다. 스트림이 종료되었다고 해서 반드시 작업이 성공한 것도 아닙니다. 클라이언트는 error를 처리해야 하며, done을 받은 후 usage와 terminal_reason을 기록해야 합니다. SSE에서 [DONE]은 전송 종료만을 의미하며, 그 전에 이미 발생한 오류 이벤트를 덮어쓸 수 없습니다.
API Token은 서버 측에만 보관해야 합니다. 스트림 파서는 네트워크 청크와 일시적으로 알 수 없는 새 이벤트를 처리할 수 있어야 합니다. 도구 호출은 tool_id로 연결해야 합니다. 인용 링크와 산출물은 안전하게 렌더링해야 합니다. 쓰기 가능한 연결에는 계속해서 사람의 확인 또는 충분히 좁은 무인 권한 부여를 유지해야 합니다. 모델 이름, 과금 및 사용 가능한 기능은 변경될 수 있으므로, 정식 연동 시에는 현재 문서, 서비스 페이지 및 콘솔을 기준으로 해야 하며, 예시 구성을 장기간 하드코딩하지 마세요.
AI Chat v2에서 가장 주목할 만한 점은 채팅 창에 버튼 몇 개를 더 추가하는 것이 아닙니다. 애플리케이션이 마침내 하나의 AI 작업 내부에서 무엇이 일어났는지 볼 수 있게 한다는 점입니다. 모델이 언제 텍스트를 출력하는지, 언제 도구를 호출하는지, 어디에서 사용자를 기다리는지, 또 어떤 상태로 종료되는지를 알 수 있습니다.
기존 프로젝트가 아직 일반적인 질의응답 창에 불과하다면, 먼저 인터페이스 주소를 변경하고 기존 요청 본문을 계속 사용할 수 있습니다. 이 단계가 안정된 후에 message, NDJSON 또는 SSE, 도구 타임라인 및 일시 중단 후 재개를 연동하세요. 업그레이드는 작을 수 있지만, 이후의 제품 형태를 위한 충분히 큰 공간을 남겨 둡니다.
