Agent API
Agent 앱에서 GenAI에 배포한 에이전트를 외부 프로그램에서 실행하고 답을 받습니다. 배포본의 지침 · 모델 · 도구 · 스킬 설정 그대로 실행합니다.
개요
| 항목 | 값 | 설명 |
|---|---|---|
| 기본 주소 | URL | https://swdev.co.kr/api/agent/v1 |
| 인증 | 헤더 | 범위에 Agent가 있는 API 키 (Authorization: Bearer swd_…) |
| 에이전트 id | UUID | Agent > 에이전트 편집의 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자까지) |
conversationId | UUID (선택) | 앞 실행의 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는 프로그램이 나눠 볼 값입니다.
| code | HTTP | 언제 |
|---|---|---|
INVALID_INPUT | 400 | 빈 input, 너무 긴 metadata, 다른 에이전트의 대화 |
UNAUTHORIZED · INVALID_API_KEY | 401 | 키 없음 · 틀림 · 만료 · 폐기 |
SCOPE_NOT_ALLOWED | 403 | 키의 범위에 Agent가 없음 |
AGENT_NOT_FOUND · CONVERSATION_NOT_FOUND · RUN_NOT_FOUND | 404 | 없거나 배포되지 않은 에이전트, 이 키의 것이 아닌 대화 · 실행 |
AGENT_UNAVAILABLE · RUN_IN_PROGRESS | 409 | 배포 중지 · 모델을 쓸 수 없음, 같은 대화에서 실행 중 |
USAGE_LIMIT · RUN_LIMIT | 429 | 사용 한도 초과, 동시 실행 수 초과 |
ACCESS_UNAVAILABLE | 503 | 키 확인 불가 (잠시 후 다시) |