에이전트 API 로 Tin 을 우리 서비스에 붙이기

Tin 은 흩어진 생각을 선명한 다음 단계로 정리해 주는 에이전트입니다. 보통은 endue 채팅창에서 Tin 과 이야기하지만, API 를 열어 두면 내가 만든 서비스 안에서도 같은 Tin 을 부를 수 있습니다. 메모 앱의 “계획으로 만들기” 버튼 뒤에서, 매일 아침 도는 스크립트 안에서, 설문이 접수될 때마다 움직이는 자동화 속에서요.

API 로 부른 Tin 은 채팅창의 Tin 과 같은 에이전트입니다. 지침, 스킬, 연결한 커넥터, 메모리를 그대로 쓰고, 사용량은 내 계정에 쌓입니다. 따로 서버를 띄우거나 모델을 연결할 필요가 없습니다.

어떻게 연결되나요

1. 스튜디오에서 Tin 전용 API 키를 발급합니다.
2. 우리 서버가 그 키를 실어 Tin 에게 요청을 보냅니다. 요청 본문은 “무엇을 해 달라” 는 문장 하나면 됩니다.
3. Tin 이 답을 돌려줍니다. 주고받은 내용은 endue 의 대화 목록에도 남아서, 나중에 웹에서 그대로 확인할 수 있습니다.

이런 곳에 좋습니다

• 내 앱 안의 기능으로. 사용자가 적은 메모를 Tin 에게 보내고, 돌아온 실행 계획을 우리 화면에 보여 줍니다. 사용자는 endue 를 몰라도 됩니다.
• 정해진 시간에 도는 작업으로. 예약 작업(cron)이 어제 못 끝낸 일을 보내면, Tin 이 오늘 할 일 세 가지로 추려 줍니다. 결과를 사내 게시판이나 우리 DB 에 넣는 것까지 우리 코드가 맡습니다.
• 노코드 자동화 도구에서. Zapier, Make, n8n 처럼 HTTP 요청을 보낼 수 있는 도구라면 코드 없이도 부를 수 있습니다.

결과를 endue 안에서만 받아 보면 충분하다면 루틴이 더 간단합니다. API 는 결과가 우리 시스템으로 들어와야 할 때 고르세요.

준비물

• endue 계정과 에이전트 하나. 이 글에서는 Tin 을 씁니다.
• 요청을 보낼 곳. 터미널, 우리 서비스의 서버, 또는 HTTP 요청을 보낼 수 있는 자동화 도구면 됩니다.
• 키를 보관할 안전한 자리. 서버의 환경 변수나 시크릿 저장소를 권합니다.

1단계. 스튜디오에서 API 열기

Tin 을 열고 상단에서 Studio 로 전환하면 에이전트 구성 화면이 나옵니다. 왼쪽 “01 요청이 들어와요” 칸에 API 카드가 있습니다. 카드를 누르면 오른쪽에 API 패널이 열립니다.

패널 맨 위의 POST 주소가 Tin 을 부르는 엔드포인트입니다. 아래쪽 curl 예시는 복사 버튼 한 번으로 가져갈 수 있고, Tin 의 에이전트 ID 가 이미 들어 있습니다.

2단계. Tin 전용 키 발급하기

키 발급을 누르고 두 가지를 정합니다.

• 키 이름. 이 키를 어디에 쓰는지 적어 두세요. 예: “플래너 앱 서버”. 나중에 대화 기록에 이 이름이 표시되고, 키가 여러 개일 때 무엇을 폐기해야 할지 바로 알 수 있습니다.
• 유효기간. 만료 없음, 30일, 90일, 365일 가운데 고릅니다. 처음 시험할 때는 짧게 두는 편이 안전합니다.

발급을 누르면 sk_ 로 시작하는 키가 딱 한 번 표시됩니다. 이 창을 닫으면 다시 볼 수 없으니 바로 복사해서 안전한 곳에 넣어 두세요. 잃어버렸다면 폐기하고 새로 발급하면 됩니다. 이때 패널 위쪽 예시 요청에도 방금 받은 키가 채워지므로, 그대로 복사해 바로 시험해 볼 수 있습니다.

여기서 만든 키는 Tin 전용입니다. 이 키로는 내 다른 에이전트를 부를 수 없습니다. 모든 에이전트를 부를 수 있는 계정 전체 키는 설정 › 계정 › API 키에서 따로 발급하지만, 한 에이전트만 쓸 거라면 전용 키가 훨씬 안전합니다.

3단계. 첫 요청 보내기

터미널에서 바로 시험해 볼 수 있습니다. 키는 명령어에 직접 쓰지 말고 환경 변수에 넣어 두세요. AGENT_ID 자리에는 스튜디오에서 복사한 주소를 그대로 쓰면 됩니다.

export ENDUE_API_KEY="sk_..."   # 2단계에서 복사한 키

curl -X POST https://platform.endue.ai/api/public/v1/agents/AGENT_ID/invoke \
  -H "Authorization: Bearer $ENDUE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": "이번 주 계획으로 바꿔줘: 우리 카페 소식지를 작게 시작하고 싶어. 이번 주에 쓸 수 있는 시간은 5시간 정도야."}'

Tin 이 답을 다 쓰면 이런 응답이 돌아옵니다.

{
  "success": true,
  "data": {
    "run_id": "...",
    "session_id": "cnv_...",
    "conversation_id": "cnv_...",
    "agent_id": "...",
    "status": "completed",
    "finish_reason": "final",
    "output_text": "주말을 쓰지 않고도 첫 호를 내보낼 수 있게 한 주를 짜 봤어요. ...",
    "usage": { "input_tokens": 1830, "output_tokens": 264, "total_tokens": 2094 }
  }
}

눈여겨볼 값은 세 개입니다.

• output_text: Tin 의 답. 우리 화면에 보여 줄 내용입니다.
• session_id: 이 대화의 번호. 다음 요청에 돌려보내면 대화가 이어집니다. conversation_id 에도 같은 값이 들어 있고, 스튜디오 안내문에 적힌 이름이 이쪽입니다.
• status: completed 면 끝까지 답한 것입니다. incomplete 면 Tin 이 정해진 단계 안에 끝내지 못했거나 사람의 결정이 필요한 지점에서 멈춘 것이니, 요청을 더 구체적으로 다시 보내 보세요.

4단계. 대화 이어가기

사용자가 “수요일은 시간이 안 나” 라고 답했다면, 앞 응답의 session_id 를 실어 보냅니다. Tin 은 앞에서 짠 계획을 기억한 채로 고쳐 줍니다.

{
  "input": "수요일은 시간이 안 나. 목요일로 옮겨서 다시 짜 줘.",
  "session_id": "cnv_..."
}

session_id 를 빼면 새 대화가 시작됩니다. 사용자마다, 또는 메모마다 대화를 따로 두고 싶다면 우리 DB 에 session_id 를 함께 저장해 두면 됩니다.

5단계. 우리 서비스에 붙이기

예를 들어 메모 앱에 “계획으로 만들기” 버튼을 단다고 해 보겠습니다. 중요한 원칙은 하나입니다. Tin 을 부르는 코드는 서버에 둡니다. 브라우저나 모바일 앱에 키를 넣으면 누구나 꺼내 볼 수 있습니다. 화면은 우리 서버에 요청하고, 우리 서버가 Tin 을 부릅니다.

Node.js 서버라면 이 정도입니다.

// 서버 코드. 키는 환경 변수에서 읽습니다.
const TIN_URL = 'https://platform.endue.ai/api/public/v1/agents/AGENT_ID/invoke';

export async function askTin(input, sessionId) {
  const res = await fetch(TIN_URL, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.ENDUE_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(sessionId ? { input, session_id: sessionId } : { input }),
  });
  const body = await res.json();
  if (!res.ok) throw new Error(body.error?.message ?? `HTTP ${res.status}`);
  return { plan: body.data.output_text, sessionId: body.data.session_id };
}

매일 아침 도는 파이썬 스크립트라면 더 짧습니다.

import os
import requests

res = requests.post(
    "https://platform.endue.ai/api/public/v1/agents/AGENT_ID/invoke",
    headers={"Authorization": f"Bearer {os.environ['ENDUE_API_KEY']}"},
    json={"input": "어제 못 끝낸 일: 견적서 회신, 원두 발주, 블로그 초안. 오늘 할 일 세 가지로 정리해줘."},
    timeout=120,
)
res.raise_for_status()
print(res.json()["data"]["output_text"])

기본 호출은 Tin 이 답을 다 쓸 때까지 기다렸다가 한 번에 돌려줍니다. 길게 생각하는 요청이면 수십 초가 걸릴 수 있으니 타임아웃을 넉넉히 잡으세요. 채팅처럼 글자가 써지는 모습을 보여 주고 싶다면 요청에 "stream": true 를 넣습니다. 그러면 웹 채팅과 같은 SSE 로 run_created, delta(글자 조각), done 이벤트가 차례로 옵니다.

호출 기록은 endue 에 남습니다

API 로 주고받은 대화는 Tin 의 사이드바 API 묶음에 모입니다. 호출자의 요청은 “API 호출자” 로 표시되고, 제목 옆에는 어떤 키로 들어온 요청인지가 보입니다. 답이 이상했다면 여기서 Tin 이 무엇을 받고 어떻게 답했는지 그대로 확인할 수 있습니다.

이 대화는 읽기 전용입니다. 이어서 말을 거는 것은 같은 session_id 를 실은 API 호출로만 할 수 있습니다.

스튜디오 구성 화면에서도 달라진 점이 보입니다. API 카드에 방금 만든 키가 활성 상태로 붙고, Tin 에게 이어지는 선이 생깁니다.

API 로 부를 때 알아 둘 점

API 호출에는 화면 앞에 앉아 있는 사람이 없습니다. 그래서 endue 는 API 요청을 지켜보는 사람이 없는 실행으로 다룹니다.

• 메일 발송이나 삭제처럼 밖으로 내보내거나 지우는 동작은 승인을 기다리지 않고 거절됩니다. 조회처럼 읽기만 하는 동작은 평소대로 합니다.
• Tin 이 되물어야 하는 상황이 와도 답해 줄 사람이 없습니다. 요청에 필요한 정보(기한, 쓸 수 있는 시간, 원하는 형식)를 처음부터 담아 보내세요.

Tin 에게는 초안과 계획을 받아 오고, 실제로 보내거나 저장하는 일은 우리 코드가 하도록 나누면 가장 매끄럽습니다.

키를 안전하게 쓰는 법

• 키는 서버에만. 브라우저 코드, 모바일 앱, git 저장소에 넣지 않습니다.
• 쓰는 곳마다 키를 따로. “플래너 앱 서버”, “아침 요약 스크립트” 처럼 나눠 두면, 하나가 새어도 그 키만 폐기하면 됩니다.
• 폐기는 바로. API 패널에서 폐기를 누르면 1분 안에 그 키로 들어오는 요청이 막힙니다.
• 유효기간을 두세요. 만료가 가까워지거나 지난 키는 패널과 스튜디오 화면에 표시됩니다.

응답 코드가 알려 주는 것

• 401: 키가 없거나 틀렸거나, 만료·폐기된 키입니다.
• 403: 다른 에이전트 전용 키로 Tin 을 불렀습니다.
• 404: 에이전트 ID 가 틀렸거나, 다른 에이전트의 session_id 를 보냈습니다.
• 409: 같은 세션에서 앞 요청이 아직 실행 중입니다. 끝난 뒤 다시 보내세요.
• 402: 요금제 사용 한도에 닿았습니다. 사용량 화면에서 남은 양을 확인하세요.

더 자세한 요청 필드와 제한은 에이전트 API 문서에 정리되어 있습니다.