CLOVA Studio GOV 에이전트는 특정 작업에 특화된 AI 어시스턴트입니다. 에이전트는 지식베이스 검색, 문서 처리, 질의응답 등 다양한 워크플로우를 자동화할 수 있습니다.
에이전트 작업 흐름 에이전트를 사용하는 전체 워크플로우는 다음과 같이 구성됩니다:
1. 에이전트 생성 (웹)
관리자 메뉴의 에이전트 관리 에서 에이전트를 생성하고 구성합니다.
워크플로우 패턴 선택
지식 컬렉션 연결
프롬프트 및 출력 설정
2. 배포 (웹)
생성한 에이전트를 검토하고 배포 요청을 제출합니다.
관리자 승인 후 배포됩니다.
3. 에이전트 사용
배포된 에이전트는 두 가지 방법으로 사용할 수 있습니다: 웹 인터페이스:
“대화하기” 메뉴에서 에이전트 선택
웹 UI를 통해 대화형으로 사용
API:
이 문서에서 설명하는 API를 통해 프로그래밍 방식으로 호출
애플리케이션에 통합하여 자동화된 워크플로우 구현
중요: 에이전트 생성 및 설정 은 웹 인터페이스에서만 가능합니다. API는 이미 생성된 에이전트를 실행 하는 용도로만 사용됩니다.에이전트 생성 방법은 에이전트 생성하기 가이드를 참조하세요. API를 통한 에이전트 실행은 배포된(deployed) 에이전트만 가능합니다. 초안(draft) 또는 검토 대기(pending review) 상태의 에이전트는 API로 실행할 수 없으며, 호출 시 403 Agent workflow is not deployed 오류가 발생합니다.
배포 전 에이전트 테스트는 웹 “대화하기” 메뉴를 이용해 주세요. (개발자/관리자 권한 필요)
Agent ID 이해하기 Agent ID(= agent_slug)는 API를 통해 에이전트를 호출할 때 필수적으로 필요한 고유 식별자입니다.
문자열(string) 형태이며, 에이전트를 생성하면 자동으로 할당됩니다.
Agent ID 확인 방법
에이전트 관리 메뉴 접속
관리자 메뉴에서 에이전트 관리 를 클릭합니다.
Agent ID 확인
에이전트 목록에서 에이전트 ID 열을 확인합니다.
각 에이전트마다 고유한 ID(slug)가 할당됩니다
ID 우측의 복사 아이콘을 클릭하여 복사할 수 있습니다
API 호출 시 사용
복사한 Agent ID를 API 엔드포인트 URL의 {agent_slug} 자리에 포함하여 호출합니다.
Agent ID는 API 호출 시 필수입니다. ID가 없거나 잘못된 경우 404 오류가 발생합니다.
주요 기능
RAG 검색 지식베이스에서 관련 문서를 검색하여 정확한 답변 제공
워크플로우 자동화 다단계 작업을 자동으로 처리하는 커스텀 워크플로우
스트리밍 응답 실시간으로 응답을 스트리밍하여 빠른 사용자 경험 제공
컨텍스트 유지 대화 맥락을 유지하며 이전 대화 참조 가능
에이전트 실행 (A2A Protocol) 에이전트는 A2A (Agent-to-Agent) 프로토콜을 사용하여 실행됩니다.
엔드포인트 POST /api/v1/external/agents/{agent_slug}/a2a 경로 파라미터 타입 설명 agent_slugstring 에이전트 관리 화면의 에이전트 ID 값
발급받은 API 키를 Authorization 헤더에 Bearer 토큰으로 전달합니다.
Authorization : Bearer YOUR_API_KEY Content-Type : application/json API 키 발급 방법은 API 인증 을 참조하세요.
요청 형식 A2A 프로토콜은 JSON-RPC 2.0 형식을 사용합니다:
{ "jsonrpc" : "2.0" , "id" : "request-1" , "method" : "message/send" , "params" : { "message" : { "kind" : "message" , "messageId" : "msg-123456" , "role" : "user" , "parts" : [ { "kind" : "text" , "text" : "사용자 질문" } ] } } } 파라미터 필드 타입 필수 설명 jsonrpcstring ✅ JSON-RPC 버전 (항상 "2.0") idstring | number ✅ 요청 고유 식별자 methodstring ✅ message/send (일반) 또는 message/stream (스트리밍)params.message.kindstring ✅ 메시지 종류 (항상 "message") params.message.rolestring ✅ 메시지 역할 (항상 "user") params.message.messageIdstring ✅ 메시지 고유 식별자 (UUID 권장) params.message.partsarray ✅ 메시지 내용 배열. 각 원소는 { "kind": "text", "text": "..." } params.metadata.chat_session_idnumber ⭕ 특정 채팅 세션에 연결하고 싶을 때만 사용 (선택)
chat_session_id는 선택사항입니다.
권한 및 접근 제어 역할 API 키 발급 에이전트 API 호출 일반 사용자 (User) ❌ ❌ 개발자 (Developer) ✅ ✅ (배포된 에이전트만) 관리자 (Admin) ✅ ✅ (배포된 에이전트만)
개발자·관리자 권한 여부와 관계없이, 외부 API(/api/v1/external/agents/...)로는 배포된 에이전트만 실행할 수 있습니다.
배포 전 에이전트는 웹 “대화하기” 메뉴에서 테스트해 주세요.
역할별 권한과 배포 상태에 대한 자세한 내용은 권한 관리 를 참조하세요. cURL 예제 curl -X POST "https://api.clovastudio.go.kr/api/v1/external/agents/YOUR_AGENT_SLUG/a2a" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" \ -d '{ "jsonrpc": "2.0", "id": "request-1", "method": "message/send", "params": { "message": { "kind": "message", "messageId": "msg-001", "role": "user", "parts": [ { "kind": "text", "text": "안녕하세요!" } ] } } }' Python 예제 import requests import uuid API_KEY = "YOUR_API_KEY" BASE_URL = "https://api.clovastudio.go.kr" AGENT_SLUG = "YOUR_AGENT_SLUG" def send_message ( message : str , message_id : str = None ) -> dict : """Send a message to the agent using A2A protocol.""" url = f " { BASE_URL } /api/v1/external/agents/ { AGENT_SLUG } /a2a" # Generate unique message ID if not provided if message_id is None : message_id = f "msg- { uuid.uuid4().hex[: 8 ] } " payload = { "jsonrpc" : "2.0" , "id" : "request-1" , "method" : "message/send" , "params" : { "message" : { "kind" : "message" , "messageId" : message_id, "role" : "user" , "parts" : [ { "kind" : "text" , "text" : message } ] } } } headers = { "Content-Type" : "application/json" , "Authorization" : f "Bearer { API_KEY } " } response = requests.post(url, json = payload, headers = headers) return response.json() # 사용 예시 result = send_message( "안녕하세요!" ) print (result) JavaScript/TypeScript 예제 const API_KEY = "YOUR_API_KEY" ; const BASE_URL = "https://api.clovastudio.go.kr" ; const AGENT_SLUG = "YOUR_AGENT_SLUG" ; // Generate unique message ID function generateMessageId () { return `msg- ${ crypto . randomUUID (). slice ( 0 , 8 ) } ` ; } async function sendMessage ( message , messageId = null ) { const url = ` ${ BASE_URL } /api/v1/external/agents/ ${ AGENT_SLUG } /a2a` ; const payload = { jsonrpc: "2.0" , id: "request-1" , method: "message/send" , params: { message: { kind: "message" , messageId: messageId || generateMessageId (), role: "user" , parts: [ { kind: "text" , text: message } ] } } }; const response = await fetch ( url , { method: "POST" , headers: { "Content-Type" : "application/json" , "Authorization" : `Bearer ${ API_KEY } ` }, body: JSON . stringify ( payload ) }); return response . json (); } // 사용 예시 const result = await sendMessage ( "안녕하세요!" ); console . log ( result ); 스트리밍 예제 실시간으로 응답을 받으려면 method를 "message/stream"으로 지정하세요.
응답은 Server-Sent Events (SSE) 형식으로 전달됩니다.
import requests import json import uuid API_KEY = "YOUR_API_KEY" BASE_URL = "https://api.clovastudio.go.kr" AGENT_SLUG = "YOUR_AGENT_SLUG" def send_message_stream ( message : str , message_id : str = None ): """Send a message to the agent with streaming response.""" url = f " { BASE_URL } /api/v1/external/agents/ { AGENT_SLUG } /a2a" if message_id is None : message_id = f "msg- { uuid.uuid4().hex[: 8 ] } " payload = { "jsonrpc" : "2.0" , "id" : "request-1" , "method" : "message/stream" , "params" : { "message" : { "kind" : "message" , "messageId" : message_id, "role" : "user" , "parts" : [ { "kind" : "text" , "text" : message } ] } } } headers = { "Content-Type" : "application/json" , "Authorization" : f "Bearer { API_KEY } " } with requests.post(url, json = payload, headers = headers, stream = True ) as response: for line in response.iter_lines(): if not line: continue decoded = line.decode( "utf-8" ) if not decoded.startswith( "data: " ): continue data = json.loads(decoded[ 6 :]) # SSE 이벤트에서 텍스트 조각을 추출 status = data.get( "result" , {}).get( "status" , {}) msg = status.get( "message" , {}) for part in msg.get( "parts" , []): if part.get( "kind" ) == "text" : print (part.get( "text" , "" ), end = "" , flush = True ) print () # 사용 예시 send_message_stream( "안녕하세요!" ) 스트리밍 응답 구조 각 SSE 이벤트는 다음과 같은 JSON-RPC 형식을 갖습니다.
텍스트 조각은 result.status.message.parts[].text 경로에 위치합니다.
{ "jsonrpc" : "2.0" , "id" : "request-1" , "result" : { "kind" : "status-update" , "taskId" : "..." , "contextId" : "..." , "final" : false , "status" : { "state" : "working" , "timestamp" : "2025-01-01T00:00:00Z" , "message" : { "kind" : "message" , "messageId" : "..." , "role" : "agent" , "parts" : [ { "kind" : "text" , "text" : "응답 조각" } ] } } } } 에러 처리 A2A 프로토콜은 JSON-RPC 에러 형식을 사용합니다:
{ "jsonrpc" : "2.0" , "id" : "request-1" , "error" : { "code" : -32600 , "message" : "Invalid Request" , "data" : { "detail" : "invalid JSON-RPC format" } } } 주요 에러 코드 상태 코드 설명 해결 방법 400 잘못된 요청 형식 JSON-RPC 형식과 필수 필드 확인 (jsonrpc, method, params.message) 401 인증 실패 Authorization: Bearer YOUR_API_KEY 헤더와 API 키 유효성 확인403 배포되지 않은 에이전트 에이전트를 배포(deploy)한 후 다시 호출 404 에이전트를 찾을 수 없음 agent_slug 값이 정확한지 확인500 서버 에러 에이전트 설정 및 지식베이스 확인 후 재시도
다음 단계 에이전트를 효과적으로 활용하려면 적절한 지식베이스 구성과 프롬프트 최적화가 중요합니다.
