Agent Runtime API 소개
UpServe Agent Runtime API는 외부 시스템이 발행된 AI 직원(Deployment)과 게시된 워크플로를 호출하는 서버 간 REST API입니다. 사내 시스템, 배치 작업, 백엔드 서비스가 UpServe의 AI 직원에게 일을 시키고 결과를 받아 갈 때 씁니다.
OpenAI 호환 API가 아닙니다. OpenAI의 chat completions 같은 경로가 없고, 요청·응답 형식도 다릅니다. OpenAI SDK의 base URL만 바꿔서는 동작하지 않습니다.
Private Beta 안내
- 이 API는 Private Beta입니다. 허용된 Project만 호출할 수 있고, 그 밖의 Project에서는 모든 경로가
404 NOT_FOUND로 응답합니다. - Beta 동안 계약(경로, 필드, 한도)이 바뀔 수 있습니다. 변경은 변경 이력에 기록합니다.
- 브라우저나 모바일 앱에서 직접 호출하는 용도가 아닙니다. API 키는 서버에만 보관하세요.
기본 정보
| 항목 | 값 |
|---|---|
| 기본 URL | https://api.upserve.app/v1 |
| 인증 | Authorization: Bearer up_... (API 키) |
| 형식 | JSON (파일 업로드만 multipart) |
| 계약 원천 | openapi.json |
OpenAPI 파일은 공개 /v1 경로의 요청·응답 schema 원천입니다. 이 문서의 설명과 파일이 다르면 파일이 우선입니다.
핵심 개념
| 개념 | 설명 |
|---|---|
| Project | 조직이 소유한 호출 단위입니다. API 키, Deployment, 웹훅, 예산 한도가 Project에 속합니다. |
| API key | Project에 속한 호출 자격입니다. 허용 scope와 호출 가능한 Deployment, 워크플로 목록을 가집니다. |
| Deployment | 조직의 AI 직원을 특정 시점에 고정해 발행한 호출 대상입니다. 원본 직원을 고쳐도 발행본은 바뀌지 않습니다. |
| Session | 한 Deployment와의 대화 단위입니다. 같은 Session에서는 이전 대화가 이어집니다. |
| Turn | Session에 보낸 한 번의 입력과 그 실행입니다. 한 Session에는 동시에 하나의 Turn만 실행됩니다. |
| Workflow | 조직이 게시한 일의 순서와 조건입니다. 게시 버전과 입력 schema가 고정됩니다. |
| Run | 게시된 워크플로를 한 번 실행한 것입니다. 여러 단계를 거쳐 결과를 만듭니다. |
| Artifact | 실행이 만든 파일 결과물입니다. 짧게 유효한 주소로 내려받습니다. |
| Event | Turn과 Run의 진행을 알리는 기록입니다. 폴링, SSE, 웹훅이 같은 기록을 씁니다. |
어디서부터 읽을까
- 빠른 시작에서 15분 안에 첫 Turn을 받아 보세요.
- 키를 다루는 방법은 인증에서 확인하세요.
- 대화형 호출은 Session과 Turn, 워크플로 호출은 Workflow와 Run을 읽으세요.
- 운영에 들어가기 전에 이벤트, 웹훅, 오류, 한도와 데이터를 확인하세요.
- 업무를 설명해 조직 팀을 새로 만들려면 조직 업무 만들기를 읽으세요.
AI 도구에 연동을 맡길 때
AI 코딩 도구가 이 API를 읽고 호출 코드를 쓰게 하려면 llms.txt를 먼저 읽히세요. 기본 정보, 실행과 조회와 결과와 취소의 순서, 중복 실행과 비용을 막는 규칙, 지금 API로 할 수 없는 일을 한 파일에 짧게 모았습니다. 세부 계약은 이 문서와 openapi.json이 원천입니다.
실패한 실행을 다시 할지는 오류와 재시도의 코드별 다음 행동 표로 정하게 하세요. 비용이 다시 드는 결정과 예산 변경은 사람에게 확인받도록 하는 것이 안전합니다.