ProsodyProsody
Agent API

에이전트를 내 서비스에 붙이기

콘솔에서 만든 에이전트를 웹사이트, 앱, 콜봇 백엔드에 연결하는 개발자 문서입니다. API Key는 서버에만 두고, 브라우저 위젯은 내 서버 프록시를 통해 호출하세요.

에이전트 만들기API Key도입 문의

연동 흐름

STEP 1

Agent Builder

문서 업로드와 대화로 에이전트 지식과 응대 지침을 만들고 직접 수정합니다.

STEP 2

배포

검수한 에이전트 지식을 런타임에서 사용할 버전으로 고정합니다.

STEP 3

API Key 발급

서버에서 사용할 키와 Agent ID를 함께 보관합니다.

STEP 4

서버 프록시 연결

웹 위젯과 앱은 내 서버를 호출하고, 내 서버가 Prosody를 호출합니다.

런타임 API

한 턴의 사용자 입력을 보내면 에이전트가 지식에서 필요한 근거를 찾아 답변과 다음 턴 상태를 반환합니다.

POST/api/v1/agents/chat

Request body

파라미터타입필수설명
agent_idstring필수실행할 에이전트의 ID입니다. Agent Builder에서 확인할 수 있습니다.
messagestring필수사용자의 이번 턴 입력입니다. 음성 상담에서는 STT 결과 텍스트를 넣습니다.
historyarray선택최근 대화 턴입니다. 각 항목은 role과 content를 가집니다.
messagesarray선택history와 같은 용도의 별칭입니다. 기존 채팅 구현을 그대로 연결할 때 사용합니다.
stateobject선택이전 응답에서 받은 compact state입니다. 멀티턴 흐름 유지에 사용합니다.
streamboolean선택true면 Server-Sent Events로 응답을 받습니다.(기본값: false)
Minimal cURL
curl https://console.humelo.com/api/v1/agents/chat \
  -H "Authorization: Bearer ${PROSODY_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "00000000-0000-0000-0000-000000000000",
    "message": "예약 취소 수수료가 어떻게 되나요?",
    "history": []
  }'
JSON response
{
  "agent_id": "00000000-0000-0000-0000-000000000000",
  "agent_name": "라온투어 고객센터",
  "response": "예약 조건에 따라 취소 수수료가 달라질 수 있습니다. 예약번호와 출발일을 알려주시면 확인 기준을 안내드리겠습니다.",
  "matched_intent": "패키지 취소료 기준",
  "handoff_required": false,
  "retrieved_context": [
    {
      "title": "패키지 취소료 기준",
      "content": "여행 개시일 기준 취소 시점별 수수료 규정..."
    }
  ],
  "state": {
    "topic": "cancellation_fee",
    "handoff": false
  },
  "runtime": {
    "mode": "text",
    "voice_engine": "DIVE"
  }
}

스트리밍 응답

채팅 UI에서는 SSE를 사용해 토큰이 도착하는 대로 화면에 붙이는 구성이 자연스럽습니다. 최종 done 이벤트의 state를 저장해 다음 요청에 다시 보내세요.

SSE request
curl https://console.humelo.com/api/v1/agents/chat \
  -N \
  -H "Authorization: Bearer ${PROSODY_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "agent_id": "00000000-0000-0000-0000-000000000000",
    "message": "환불은 얼마나 걸리나요?",
    "stream": true
  }'
EventPayload사용 방식
startmatched_intent, handoff_required, retrieved_context, state런타임이 응답 생성을 시작했음을 표시합니다.
chunkdeltadelta를 현재 답변 문자열 뒤에 이어 붙입니다.
doneresponse, state, retrieved_context최종 답변과 다음 턴 state를 저장합니다.
errorerror일시 오류 안내를 보여주고 서버 로그를 확인합니다.

서버 프록시 패턴

ChannelTalk처럼 웹사이트에 붙이는 위젯도 API Key를 브라우저에 넣으면 안 됩니다. 위젯은 내 서버 엔드포인트를 호출하고, 내 서버가 Prosody API를 호출하는 구조로 두세요.

Next.js route handler
// app/api/agent/chat/route.ts
export async function POST(request: Request) {
  const body = await request.json();

  const response = await fetch("https://console.humelo.com/api/v1/agents/chat", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.PROSODY_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      agent_id: process.env.PROSODY_AGENT_ID,
      message: body.message,
      history: body.history ?? [],
      state: body.state ?? null,
      stream: false,
    }),
  });

  return new Response(await response.text(), {
    status: response.status,
    headers: {
      "Content-Type": response.headers.get("Content-Type") ?? "application/json",
    },
  });
}
Browser widget state
type Turn = { role: "user" | "assistant"; content: string };

let history: Turn[] = [];
let state: Record<string, unknown> | null = null;

async function sendToAgent(message: string) {
  const response = await fetch("/api/agent/chat", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ message, history, state }),
  });

  if (!response.ok) {
    throw new Error("Agent is temporarily unavailable");
  }

  const result = await response.json();
  history = [
    ...history,
    { role: "user", content: message },
    { role: "assistant", content: result.response },
  ].slice(-16);
  state = result.state ?? state;
  return result;
}
멀티턴 상태
  • 최근 8~16턴 정도의 history를 보냅니다.
  • 응답에서 받은 state를 사용자 상담 세션 단위로 저장합니다.
  • 새 상담을 시작할 때는 state를 초기화합니다.
운영 체크리스트
  • API Key는 서버 환경변수나 secret manager에만 둡니다.
  • 프록시에 자체 세션, origin, rate limit 정책을 둡니다.
  • 고객 정보 저장 정책에 맞춰 transcript를 마스킹합니다.
LLM/Agent용 문서

개발 에이전트에게 그대로 넘길 수 있습니다.

우측 상단의 Copy page 메뉴에서 현재 페이지, 전체 문서, ChatGPT/Claude 전달용 프롬프트를 바로 만들 수 있습니다.

llms.txtMarkdown

응답 실패 시

401은 키 설정, 404는 Agent ID와 조직 권한, 500은 일시적인 런타임 오류를 먼저 확인합니다. 사용자 화면에는 일시 오류 안내와 도입 문의/상담 연결 경로를 함께 제공하는 것을 권장합니다.