내 앱의 버튼 뒤에 내가 만든 AI 를: endue Agent API

메모 앱에 “이번 주 계획으로 만들기” 버튼을 넣고 싶다고 해 보겠습니다. 사용자가 적어 둔 할 일을 읽고, 무리 없는 순서로 정리해 주는 기능입니다. 이미 endue 에서 내 방식대로 계획을 세우는 에이전트를 만들었다면, 그 에이전트를 앱에서도 부를 수 있으면 좋겠죠.

Agent API 는 내가 구성한 에이전트를 HTTP 요청으로 호출하는 기능입니다. 앱이나 스크립트에서 요청을 보내면, 그 에이전트가 자신의 지침과 연결된 능력을 사용해 처리하고 응답을 돌려줍니다. 에이전트의 역할을 다듬는 일은 endue 에서, 사용자가 만지는 화면과 서비스 흐름은 내 앱에서 이어갈 수 있습니다.

Live로 공개 대화 링크를 제공했다면, API 는 그 다음 선택지가 됩니다. 내 서비스의 화면 안에서 에이전트의 도움을 제공하고 싶을 때 사용합니다.

이 글의 스크린샷은 실제 제품 UI 에 설명용 에이전트와 대화 데이터를 넣어 캡처했습니다. 아래 코드는 연결 방법을 설명하는 서버 측 예제입니다.

AI 를 붙이고 싶은 자리에 맞춰 시작하세요

API 를 사용할 곳에 꼭 큰 채팅창이 있어야 하는 것은 아닙니다. 사용자가 이미 하던 일 옆에 버튼 하나를 놓는 방식으로도 시작할 수 있습니다.

내 서비스의 화면	에이전트에게 맡길 일	사용자가 받는 것
메모·할 일 목록	주어진 시간에 맞춰 우선순위 정리	이번 주 실행 계획
고객 문의 관리	문의 내용 분류와 답변 초안 작성	담당자가 검토할 초안
문서 편집기	정해 둔 기준으로 문장 검토	수정 제안과 확인할 항목
업무 보고 화면	전달한 자료에서 핵심 변화 정리	출처를 확인할 수 있는 요약

이때 에이전트의 지침에는 서비스가 원하는 결과를 구체적으로 담습니다. 계획 도우미라면 “주어진 시간 안에서 세 가지를 고르고, 각 항목에 예상 소요 시간을 붙인다”처럼요. 사용자는 버튼을 누를 때마다 이 지침을 다시 쓸 필요가 없습니다.

처음에는 입력과 결과가 분명한 기능 하나를 고르는 편이 좋습니다. 답변이 괜찮은지 판단하기 쉽고, 서비스에 필요한 대기 화면과 오류 처리도 작게 시작할 수 있습니다.

내가 다듬은 에이전트를 그대로 호출합니다

API 의 호출 대상은 에이전트입니다. endue 에서 설정한 역할과 지침, 사용하도록 부여한 도구를 기준으로 요청을 처리합니다. 서비스용 말투나 답변 형식을 고치고 싶을 때도 그 에이전트의 구성을 조정합니다.

모델을 선택하는 자리도 에이전트 설정에 있습니다. 지원 모델을 바꿔도 에이전트의 지침·메모리·연결 설정은 유지됩니다. 모델마다 도구 호출과 입력 형식 지원이 다르므로, 변경한 뒤에는 앱에서 쓰는 대표 요청을 다시 확인하세요. 모델 선택 안내에 선택 기준이 정리되어 있습니다.

이 구조의 실용적인 장점은 에이전트 설정과 앱의 사용 경험을 각각 다듬을 수 있다는 것입니다. 앱은 어떤 상황에서 AI 를 부르고 결과를 어떻게 보여 줄지 담당합니다. endue 에서는 그 요청을 맡을 에이전트의 행동을 조정합니다.

구성 화면에서 호출 주소와 전용 키를 준비합니다

에이전트의 구성 화면에서 API를 엽니다. 패널에 호출 주소와 복사할 수 있는 요청 예제가 나타납니다. 에이전트 ID 를 따로 찾아 조합하는 대신, 화면의 주소를 가져와 시작할 수 있습니다.

키 이름에는 사용할 곳을 적어 두세요. “플래너 앱 서버”, “문의 초안 도구”처럼 이름을 붙이면 나중에 어느 연결인지 구분하기 쉽습니다. 유효기간도 이 용도에 맞게 정합니다.

발급한 키는 한 번만 표시됩니다. 복사한 뒤 서버의 환경 변수나 시크릿 저장소에 보관하세요. 브라우저나 모바일 앱 안에 키를 넣지 않습니다. 사용자 화면은 내 서버에 요청하고, 내 서버가 이 키로 에이전트를 호출하는 구조입니다.

에이전트 전용 키는 호출 범위를 해당 에이전트로 제한합니다. 한 에이전트만 필요한 앱에는 그 범위에 맞는 키를 주면 됩니다. 연결을 끝낼 때는 API 패널에서 키를 폐기할 수 있습니다.

첫 호출은 작은 요청 하나로 확인합니다

아래 예제의 ENDUE_AGENT_ID에는 API 패널에서 확인한 에이전트 ID 를, ENDUE_API_KEY에는 발급받은 키를 서버 환경 변수로 설정합니다.

curl --fail-with-body --max-time 120 \
  "https://platform.endue.ai/api/public/v1/agents/${ENDUE_AGENT_ID}/invoke" \
  -H "Authorization: Bearer ${ENDUE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"input":"카페 소식지를 처음 발행하려고 해. 이번 주에 쓸 수 있는 시간은 5시간이야. 할 일 세 가지와 예상 시간을 정리해 줘."}'

응답에서 앱이 우선 살펴볼 값은 status, output_text, session_id입니다. output_text는 사용자에게 보여 줄 답이고, session_id는 다음 요청에서 이어갈 대화를 가리킵니다. 응답의 형태는 다음과 같습니다.

{
  "success": true,
  "data": {
    "status": "completed",
    "output_text": "이번 주 5시간을 준비, 초안 작성, 검토에 나눠 보겠습니다…",
    "session_id": "cnv_example"
  }
}

위 내용은 응답 형태를 보여 주는 예시입니다. 실제 답과 세션 ID 는 호출 결과에서 가져옵니다. status가 incomplete이면 결과가 끝까지 완성되지 않은 것이므로, 앱에서 완료된 답변처럼 표시하지 말고 재요청이나 확인 동선을 제공해야 합니다.

대화는 내 앱 안에서도 이어집니다

첫 계획을 본 사용자가 “수요일에는 시간이 없어”라고 말하면, 이전 응답의 session_id를 다음 요청에 담습니다.

{
  "input": "수요일에는 시간이 없어. 목요일과 금요일에 나눠서 다시 짜 줘.",
  "session_id": "cnv_example"
}

이렇게 하면 앞에서 만든 계획을 바탕으로 대화가 이어집니다. session_id를 생략하면 새 대화를 시작합니다. 내 서비스에서는 로그인한 사용자와 해당 세션의 관계를 서버에 저장하고, 같은 사람의 후속 요청에만 그 세션을 사용하세요.

Node.js 서버에서 한 번 호출하는 함수는 다음처럼 만들 수 있습니다.

// 서버 전용 코드. ENDUE_API_KEY 는 클라이언트에 전달하지 않습니다.
export async function askAgent(input, sessionId) {
  const agentId = process.env.ENDUE_AGENT_ID;
  const key = process.env.ENDUE_API_KEY;
  if (!agentId || !key) throw new Error('Agent API 설정이 필요합니다.');

  const response = await fetch(
    `https://platform.endue.ai/api/public/v1/agents/${encodeURIComponent(agentId)}/invoke`,
    {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${key}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ input, ...(sessionId ? { session_id: sessionId } : {}) }),
      signal: AbortSignal.timeout(120_000),
    },
  );

  if (!response.ok) throw new Error(`Agent API HTTP ${response.status}`);
  const body = await response.json();
  if (!body.success || body.data?.status !== 'completed') {
    throw new Error('요청이 완료되지 않았습니다. 실행 결과를 확인해 주세요.');
  }
  return { text: body.data.output_text, sessionId: body.data.session_id };
}

이 함수 앞에는 내 서비스의 사용자 인증과 요청 검사를 둡니다. 브라우저가 임의로 보낸 세션 ID 를 그대로 넘기지 말고, 서버가 해당 사용자에게 저장해 둔 세션을 선택해야 합니다.

같은 세션에서는 요청이 순서대로 이어져야 합니다. 앞 요청이 끝나기 전에 다시 보내면 충돌 응답을 받을 수 있으므로, 처리 중 표시와 중복 전송 방지도 함께 넣으세요. 답을 생성되는 대로 보여 주고 싶다면 API 의 stream: true 옵션으로 스트리밍 응답을 받을 수 있습니다.

서비스에서 들어온 요청을 endue 에서 확인합니다

API 호출로 나눈 대화도 기록으로 남습니다. 에이전트의 API 대화 묶음에서 무엇을 요청했고 어떤 답이 나왔는지 읽을 수 있습니다. 아래 화면에는 “플래너 앱 서버”에서 보낸 요청과 그 응답이 표시되어 있습니다.

답이 기대와 다를 때 이 기록이 도움이 됩니다. 앱에서 필요한 정보가 빠졌는지, 지침이 모호했는지, 요청한 범위가 너무 컸는지 확인할 수 있기 때문입니다. 해당 대화는 읽기 전용이며, 이어지는 요청은 API 에서 같은 세션으로 보냅니다.

키와 대화를 사용처별로 나누면 연결을 관리하기도 쉬워집니다. 처음에는 계획 도우미 하나로 시작하고, 나중에 문의 초안 도구를 추가할 때 새 키와 세션 범위를 정하면 됩니다.

첫 연동은 초안과 제안부터 시작하세요

API 실행 중에는 사용자가 endue 의 승인 카드 앞에 앉아 있지 않습니다. 승인이 필요한 동작이 생겨도 내 앱의 호출만으로 그 카드를 처리할 수 있다고 가정하면 안 됩니다. 처음에는 읽기·분류·요약·초안처럼 결과를 받아 검토할 수 있는 일을 고르면 전체 흐름이 단순해집니다.

계획 앱에서는 에이전트에게 계획안을 받고, 사용자가 “적용”을 눌렀을 때 내 앱의 일정으로 저장할 수 있습니다. 문의 도구에서는 답변 초안을 받은 뒤 담당자가 확인하고 발송하게 할 수 있습니다. 에이전트가 제안하는 부분과 내 서비스가 실행하는 부분을 정하면 사용 경험도 설명하기 쉬워집니다.

실제 연동에서는 요금제 한도, 호출 실패, 응답 대기 시간도 처리해야 합니다. 사용자의 재시도를 무조건 자동 실행으로 바꾸기보다, 첫 요청의 처리 상태를 확인할 수 있도록 구성하세요. 자세한 호출 규칙은 에이전트 API 문서에서 확인할 수 있습니다.

내 앱에서 AI 의 도움이 필요한 순간 하나를 골라 보세요. 그 순간에 맞는 에이전트를 다듬고, 전용 키로 한 번 호출해 보는 것이 시작입니다. 이후 작업을 분석·작성·검토로 나눠 운영하고 싶다면 Space 에서 AI 팀을 구성하는 방법도 살펴볼 수 있습니다.