Agent API

Agent 앱에서 GenAI에 배포한 에이전트를 외부 프로그램에서 실행하고 답을 받습니다. 배포본의 지침 · 모델 · 도구 · 스킬 설정 그대로 실행합니다.

개요

항목값설명
기본 주소URLhttps://swdev.co.kr/api/agent/v1
인증헤더범위에 Agent가 있는 API 키 (Authorization: Bearer swd_…)
에이전트 idUUIDAgent > 에이전트 편집의 API 탭, 또는 GET /agents
  • GenAI에 배포한 에이전트만 부를 수 있습니다. 배포를 중지하면 409 AGENT_UNAVAILABLE입니다.
  • 승인이 필요한 도구는 실행하지 않습니다(물어볼 사람이 없습니다). 기억은 쓰지 않습니다.
  • API 키가 곧 사용자입니다. 키가 만든 대화 · 실행은 그 키로만 보이고, GenAI 화면에는 나오지 않습니다. 30일 동안 쓰지 않은 대화는 지워집니다.
  • 사용 한도는 Planet의 구성원 한 명처럼 걸립니다(Agent > Usage). 실행 기록에는 API · 키 이름으로 남습니다.

경로

경로 (/api/agent/v1 아래)설명
GET /agents배포된 에이전트 목록
POST /agents/{id}/runs실행 (wait 초 안에 끝나면 답까지)
GET /runs/{runId}실행 상태 · 답 · 사용량
POST /runs/{runId}/cancel실행 중단

에이전트 목록

curl
curl https://swdev.co.kr/api/agent/v1/agents \
  -H "Authorization: Bearer $SWDEV_API_KEY"
응답
{
  "items": [
    { "id": "73b953f4-7a07-44cf-a1e8-205737e3dd9b", "name": "주간 보고서 작성 도우미", "description": "…" }
  ]
}

실행

필드형식설명
input문자열 (필수)에이전트에게 보낼 글 (100,000자까지)
conversationIdUUID (선택)앞 실행의 conversationId. 같은 대화를 이어 갑니다.
metadata객체 (선택)호출하는 쪽의 값(4,000자까지). 실행 결과에 그대로 돌려줍니다.
wait정수 0~60 (선택)이 초만큼 끝나기를 기다립니다. 끝나면 200과 답, 아니면 202를 돌려줍니다.
curl
curl https://swdev.co.kr/api/agent/v1/agents/$AGENT_ID/runs \
  -H "Authorization: Bearer $SWDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": "이번 주 회의록을 세 줄로 요약해 주세요", "metadata": {"ticket": 42}, "wait": 30}'
Python (requests)
import os, time, requests

BASE = "https://swdev.co.kr/api/agent/v1"
H = {"Authorization": f"Bearer {os.environ['SWDEV_API_KEY']}"}

run = requests.post(f"{BASE}/agents/{agent_id}/runs", headers=H, json={"input": "안녕하세요", "wait": 30}).json()
while run["status"] in ("queued", "running", "waiting_approval"):
    time.sleep(2)
    run = requests.get(f"{BASE}/runs/{run['id']}", headers=H).json()
print(run["output"])

코드 실행 · 문서 생성처럼 오래 걸리는 작업은 60초를 넘길 수 있습니다. 202를 받으면 GET /runs/{runId}로 몇 초 간격으로 확인하십시오.

실행 결과

실행 · 실행 조회 · 중단 뒤 조회는 모두 같은 모양으로 돌려줍니다.

응답
{
  "id": "5d0c…",
  "agentId": "73b953f4-…",
  "conversationId": "a1f2…",
  "status": "completed",
  "output": "이번 주 회의에서는 …",
  "error": null,
  "usage": { "promptTokens": 1830, "completionTokens": 212, "costUsd": 0.0041 },
  "source": "api",
  "metadata": { "ticket": 42 },
  "startedAt": "2026-10-30T06:41:49.120Z",
  "finishedAt": "2026-10-30T06:41:57.884Z"
}
status끝남설명
queued · running아니요대기 · 실행 중
waiting_approval아니요승인 대기. API 실행은 승인이 필요한 도구를 실행하지 않아 나오지 않습니다.
completed예끝남. output에 마지막 답이 있습니다.
failed예실패. error에 { code, message }가 있습니다.
cancelled · interrupted예중단 · 서버 재시작 등으로 끊김

output은 끝난 뒤에만 채워집니다. 에이전트가 만든 파일은 아직 API로 받을 수 없습니다.

대화 이어 가기

앞 실행의 conversationId를 넘기면 앞의 대화를 함께 보고 답합니다. 다른 키가 만든 대화는 이어 갈 수 없습니다(404). 한 대화에서는 한 번에 하나만 실행합니다(409 RUN_IN_PROGRESS).

요청
{
  "input": "그중 결정 사항만 다시 정리해 주세요",
  "conversationId": "a1f2…",
  "wait": 30
}

중단

curl
curl -X POST https://swdev.co.kr/api/agent/v1/runs/$RUN_ID/cancel \
  -H "Authorization: Bearer $SWDEV_API_KEY"

{"cancelled": true}면 중단을 요청한 것이고, 이미 끝난 실행이면 {"cancelled": false}입니다. 실제로 멈췄는지는 실행 조회의 status로 확인합니다.

오류

SW_DEV 공통 형식 {"type", "title", "status", "detail", "code", "instance"}으로 돌려줍니다. detail은 사람이 읽는 설명, code는 프로그램이 나눠 볼 값입니다.

codeHTTP언제
INVALID_INPUT400빈 input, 너무 긴 metadata, 다른 에이전트의 대화
UNAUTHORIZED · INVALID_API_KEY401키 없음 · 틀림 · 만료 · 폐기
SCOPE_NOT_ALLOWED403키의 범위에 Agent가 없음
AGENT_NOT_FOUND · CONVERSATION_NOT_FOUND · RUN_NOT_FOUND404없거나 배포되지 않은 에이전트, 이 키의 것이 아닌 대화 · 실행
AGENT_UNAVAILABLE · RUN_IN_PROGRESS409배포 중지 · 모델을 쓸 수 없음, 같은 대화에서 실행 중
USAGE_LIMIT · RUN_LIMIT429사용 한도 초과, 동시 실행 수 초과
ACCESS_UNAVAILABLE503키 확인 불가 (잠시 후 다시)