Ability API 엔드포인트 사용하기

에이전트리아(Agentria)에서 완성한 어빌리티(Ability, 워크플로)를 API로 배포했다면, 외부 서비스에서 이 API 엔드포인트(Endpoint)를 호출해 어빌리티를 실행할 수 있습니다. Ability API는 비동기(Async) 실행, SSE(Server-Sent Events) 스트리밍, 상태 조회, 요청 취소를 지원하는 REST API입니다.

이 가이드에서는 각 엔드포인트를 호출하는 방법과, 실행 결과를 안전하게 받아오는 방법을 안내합니다.

사전 준비

• 어빌리티가 API로 배포되어 있어야 합니다. 아직 배포하지 않았다면 🔗API 배포 가이드를 먼저 진행합니다.

• API 배포 시 발급받은 엔드포인트 코드(api_endpoint)와 API 키(Key)가 필요합니다.

Base URL과 인증 방식은 모든 엔드포인트에 공통으로 적용됩니다.

Base URL

모든 요청에는 X-API-KEY 헤더가 필요합니다.

1단계: 어빌리티 비동기 실행하기

어빌리티를 비동기로 실행하고 request_id(트랜잭션 ID)를 즉시 응답받습니다. 실행 결과는 상태 조회 API(3단계) 또는 콜백(Callback) URL로 받을 수 있습니다.

Path Parameters

Headers

Request Body (multipart/form-data)

params_json에는 어빌리티에 정의된 입력 파라미터에 맞는 JSON 객체를 전달합니다. 필드는 어빌리티마다 다르므로, 해당 어빌리티의 입력 스펙을 먼저 확인합니다.

{
  "inputData": "분석할 텍스트입니다.",
  "option1": "value1",
  "option2": 123
}

{
  "inputData": "분석할 텍스트입니다.",
  "option1": "value1",
  "option2": 123
}

{
  "inputData": "분석할 텍스트입니다.",
  "option1": "value1",
  "option2": 123
}

external_request_id는 클라이언트가 요청을 보내기 전에 직접 발급하는 식별자로, 두 가지 역할을 합니다. 첫째, 동일한 external_request_id로 재요청이 오면 서버가 같은 요청으로 판단해 409 Conflict로 거부하므로, 네트워크 재시도 등으로 인한 중복 실행(멱등성, Idempotency 보장)을 방지할 수 있습니다. 둘째, 클라이언트가 요청 시점에 이미 이 식별자를 확보해두는 방식이므로, 서버가 응답으로 request_id를 돌려주기 전부터 이 값으로 해당 요청을 추적·조회할 수 있습니다.

Response

성공하면 200 OK 상태와 함께 요청 ID(문자열)를 응답받습니다.

"a1b2c3d4-e5f6-7890-abcd-ef1234567890"

"a1b2c3d4-e5f6-7890-abcd-ef1234567890"

"a1b2c3d4-e5f6-7890-abcd-ef1234567890"

Error Responses

요청 예시

curl -X POST "{host}/api/ability/my-ability" \
  -H "X-API-KEY: your-api-key" \
  -F 'params_json={"inputData": "안녕하세요"}' \
  -F 'callback_url=https://my-service.com/webhook' \
  -F 'external_request_id=order-12345' \
  -F 'debug=false'

curl -X POST "{host}/api/ability/my-ability" \
  -H "X-API-KEY: your-api-key" \
  -F 'params_json={"inputData": "안녕하세요"}' \
  -F 'callback_url=https://my-service.com/webhook' \
  -F 'external_request_id=order-12345' \
  -F 'debug=false'

curl -X POST "{host}/api/ability/my-ability" \
  -H "X-API-KEY: your-api-key" \
  -F 'params_json={"inputData": "안녕하세요"}' \
  -F 'callback_url=https://my-service.com/webhook' \
  -F 'external_request_id=order-12345' \
  -F 'debug=false'

2단계: SSE로 실시간 스트리밍 받기

어빌리티를 실행하면서 SSE를 통해 각 노드의 실행 결과를 실시간으로 수신합니다.

Path Parameters / Headers

1단계와 동일하게 api_endpoint 경로 파라미터와 X-API-KEY 헤더가 필요합니다.

Request Body (multipart/form-data)

Response

응답의 Content-Type은 text/event-stream입니다.

응답 헤더 X-Ability-Request-Id로 요청 ID를 받습니다. 첫 이벤트 수신 전에 연결이 끊기더라도 이 값으로 재조회할 수 있으며, 첫 request_id 이벤트와 동일한 값입니다.

주의: X-Request-Id 헤더는 HTTP 추적용으로 쓰이는 별개의 값이므로 X-Ability-Request-Id와 혼동하지 않도록 주의합니다.

각 이벤트는 표준 EventSource 포맷과 호환되지 않는 자체 정의 SSE 라인 포맷으로 전달됩니다. 빈 줄로 이벤트가 구분됩니다.

event_type 값과 body 형태

event_type이 request_id면 스트림 시작을 알리는 메타 이벤트, node면 중간 이벤트, response 또는 error면 최종 이벤트입니다. 또는 body JSON의 status 값이 COMPLETED·FAILURE이면 최종 이벤트로 판단할 수 있습니다. 스트림이 종료되면 연결이 닫힙니다.

스트림 유실 시 결과 재조회

네트워크 유실 등으로 최종 이벤트를 받지 못한 경우, 같은 요청을 재전송하면 어빌리티가 재실행되므로 재조회를 사용해야 합니다. 서버는 스트림 단절과 무관하게 실행을 완료하고 결과를 기록합니다.

• request_id 이벤트(또는 X-Ability-Request-Id 헤더)로 받은 요청 ID로 GET /{api_endpoint}/{request_id}/result를 폴링합니다 (3단계 참고).

• external_request_id를 부여했다면 GET /{api_endpoint}/external/{external_request_id}/result로도 조회할 수 있습니다 (3단계 참고).

status가 COMPLETED·FAILURE·CANCELED가 될 때까지 폴링합니다. 같은 external_request_id로 재전송하면 409 Conflict로 거부되므로, 외부 ID를 함께 쓰면 실수로 인한 중복 실행도 방지할 수 있습니다.

요청 예시

curl -N -X POST "{host}/api/ability/my-ability/sse" \
  -H "X-API-KEY: your-api-key" \
  -F 'params_json={"inputData":"안녕하세요"}' \
  -F 'debug=false'

curl -N -X POST "{host}/api/ability/my-ability/sse" \
  -H "X-API-KEY: your-api-key" \
  -F 'params_json={"inputData":"안녕하세요"}' \
  -F 'debug=false'

curl -N -X POST "{host}/api/ability/my-ability/sse" \
  -H "X-API-KEY: your-api-key" \
  -F 'params_json={"inputData":"안녕하세요"}' \
  -F 'debug=false'

• N(-no-buffer) 옵션은 필수입니다. 붙이지 않으면 청크가 몰려서 전달됩니다.

실제 응답 예시 (wire)

JavaScript 클라이언트 예시

const formData = new FormData();
formData.append('params_json', JSON.stringify({ inputData: '안녕하세요' }));
formData.append('debug', 'false');

const response = await fetch(`${host}/api/ability/my-ability/sse`, {
  method: 'POST',
  headers: { 'X-API-KEY': 'your-api-key' },
  body: formData
});

// 스트림 유실 시 GET .../{requestId}/result 재조회용. 첫 request_id 이벤트로도 갱신됩니다.
let requestId = response.headers.get('X-Ability-Request-Id');

// 한 번의 read() 가 여러 이벤트를 합쳐서 줄 수 있으므로 line-buffered 파싱이 필요합니다.
const reader = response.body.getReader();
const decoder = new TextDecoder();
let buf = '';
let currentEvent = null;

const events = [];

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  buf += decoder.decode(value, { stream: true });

  let nl;
  while ((nl = buf.indexOf('\n')) !== -1) {
    const line = buf.slice(0, nl);
    buf = buf.slice(nl + 1);

    if (line === '') {
      currentEvent = null; // 이벤트 경계
      continue;
    }
    if (line.endsWith(':')) {
      currentEvent = line.slice(0, -1); // "node" | "response" | "error"
      continue;
    }
    // body 라인 — JSON.parse 시도 후 실패하면 raw string으로 처리
    let body;
    try { body = JSON.parse(line); } catch { body = line; }

    if (currentEvent === 'request_id') {
      requestId = body; // plain UUID 문자열
    } else if (currentEvent === 'node') {
      console.log('[node]', body.ability_node_id, body.ability_node_name, body.results);
    } else if (currentEvent === 'response' || currentEvent === 'error') {
      events.push(body);
      console.log(`[${currentEvent}] status=${body.status}`, body.results);
    }
  }
}

// 최종 결과 = events[events.length - 1]
const final = events[events.length - 1];
if (final?.status === 'FAILURE') {
  console.error('실패:', final.failure_reason);
}

// 최종 이벤트 없이 스트림이 끊긴 경우 — 재전송(재실행) 대신 재조회
if (!final && requestId) {
  const res = await fetch(`${host}/api/ability/my-ability/${requestId}/result`, {
    headers: { 'X-API-KEY': 'your-api-key' }
  });
  const result = await res.json(); // status 가 COMPLETED/FAILURE 가 될 때까지 폴링
}

const formData = new FormData();
formData.append('params_json', JSON.stringify({ inputData: '안녕하세요' }));
formData.append('debug', 'false');

const response = await fetch(`${host}/api/ability/my-ability/sse`, {
  method: 'POST',
  headers: { 'X-API-KEY': 'your-api-key' },
  body: formData
});

// 스트림 유실 시 GET .../{requestId}/result 재조회용. 첫 request_id 이벤트로도 갱신됩니다.
let requestId = response.headers.get('X-Ability-Request-Id');

// 한 번의 read() 가 여러 이벤트를 합쳐서 줄 수 있으므로 line-buffered 파싱이 필요합니다.
const reader = response.body.getReader();
const decoder = new TextDecoder();
let buf = '';
let currentEvent = null;

const events = [];

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  buf += decoder.decode(value, { stream: true });

  let nl;
  while ((nl = buf.indexOf('\n')) !== -1) {
    const line = buf.slice(0, nl);
    buf = buf.slice(nl + 1);

    if (line === '') {
      currentEvent = null; // 이벤트 경계
      continue;
    }
    if (line.endsWith(':')) {
      currentEvent = line.slice(0, -1); // "node" | "response" | "error"
      continue;
    }
    // body 라인 — JSON.parse 시도 후 실패하면 raw string으로 처리
    let body;
    try { body = JSON.parse(line); } catch { body = line; }

    if (currentEvent === 'request_id') {
      requestId = body; // plain UUID 문자열
    } else if (currentEvent === 'node') {
      console.log('[node]', body.ability_node_id, body.ability_node_name, body.results);
    } else if (currentEvent === 'response' || currentEvent === 'error') {
      events.push(body);
      console.log(`[${currentEvent}] status=${body.status}`, body.results);
    }
  }
}

// 최종 결과 = events[events.length - 1]
const final = events[events.length - 1];
if (final?.status === 'FAILURE') {
  console.error('실패:', final.failure_reason);
}

// 최종 이벤트 없이 스트림이 끊긴 경우 — 재전송(재실행) 대신 재조회
if (!final && requestId) {
  const res = await fetch(`${host}/api/ability/my-ability/${requestId}/result`, {
    headers: { 'X-API-KEY': 'your-api-key' }
  });
  const result = await res.json(); // status 가 COMPLETED/FAILURE 가 될 때까지 폴링
}

const formData = new FormData();
formData.append('params_json', JSON.stringify({ inputData: '안녕하세요' }));
formData.append('debug', 'false');

const response = await fetch(`${host}/api/ability/my-ability/sse`, {
  method: 'POST',
  headers: { 'X-API-KEY': 'your-api-key' },
  body: formData
});

// 스트림 유실 시 GET .../{requestId}/result 재조회용. 첫 request_id 이벤트로도 갱신됩니다.
let requestId = response.headers.get('X-Ability-Request-Id');

// 한 번의 read() 가 여러 이벤트를 합쳐서 줄 수 있으므로 line-buffered 파싱이 필요합니다.
const reader = response.body.getReader();
const decoder = new TextDecoder();
let buf = '';
let currentEvent = null;

const events = [];

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  buf += decoder.decode(value, { stream: true });

  let nl;
  while ((nl = buf.indexOf('\n')) !== -1) {
    const line = buf.slice(0, nl);
    buf = buf.slice(nl + 1);

    if (line === '') {
      currentEvent = null; // 이벤트 경계
      continue;
    }
    if (line.endsWith(':')) {
      currentEvent = line.slice(0, -1); // "node" | "response" | "error"
      continue;
    }
    // body 라인 — JSON.parse 시도 후 실패하면 raw string으로 처리
    let body;
    try { body = JSON.parse(line); } catch { body = line; }

    if (currentEvent === 'request_id') {
      requestId = body; // plain UUID 문자열
    } else if (currentEvent === 'node') {
      console.log('[node]', body.ability_node_id, body.ability_node_name, body.results);
    } else if (currentEvent === 'response' || currentEvent === 'error') {
      events.push(body);
      console.log(`[${currentEvent}] status=${body.status}`, body.results);
    }
  }
}

// 최종 결과 = events[events.length - 1]
const final = events[events.length - 1];
if (final?.status === 'FAILURE') {
  console.error('실패:', final.failure_reason);
}

// 최종 이벤트 없이 스트림이 끊긴 경우 — 재전송(재실행) 대신 재조회
if (!final && requestId) {
  const res = await fetch(`${host}/api/ability/my-ability/${requestId}/result`, {
    headers: { 'X-API-KEY': 'your-api-key' }
  });
  const result = await res.json(); // status 가 COMPLETED/FAILURE 가 될 때까지 폴링
}

참고 (Python 클라이언트): 위와 동일한 라인 버퍼링이 필요합니다. httpx.AsyncClient.stream()의 aiter_lines()는 한 줄씩 값을 넘겨주므로, node: / response: / error: 접두 라인은 JSON 파싱 오류로 건너뛰고 JSON 라인만 파싱하면 됩니다. 단, request_id 이벤트의 body(plain UUID)는 JSON이 아니므로, 재조회용 ID가 필요하면 직전 라인이 request_id:인지 추적하거나 응답 헤더 X-Ability-Request-Id를 사용합니다.

3단계: 요청 상태·결과 조회하기

비동기 실행 요청의 처리 상태와 결과를 조회합니다.

두 엔드포인트는 동일한 응답을 반환합니다.

Path Parameters

Response

성공하면 200 OK 상태와 함께 아래 형태의 결과를 응답받습니다.

{
  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "external_request_id": null,
  "chat_room_id": null,
  "status": "COMPLETED",
  "failure_reason": null,
  "results": {
    "output": "어빌리티 실행 결과"
  },
  "artifact_metadata_json": null,
  "request_params_json": "{\"inputData\":\"안녕하세요\"}",
  "result_metadata_json": null,
  "requested_time": "2026-01-15T10:30:00",
  "updated_time": "2026-01-15T10:31:00"
}

{
  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "external_request_id": null,
  "chat_room_id": null,
  "status": "COMPLETED",
  "failure_reason": null,
  "results": {
    "output": "어빌리티 실행 결과"
  },
  "artifact_metadata_json": null,
  "request_params_json": "{\"inputData\":\"안녕하세요\"}",
  "result_metadata_json": null,
  "requested_time": "2026-01-15T10:30:00",
  "updated_time": "2026-01-15T10:31:00"
}

{
  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "external_request_id": null,
  "chat_room_id": null,
  "status": "COMPLETED",
  "failure_reason": null,
  "results": {
    "output": "어빌리티 실행 결과"
  },
  "artifact_metadata_json": null,
  "request_params_json": "{\"inputData\":\"안녕하세요\"}",
  "result_metadata_json": null,
  "requested_time": "2026-01-15T10:30:00",
  "updated_time": "2026-01-15T10:31:00"
}

external_request_id는 요청 시 외부 ID를 부여한 경우에만 값이 채워지며, 그 외에는 null입니다.

status 값

요청 예시

curl -X GET "{host}/api/ability/my-ability/a1b2c3d4-e5f6-7890-abcd-ef1234567890/status" \
  -H "X-API-KEY: your-api-key"

curl -X GET "{host}/api/ability/my-ability/a1b2c3d4-e5f6-7890-abcd-ef1234567890/status" \
  -H "X-API-KEY: your-api-key"

curl -X GET "{host}/api/ability/my-ability/a1b2c3d4-e5f6-7890-abcd-ef1234567890/status" \
  -H "X-API-KEY: your-api-key"

외부 요청 ID로 조회하기

요청 시 external_request_id를 부여했다면, 해당 값으로도 동일한 응답을 조회할 수 있습니다.

curl -X GET "{host}/api/ability/my-ability/external/order-12345/status" \
  -H "X-API-KEY: your-api-key"

curl -X GET "{host}/api/ability/my-ability/external/order-12345/status" \
  -H "X-API-KEY: your-api-key"

curl -X GET "{host}/api/ability/my-ability/external/order-12345/status" \
  -H "X-API-KEY: your-api-key"

4단계: 요청 취소하기

진행 중인 비동기 요청을 취소합니다.

Path Parameters

Response

성공하면 200 OK 상태와 함께 true를 응답받습니다.

Error Responses

요청 예시

curl -X DELETE "{host}/api/ability/my-ability/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "X-API-KEY: your-api-key"

curl -X DELETE "{host}/api/ability/my-ability/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "X-API-KEY: your-api-key"

curl -X DELETE "{host}/api/ability/my-ability/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "X-API-KEY: your-api-key"

여러 요청 한 번에 취소하기

여러 개의 비동기 요청을 한 번에 취소할 수도 있습니다.

curl -X DELETE "{host}/api/ability/my-ability?request_ids=id-001&request_ids=id-002&request_ids=id-003" \
  -H "X-API-KEY: your-api-key"

curl -X DELETE "{host}/api/ability/my-ability?request_ids=id-001&request_ids=id-002&request_ids=id-003" \
  -H "X-API-KEY: your-api-key"

curl -X DELETE "{host}/api/ability/my-ability?request_ids=id-001&request_ids=id-002&request_ids=id-003" \
  -H "X-API-KEY: your-api-key"

전체 흐름 한눈에 보기

목적에 따라 아래 네 가지 흐름 중 하나를 선택해 사용합니다.

흐름 1: 비동기 실행 + 폴링(Polling)

흐름 2: 비동기 실행 + 콜백(Callback)

콜백 페이로드 예시입니다.

// external_request_id를 부여한 요청의 콜백 — 키 포함
{
  "request_id": "a1b2c3d4-...",
  "external_request_id": "order-12345",
  "status": "COMPLETED",
  "results": { ... },
  "failure_reason": null
}

// external_request_id를 부여하지 않은 요청의 콜백 — 키 자체가 생략됨
{
  "request_id": "a1b2c3d4-...",
  "status": "COMPLETED",
  "results": { ... },
  "failure_reason": null
}

// external_request_id를 부여한 요청의 콜백 — 키 포함
{
  "request_id": "a1b2c3d4-...",
  "external_request_id": "order-12345",
  "status": "COMPLETED",
  "results": { ... },
  "failure_reason": null
}

// external_request_id를 부여하지 않은 요청의 콜백 — 키 자체가 생략됨
{
  "request_id": "a1b2c3d4-...",
  "status": "COMPLETED",
  "results": { ... },
  "failure_reason": null
}

// external_request_id를 부여한 요청의 콜백 — 키 포함
{
  "request_id": "a1b2c3d4-...",
  "external_request_id": "order-12345",
  "status": "COMPLETED",
  "results": { ... },
  "failure_reason": null
}

// external_request_id를 부여하지 않은 요청의 콜백 — 키 자체가 생략됨
{
  "request_id": "a1b2c3d4-...",
  "status": "COMPLETED",
  "results": { ... },
  "failure_reason": null
}

외부 ID가 없는 요청은 external_request_id 키 자체를 콜백 페이로드에 포함하지 않습니다. 기존 방식 그대로 유지되므로 이전 연동 코드와도 호환됩니다.

흐름 3: 실시간 스트리밍

흐름 4: 요청 취소

다음 단계

Ability API 엔드포인트 사용법을 확인했습니다.

이제 외부 서비스에서 어빌리티를 직접 호출해 실행 결과를 받아올 수 있습니다.

• 🔗API 배포 가이드에서 엔드포인트와 API 키 발급 절차를 다시 확인할 수 있습니다.

자주 묻는 질문

Ability API란 무엇인가요?

Ability API는 외부 서비스가 에이전트리아에서 만든 어빌리티(Ability)를 REST API로 실행할 수 있게 해주는 기능입니다. 비동기 실행, SSE 스트리밍, 상태·결과 조회, 요청 취소를 지원하며, 모든 요청은 X-API-KEY 헤더로 인증합니다.

Ability API는 언제 사용해야 하나요?

외부 백엔드 서버나 다른 서비스에서 에이전트리아 UI를 거치지 않고 어빌리티 실행 결과를 받아야 할 때 사용합니다. 예를 들어 자사 서비스의 이벤트가 발생했을 때 어빌리티를 트리거하거나, 실행 결과를 자사 시스템에 자동으로 반영하려는 경우에 적합합니다.

어빌리티 실행 결과는 어떻게 받을 수 있나요?

세 가지 방법이 있습니다. GET /{api_endpoint}/{request_id}/status(또는 /result)로 상태를 폴링하거나, 실행 요청 시 callback_url을 지정해 완료 시점에 결과를 콜백으로 받거나, /sse 엔드포인트로 실행 중 각 노드의 결과를 실시간 스트리밍으로 받을 수 있습니다.

실시간 스트리밍(SSE) 도중 연결이 끊기면 어떻게 되나요?

서버는 스트림 연결과 무관하게 어빌리티 실행을 계속 완료하고 결과를 기록합니다. 연결이 끊겨 최종 이벤트를 받지 못했다면, 같은 요청을 재전송하지 않고 request_id(또는 external_request_id)로 상태·결과 조회 API를 폴링해 결과를 가져와야 합니다. 같은 요청을 재전송하면 어빌리티가 다시 실행되므로 주의합니다.

Ability API를 사용하려면 무엇이 먼저 필요한가요?

어빌리티가 API로 배포되어 있어야 하며, 배포 시 발급되는 엔드포인트 코드(api_endpoint)와 API 키가 필요합니다. 아직 배포하지 않았다면 API 배포 가이드에서 먼저 배포 절차를 진행해야 합니다.