> For the complete documentation index, see [llms.txt](https://docs.roboflow.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.roboflow.com/get-started/ko/agents/roboflow-agent.md). # Roboflow 에이전트 ## 소개 Roboflow 에이전트는 귀하의 [워크스페이스에](/get-started/ko/platform/workspaces/key-concepts.md) 액세스할 수 있으며 [워크플로를](https://docs.roboflow.com/workflows). 또한 이를 사용해 [Rapid](https://docs.roboflow.com/models/rapid/rapid) 모델을 설정할 수 있습니다. 워크스페이스 왼쪽 사이드바에서 "Agent"를 클릭하여 에이전트에 접근할 수 있습니다.
### 기능 에이전트는 다음을 할 수 있습니다: * 생성 [워크플로를](https://docs.roboflow.com/workflows) 자연어 설명으로부터 이를 만들고, 실행하며, 실패를 자동으로 수정합니다. 모든 입력 모드가 지원됩니다: 이미지 URL, RTSP 스트림, 로컬 비디오, 웹캠. * 실행 중인 동안 비디오 미리보기를 볼 수 있습니다. 에이전트는 미리보기가 아직 시작 중일 때와 스트림이 끝나거나 실패했을 때를 알려줍니다. 웹캠 및 RTSP 미리보기의 경우 마지막 약 2.5분의 결과를 보관하므로 스트림을 중지하지 않고도 무엇을 보았는지 물어볼 수 있습니다. * 첨부된 이미지와 비디오를 이해합니다. 채팅에 이미지나 짧은 비디오를 첨부, 드래그 앤 드롭, 또는 붙여넣기 할 수 있습니다. 에이전트는 미디어를 분석하여 내용을 파악하고, 이를 바탕으로 워크플로를 생성한 다음, 동일한 미디어에서 워크플로를 다시 실행해 결과를 검증합니다. 비디오는 MP4 또는 MOV여야 하며 100MB 이하여야 합니다. 이미지는 15MB 이하여야 합니다. 첨부된 비디오는 업로드된 다른 비디오와 마찬가지로 워크스페이스에 저장되므로, 나중에 찾아서 삭제할 수 있습니다. * 설정 및 관리 [Rapid](https://docs.roboflow.com/models/rapid/rapid) 모델. * 요청 시 데이터셋을 관리합니다: [프로젝트의 학습, 검증, 테스트 분할을 재조정하거나](https://docs.roboflow.com/datasets/versions/dataset-versions/create-a-dataset-version#readjusting-train-validation-test-splits) 또는 [프로젝트를 병합하여](https://docs.roboflow.com/datasets/manage/merge-datasets) 새 프로젝트로 만들 수 있습니다. 둘 다 [백그라운드 작업](#background-tasks) 패널에서 추적할 수 있는 백그라운드 작업으로 실행됩니다. * [프로젝트 생성하기](https://docs.roboflow.com/datasets/create-and-upload/create-a-project#create-a-project-from-the-agent) "+" 탭에서. "새 자산 만들기" 페이지에서 "새 모델"을 클릭하고 프로젝트 유형을 선택한 뒤 나머지 양식을 작성하세요. 탭은 생성되면 새 프로젝트로 바뀝니다. * 시작하기 [모델 학습](https://docs.roboflow.com/models/train/train-a-model#train-from-the-agent) 프로젝트 탭에서 실행합니다. "Train" 버튼은 탭 안에서 전체 학습 흐름(엔진, 아키텍처, 버전 단계)을 열고, 데이터셋 내보내기를 준비해 줍니다. * 열려 있는 워크플로, Rapid 모델, 사용량 보기, 프로젝트, 플랜을 탭으로 정리합니다. 탭을 드래그해 순서를 바꿀 수 있습니다. "+" 탭을 사용해 닫은 항목을 다시 열거나 새 항목을 만들 수 있습니다. 후속 대화는 이전 채팅의 산출물을 이어받습니다. * "+" 탭에서 모델 중 하나를 엽니다. "최근" 아래에서 하나를 선택하거나 검색하여 워크스페이스의 모든 모델을 볼 수 있습니다. 모델은 대화와 함께 유지되므로 새로 고친 후에도 다시 열립니다. * "데이터셋" 섹션이 있는 프로젝트 탭을 엽니다. [라벨링 단계별로 프로젝트의 이미지를 그룹화하는](https://docs.roboflow.com/datasets/annotate/annotate/team-collaboration#browse-labeling-work-from-the-agent) (미할당, 주석 추가 중, 검토, 데이터셋). 주석 편집기에서 이미지를 열고, 작업을 다음 단계로 이동한 뒤, 검토 중인 이미지를 승인하거나 거부합니다. * 존 편집기를 열어 워크플로의 입력 이미지에 탐지 구역을 그립니다. * UI 이벤트에 반응합니다: Rapid 학습 실패를 진단하고, 워크플로 실행 오류를 조사하며(채팅 입력 위의 "Investigate" 프롬프트 사용), Rapid 소스 워크플로가 준비되면 자동으로 계속 진행합니다. * 워크스페이스의 [크레딧 사용 대시보드](/get-started/ko/platform/billing-and-plans/credits/view-credit-usage.md) 질문과 일치하는 필터(기간, 기능, 귀속, 누적/일별, 크레딧/달러)로 표시되는 "Historical Usage" 탭을 엽니다. 에이전트는 대화가 계속되는 동안 탭을 동기화 상태로 유지합니다. "결제 보기" 권한이 필요합니다. * 설정하기 [비전 이벤트](https://docs.roboflow.com/deployment/monitoring-and-analytics/vision-events) 를 워크플로에 추가합니다. 모델을 실행하는 워크플로를 만들 때 에이전트는 비전 이벤트 블록을 추가하고 적절한 [사용 사례](https://docs.roboflow.com/deployment/monitoring-and-analytics/vision-events/use-cases)를 설정하며, 필요하면 하나를 새로 만듭니다. * "설정" 섹션이 있는 프로젝트 탭을 열어 [액티브 러닝을](https://docs.roboflow.com/deployment/monitoring-and-analytics/active-learning) 해당 프로젝트에 대해 켜거나 끄고, 수집 한도와 조건을 편집할 수 있습니다. * 귀하의 [비전 이벤트](https://docs.roboflow.com/deployment/monitoring-and-analytics/vision-events) 데이터에 대해 질문에 답합니다(예: "지난주에 실패가 몇 건이었나요?", "어떤 카메라가 가장 많은 결함을 생성하나요?"). 에이전트는 이벤트를 계산하고, 시간 경과에 따른 성공/실패 비율을 추적하며, 숫자 필드의 합, 평균, 최소, 최대, 고유값 개수를 구할 수 있습니다. 총합은 [사용 사례](https://docs.roboflow.com/deployment/monitoring-and-analytics/vision-events/use-cases) 의 모든 필드별로, 커스텀 메타데이터를 포함해 그룹화하거나 하루 또는 주 단위로 묶을 수 있습니다(묶음은 UTC 사용). 질문이 워크스페이스의 [보존 기간을](https://docs.roboflow.com/deployment/monitoring-and-analytics/vision-events#data-retention)넘으면, 에이전트는 0으로 답하는 대신 조회할 수 있는 가장 이른 날짜를 알려줍니다. "비전 이벤트 보기" 권한이 필요합니다. 참조: [이벤트 조회](https://docs.roboflow.com/deployment/monitoring-and-analytics/vision-events/query-events). * 비전 이벤트 초안 작성, 미리보기, 예약 [요약 보고서](https://docs.roboflow.com/deployment/monitoring-and-analytics/vision-events/summary-reports) 원하는 요약의 간단한 설명만으로 생성합니다(예: "라인별 성공 및 실패 수의 주간 금요일 아침 요약"). 에이전트는 실제로 이벤트가 보내는 필드를 바탕으로 보고서를 만들고, 실제 데이터로 미리보기를 보여주며, 바로 보내거나 선택한 일정에 맞춰 이메일로 보낼 수 있습니다. * 귀하의 엣지 디바이스에 대해 [배포 관리자](https://docs.roboflow.com/deployment/self-hosted/enterprise/deployment-manager) 플릿, 구성, 텔레메트리, 로그, 이벤트, 스트림에 읽기 전용으로 접근하여 질문에 답합니다. 디바이스 상태나 스트림 오류를 물어보세요(예: "어떤 디바이스가 오프라인인가요?", "이 스트림은 왜 오류가 났나요?") 배포 관리자를 직접 클릭해 들어갈 필요가 없습니다. 디바이스 자격 증명은 에이전트와 절대 공유되지 않습니다. ### 백그라운드 작업 에이전트가 시작한 긴 작업은 채팅 중에도 계속 실행됩니다: 모델 학습, 자동 라벨링, 데이터셋 버전 생성, 프로젝트 병합, 클래스 재매핑, 분할 재조정. 채팅 상단의 배지가 실행 중인 작업 수를 표시합니다. 이를 클릭하거나 왼쪽 메뉴의 "Background Tasks"를 클릭하면 "Running"과 "Finished" 아래에 목록이 있는 패널을 열 수 있습니다. 작업을 클릭하면 생성된 페이지가 열립니다. 에이전트는 탭을 닫았다가 나중에 다시 와도 작업이 완료되면 채팅에서 알려줍니다. 대화 내부에서 시작된 작업만 여기에 표시됩니다. 앱의 다른 곳이나 API를 통해 시작한 학습은 여기에 나타나지 않으며, 대신 Activity Center에서 추적합니다. ## HTTP API 에이전트 API를 사용하면 `api.roboflow.com`을 통해 Roboflow AI 에이전트와 상호작용할 수 있습니다. 자연어 지침을 보내 워크플로를 생성하거나 수정한 다음, 준비되면 게시할 수 있습니다. 모든 편집 내용은 명시적으로 게시하기 전까지 초안으로 저장됩니다. [워크플로를](https://docs.roboflow.com/workflows/build/create-a-workflow)를 생성하거나 수정할 수 있으며 인증은 [API 키](https://docs.roboflow.com/reference/platform/rest-api/authenticate-with-the-rest-api)를 통해 이루어집니다. 만약 [범위 제한이 있는 API 키](https://docs.roboflow.com/reference/authentication/authentication/scoped-api-keys) 를 폴더 제한과 함께 사용하면, 에이전트는 해당 폴더 범위 내의 워크플로에만 접근할 수 있습니다. ### 채팅 `POST` `/:workspace/agent/chat` AI 에이전트에게 메시지를 보냅니다. 에이전트는 새 워크플로를 만들고, 기존 워크플로를 편집하며, 워크스페이스에 대해 질문에 답할 수 있습니다. 워크플로 변경 사항은 초안으로 저장됩니다. 다음을 전달하여 새 대화를 시작하거나 기존 대화를 계속할 수 있습니다 `conversation_id`. **헤더** | 이름 | 값 | | ------------ | ------------------ | | Content-Type | `application/json` | **본문**
이름유형설명필수
api_keystring워크스페이스 API 키.true
messagestring에이전트에 대한 지시 또는 질문.true
conversation_idstring계속할 기존 대화의 ID. 새 대화를 시작하려면 생략하세요.false
modestringagent (기본값) 또는 plan. plan 모드에서는 에이전트가 변경 없이 무엇을 할지 개요를 제시합니다.false
**예시 요청** ```bash curl -X POST "https://api.roboflow.com/my-workspace/agent/chat" \ -H "Content-Type: application/json" \ -d '{ "api_key": "'"$ROBOFLOW_API_KEY"'", "message": "자동차를 감지하고 개수를 세는 워크플로를 만들어 줘" }' ``` **응답** ```json { "text": "제가 'Car Counter'라는 워크플로를 만들었습니다 ...", "workflows": [ { "id": "wf_abc123", "name": "Car Counter", "url": "car-counter", "specification": { ... } } ], "conversation_id": "conv_xyz789" } ``` | 필드 | 설명 | | ----------------- | -------------------------------------------------------------- | | `text` | 에이전트의 응답 텍스트. | | `workflows` | 이번 턴 동안 생성되거나 수정된 워크플로. 각각에는 `id`, `name`, `url`, 그리고 초안 `사양`. | | `conversation_id` | 대화 ID입니다. 대화를 계속하려면 이후 요청에 이 값을 다시 전달하세요. | 필수 범위: `workflow:create` 및 `workflow:update`. ### 워크플로 게시 `POST` `/:workspace/agent/workflows/:workflowUrl/publish` 에이전트가 생성하거나 편집한 워크플로의 최신 초안 버전을 배포합니다. 게시되지 않은 초안이 없으면 엔드포인트는 `400`. **예시 요청** ```bash curl -X POST "https://api.roboflow.com/my-workspace/agent/workflows/car-counter/publish?api_key=$ROBOFLOW_API_KEY" ``` **응답** ```json { "workflowId": "wf_abc123", "workflowUrl": "car-counter", "versionId": "v-1700000000", "status": "published" } ``` 필수 범위: `workflow:update`. ### 대화 목록 `GET` `/:workspace/agent/conversations` 워크스페이스의 모든 에이전트 대화를 반환합니다. **쿼리**
이름유형설명필수
api_keystring워크스페이스 API 키.true
sourcestring출처로 필터링: api 또는 web.false
workflowstring워크플로 URL 슬러그로 필터링합니다. 이 워크플로를 참조하는 대화만 반환합니다.false
**예시 요청** ```bash curl "https://api.roboflow.com/my-workspace/agent/conversations?api_key=$ROBOFLOW_API_KEY&source=api" ``` **응답** ```json { "conversations": [ { "id": "conv_xyz789", "name": "Car Counter", "source": "api", "workflowIds": ["wf_abc123"], "created_on": "2026-05-14T20:00:00.000Z", "updated_on": "2026-05-14T20:05:00.000Z" } ] } ``` 필수 범위: `workflow:read`. ### 대화 가져오기 `GET` `/:workspace/agent/conversations/:id` 모든 메시지를 포함한 전체 대화를 반환합니다. **예시 요청** ```bash curl "https://api.roboflow.com/my-workspace/agent/conversations/conv_xyz789?api_key=$ROBOFLOW_API_KEY" ``` **응답** ```json { "id": "conv_xyz789", "name": "Car Counter", "type": "agent", "source": "api", "created_on": "2026-05-14T20:00:00.000Z", "updated_on": "2026-05-14T20:05:00.000Z", "workflowIds": ["wf_abc123"], "messages": [ { "id": "msg_1", "role": "user", "parts": [{ "type": "text", "text": "자동차를 감지하는 워크플로를 만들어 줘" }] }, { "id": "msg_2", "role": "assistant", "parts": [{ "type": "text", "text": "제가 ...라는 워크플로를 만들었습니다" }] } ] } ``` 필수 범위: `workflow:read`. ### 오류 응답 모든 엔드포인트는 다음 형식으로 오류를 반환합니다 `{ "error": "..." }` 적절한 HTTP 상태 코드와 함께. | 상태 | 의미 | | ----- | --------------------------------------------------------------- | | `400` | 잘못된 요청(누락 `message`, 게시할 초안 없음 등) | | `401` | API 키가 없거나 유효하지 않습니다. | | `402` | 크레딧이 부족합니다. | | `403` | 범위가 부족하거나, 워크플로가 폴더 범위를 벗어났거나, 이 워크스페이스에서 에이전트 기능이 비활성화되어 있습니다. | | `404` | 워크플로 또는 대화를 찾을 수 없습니다. | | `500` | 내부 서버 오류. | 워크스페이스 수준에서 에이전트 기능이 비활성화되면 채팅 및 게시 엔드포인트는 `403` 와 함께 반환합니다 `"error_type": "AGENT_DISABLED"`. ## MCP 서버 AI 에이전트를 [MCP 서버](/get-started/ko/agents/mcp-server.md) 에 연결하면 다음 도구를 사용해 Roboflow 에이전트에 작업을 넘길 수 있습니다:
도구설명
agent_chatRoboflow AI 에이전트와 채팅합니다.
agent_chat_result아직 진행 중이던 실행의 결과를 수집합니다.
agent_conversations_list워크스페이스의 에이전트 대화를 나열합니다.
agent_conversation_get메시지 기록이 포함된 대화 하나를 가져옵니다.
agent_workflow_publish에이전트가 편집한 워크플로의 최신 초안을 게시합니다.