REST API 레퍼런스

대화형 문서

모든 Agent-Lab 애플리케이션은 OpenAPI 3 문서를 자동으로 제공합니다. 레퍼런스 구현은 http://localhost:18000/docs에서(또는 직접 만든 앱이 실행되는 위치에서) 확인할 수 있습니다. 아래 카탈로그는 프레임워크에 내장된 라우터를 설명하며, extra_routers도 동일한 스키마에 표시됩니다.

인증

auth.enabled가 true이면(구성 레퍼런스 참고) 라우트에 Keycloak Bearer 토큰이 필요합니다. /auth 라우터는 인증이 활성화된 경우에만 마운트됩니다.

TOKEN=$(curl -s -X POST https://<host>/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "…", "password": "…"}' | jq -r '.access_token')

curl -s https://<host>/agents/list -H "Authorization: Bearer $TOKEN" | jq

메서드	엔드포인트	설명
POST	`/auth/login`	새 Bearer 토큰 발급
POST	`/auth/renew`	기존 Bearer 토큰 갱신
POST	`/auth/exchange`	Microsoft Entra ID 인가 코드(PKCE)를 앱 토큰으로 교환
GET	`/auth/profile`	인증된 사용자의 프로필 조회
PUT	`/auth/profile`	인증된 사용자의 프로필 수정

렐름/클라이언트 설정은 Keycloak 인증에서 다룹니다.

인증이 필요 없는 경로: /status/*, /docs, /openapi.json, /mcp, /static, OAuth well-known 엔드포인트, SPA 마운트 경로. 그 외의 모든 경로에는 유효한 토큰이 필요합니다.

엔드포인트

에이전트

등록된 모든 에이전트 유형의 인스턴스를 생성할 수 있습니다. agent_type은 레지스트리를 기준으로 동적으로 검증됩니다.

메서드	엔드포인트	설명
GET	`/agents/list`	모든 에이전트 인스턴스 목록 조회
GET	`/agents/types`	등록된 에이전트 유형 목록 조회(레지스트리)
GET	`/agents/{agent_id}`	ID로 에이전트 인스턴스 조회
POST	`/agents/create`	새 에이전트 인스턴스 생성
POST	`/agents/update`	에이전트 기본 정보 수정
POST	`/agents/update_setting`	에이전트 설정 하나 수정
POST	`/agents/{agent_id}/reset_settings`	에이전트 설정을 기본값으로 초기화
DELETE	`/agents/delete/{agent_id}`	에이전트 인스턴스 삭제
WS	`/agents/ws/task_updates/{agent_id}`	장시간 작업의 진행 상황 업데이트를 전달하는 WebSocket 스트림

메시지

메서드	엔드포인트	설명
POST	`/messages/post`	에이전트에게 메시지를 보내고 응답 받기
POST	`/messages/list`	에이전트의 메시지 목록 조회
GET	`/messages/{message_id}`	메시지 상세 정보 조회(응답, 첨부 파일 포함)
DELETE	`/messages/delete/{message_id}`	메시지 삭제

언어 모델

메서드	엔드포인트	설명
GET	`/llms/list`	구성된 언어 모델 목록 조회
GET	`/llms/{language_model_id}`	언어 모델과 해당 설정 조회
POST	`/llms/create`	새 언어 모델 생성
POST	`/llms/update`	언어 모델 구성 수정
POST	`/llms/update_setting`	언어 모델 설정 하나 수정
DELETE	`/llms/delete/{language_model_id}`	언어 모델 삭제

통합

메서드	엔드포인트	설명
GET	`/integrations/list`	외부 통합(AI 공급자) 목록 조회
GET	`/integrations/{integration_id}`	통합 상세 정보 조회
POST	`/integrations/create`	통합 생성(자격 증명은 Vault에 저장)
DELETE	`/integrations/delete/{integration_id}`	통합 삭제

첨부 파일

메서드	엔드포인트	설명
GET	`/attachments/list`	첨부 파일 목록 조회
GET	`/attachments/download/{attachment_id}`	첨부 파일 다운로드
POST	`/attachments/upload`	파일 첨부 업로드
POST	`/attachments/embeddings`	첨부 파일의 임베딩 생성

상태 및 MCP

메서드	엔드포인트	설명
GET	`/status/liveness`	Liveness 프로브
GET	`/status/readiness`	Readiness 프로브
GET	`/status/metrics`	Prometheus 메트릭
*	`/mcp`	MCP 서버(Streamable HTTP)
GET	`/.well-known/oauth-protected-resource/mcp`	MCP 클라이언트용 OAuth 메타데이터

요청 예제

에이전트 인스턴스 생성 — agent_name에는 [a-zA-Z0-9_-]를 사용할 수 있습니다. agent_type은 등록된 유형이어야 하며, language_model_id는 선택 사항입니다.

curl -s -X POST http://localhost:18000/agents/create \
  -H "Content-Type: application/json" \
  -d '{
        "agent_name": "support-agent-1",
        "agent_type": "coordinator_planner_supervisor",
        "language_model_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
      }' | jq

메시지 보내기 — message_role은 human, assistant, tool 중 하나입니다. attachment_id는 선택 사항입니다.

curl -s -X POST http://localhost:18000/messages/post \
  -H "Content-Type: application/json" \
  -d '{
        "agent_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "message_role": "human",
        "message_content": "Summarize the attached report.",
        "attachment_id": null
      }' | jq

에이전트 설정 수정 — setting_key에는 [a-zA-Z_-]를 사용할 수 있습니다. setting_value에는 최대 16,000자까지 저장할 수 있습니다(프롬프트 템플릿과 JSON 페이로드가 여기에 저장됩니다. 엔티티 도메인 모델 참고).

curl -s -X POST http://localhost:18000/agents/update_setting \
  -H "Content-Type: application/json" \
  -d '{
        "agent_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "setting_key": "system_prompt",
        "setting_value": "You are a concise research assistant…"
      }' | jq

규칙

ID는 UUID입니다. 모든 목록 엔드포인트는 쿼리 문자열이 아닌 JSON 본문을 받습니다.
설정은 에이전트나 모델과 함께 영속화되는 키-값 쌍입니다. 이를 통해 동일한 구현으로 서로 다르게 구성된 여러 인스턴스를 실행할 수 있습니다.
유효한 agent_type 값에 대해서는 레지스트리가 단일 진실 공급원입니다. GET /agents/types를 실행하면 실행 중인 앱이 검색한 유형(scan_packages를 통한 자체 패키지 포함)을 확인할 수 있습니다.