> 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 Agent

워크플로와 Rapid 모델을 만들고, 실행하고, 디버깅하며, HTTP 채팅 API도 제공합니다.

## 정보

Roboflow Agent는 다음 항목에 액세스할 수 있으며: [워크스페이스](https://docs.roboflow.com/get-started/ko/platform/workspaces/key-concepts.md) 을 만들고, 편집하고, 실행하고, 디버그할 수 있습니다. [워크플로](https://docs.roboflow.com/workflows)을 설정하는 데에도 사용할 수 있습니다. [Rapid](https://docs.roboflow.com/models/rapid/rapid) 모델. 워크스페이스 왼쪽 사이드바에서 "Agent"를 클릭해 Agent에 액세스하세요.

<figure><img src="https://83860450-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1YMZNIiZMBdlCHUDeZMP%2Fuploads%2Fgit-blob-e08163ee75bce9853bb94d3581efc5910405e091%2Frf-agent.png?alt=media" alt=""><figcaption></figcaption></figure>

### 기능

Agent는 다음 작업을 수행할 수 있습니다.

* [워크플로](https://docs.roboflow.com/workflows): 일반적인 설명만으로 워크플로를 만들고, 이미지, RTSP 스트림, 동영상, 브라우저 웹캠 또는 휴대폰 카메라에서 실행하고, 요청한 동영상 구간만 실행하고, 실시간 미리보기를 확인하고, 오류를 자동으로 수정하고, 실행 오류를 조사하고, 감지 영역을 그릴 수 있습니다. 카메라를 추가하려면 Agent가 물어볼 때 "웹캠", "네트워크 스트림" 또는 "휴대폰"을 선택하세요. 브라우저 세션이 끝나면 웹캠이나 휴대폰 스트림이 중지됩니다.
* 첨부 미디어: 채팅에 추가한 이미지와 MP4 또는 MOV 동영상을 분석하고, 이를 사용해 워크플로를 만들고 검증할 수 있습니다.
* 이미지 생성: 아직 사진이 없다면 텍스트 설명으로 이미지 1\~10개를 만들 수 있습니다. 이미지 생성을 요청하면 Agent가 작업을 시작합니다. 비용을 예상하고 싶다면 먼저 가격을 물어보세요. 각 이미지는 다음에 저장되며: [에셋 라이브러리](https://docs.roboflow.com/get-started/ko/platform/workspaces/asset-library.md), 저장된 이미지에 대해서만 비용을 지불합니다. Agent는 사용자의 이미지를 참조 이미지로 사용할 수 없습니다.
* [Rapid](https://docs.roboflow.com/models/rapid/rapid) 모델: 학습 실패를 설정, 관리 및 진단할 수 있습니다.
* [워크플로 평가](https://docs.roboflow.com/workflows/evaluate/workflow-evals): 평가를 만들고, 채팅에서 정답 데이터를 검토하고 승인하고, 워크플로를 실행 및 비교하고, 결과를 설명할 수 있습니다. 크레딧이 사용되는 실행을 시작하기 전에 Agent가 확인을 요청합니다. 가장 성능이 좋은 워크플로를 게시되지 않은 초안으로 저장할 수 있습니다. 프로젝트를 평가할 때 Agent는 해당 프로젝트의 현재 모델을 사용하는 워크플로를 사용합니다. 프로젝트의 테스트 세트와 레이블을 가져와 사용자가 승인하도록 할 수 있습니다.
* 프로젝트: [프로젝트 만들기](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), [데이터 분할 재조정](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), 프로젝트의 [데이터셋 상태 점검](https://docs.roboflow.com/datasets/versions/dataset-health-check#roboflow-agent) 을 읽거나 새로고침해 데이터 문제를 찾을 수 있습니다.
* Universe 데이터셋: 다음에서 공개 데이터셋을 찾고 [Universe](https://docs.roboflow.com/datasets/universe/universe/what-is-roboflow-universe)에서 비교한 다음, [전체 데이터셋 또는 지정한 수의 이미지를 복사](https://docs.roboflow.com/datasets/universe/universe/fork-a-universe-dataset#roboflow-agent) 해 프로젝트에 추가할 수 있습니다. Agent가 데이터를 복사하기 전에 채팅에서 소스, 이미지 수, 클래스 변경 사항을 확인하고 동의합니다.
* 동작 인식 프로젝트: 동영상을 추가하고, [동영상 구간](https://docs.roboflow.com/datasets/annotate/annotate/annotate-video-segments)을 추가, 편집 또는 가져오고, 동영상에 자동 레이블 지정을 실행하고, 탭의 타임라인에서 구간을 검토할 수 있습니다. 그런 다음 Agent는 동영상 단위로 분할해 데이터셋에 추가하고, 버전을 만들고, 동영상 모델을 학습할 수 있습니다. 모델에 비용 예상치가 없으면 학습을 시작하기 전에 Agent가 확인을 요청합니다.
* 데이터셋: [레이블링 단계별로 이미지 탐색](https://docs.roboflow.com/datasets/annotate/annotate/team-collaboration#browse-labeling-work-from-the-agent), [워크스페이스 이미지를 모델에 추가하고 레이블링 시작](https://docs.roboflow.com/datasets/annotate/annotate/team-collaboration#add-images-and-start-annotating), 일괄 작업을 검토 대상으로 보내거나 수정 대상으로 되돌리고, 검토에서 이미지 승인 또는 거부(작업과 이미지 수를 확인한 후), 이미지를 데이터셋에 추가하고, 작업을 미할당 상태로 되돌릴 수 있습니다.
* [일괄 처리](https://docs.roboflow.com/deployment/roboflow-cloud/batch-processing): 에셋 라이브러리의 이미지에 게시된 워크플로를 실행하고, 채팅에서 사용자와 함께 새 작업을 설정하고, 작업 목록을 확인하고, 특정 작업의 상태를 보고할 수 있습니다.
* [이상 감지](https://docs.roboflow.com/models/supported-tasks/anomaly-detection) 프로젝트: 일괄 작업의 레이블을 "정상" 또는 "이상"으로 지정하고 검토 대상으로 보낼 수 있습니다. 레이블 지정만으로 이미지를 승인하거나 데이터셋에 추가하지는 않습니다. 이미지를 데이터셋에 추가하면 정상 이미지는 모든 분할에 넣을 수 있고, 이상 이미지는 유효성 검사 및 테스트 분할에만 넣을 수 있습니다.
* [능동 학습](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/query-events), 예약하고 [요약 보고서](https://docs.roboflow.com/deployment/monitoring-and-analytics/vision-events/summary-reports).
* 사용량: 질문에 맞는 필터를 적용해 [크레딧 사용량 대시보드](https://docs.roboflow.com/get-started/ko/platform/billing-and-plans/view-credit-usage.md) 를 표시합니다.
* 엣지 디바이스: 읽기 전용으로 [배포 관리자](https://docs.roboflow.com/deployment/self-hosted/enterprise/deployment-manager) 플릿, 텔레메트리, 로그, 스트림에 관한 질문에 답합니다.
* 탭: 열려 있는 워크플로, 모델, 프로젝트, 사용량 뷰를 정리합니다. 드래그해 순서를 바꾸고, 닫은 항목을 다시 열거나 "+" 탭에서 새 항목을 만들 수 있습니다.

### 워크플로 게시

Agent의 수정 사항을 적용하는 시점은 워크플로의 [게시 모드](https://docs.roboflow.com/workflows/build/workflows-ai-assistant#publishing-mode)에 따라 달라집니다. "자동 게시" 모드에서는 저장할 때마다 게시되므로 새 워크플로가 즉시 적용됩니다. "수동 게시" 모드에서는 Agent의 수정 사항이 초안으로 저장되며, 현재 적용된 워크플로는 변경되지 않습니다.

저장된 초안을 적용하려면 채팅 상자 위의 에셋 바에서 워크플로를 찾으세요. 워크플로에 저장된 변경 사항이 있지만 아직 적용되지 않은 경우 "조치 필요" 표시가 나타납니다. "게시"를 클릭해 적용된 워크플로를 업데이트하거나, "사본으로 게시"를 클릭해 초안을 새 워크플로로 게시하고 원본은 그대로 유지하세요. 게시하지 않고 초안을 보관하려면 "닫기"를 클릭하세요. 워크플로를 게시하려면 게시 권한과 해당 워크플로 폴더에 대한 쓰기 권한이 필요합니다.

게시된 워크플로를 코드에서 사용하려면 Agent에게 도움을 요청하세요. Agent가 "빠른 API 호출" 또는 "코딩 에이전트" 중 무엇을 원하는지 묻습니다. "빠른 API 호출"을 선택하면 채팅에 코드 스니펫이 표시됩니다. "코딩 에이전트"를 선택하면 "코딩 에이전트로 배포" 카드가 표시됩니다. 카드를 클릭하면 코딩 에이전트에 복사해 넣을 프롬프트가 열립니다. 워크플로에 아직 적용되지 않은 변경 사항이 있으면 Agent가 먼저 게시하라고 요청합니다.

### 미디어 추가

파일을 채팅의 아무 곳에나 놓아 Agent에게 전달하세요. 파일을 붙여넣거나 채팅 상자의 클립 아이콘을 클릭한 다음 "파일 첨부" 또는 "폴더 첨부"를 선택할 수도 있습니다. 홈 페이지에서는 "+"를 클릭하고 "파일 첨부"를 선택하세요. 폴더를 추가하면 안에 있는 파일이 펼쳐집니다. zip 파일은 끌어다 놓을 때만 압축이 풀리며, 최대 300개 파일까지 처리됩니다. 더 큰 zip 파일은 [데이터 업로드 페이지](https://docs.roboflow.com/datasets/create-and-upload/adding-data#upload-a-zip-file).

웹캠으로 사진, 간격 프레임 또는 MP4 클립을 촬영하려면 클립 아이콘이나 "+"를 클릭하고 "카메라 사용"을 선택하세요. Agent가 미디어를 요청하면 요청에 "카메라 사용" 버튼도 표시됩니다. 클립을 녹화한 뒤 "동영상 유지"를 클릭하세요. 그런 다음 추가 버튼(예: "메시지에 3개 추가", "메시지에 동영상 추가")을 클릭해 캡처한 미디어를 다음 메시지에 첨부하세요.

메시지를 보내면 업로드가 시작되고 백그라운드에서 진행되므로 계속 채팅할 수 있습니다. 채팅의 카드에 진행 상황과 "취소" 버튼이 표시되며, 업로드는 백그라운드 작업 패널에도 나타납니다. 이미지와 동영상은 [에셋 라이브러리](https://docs.roboflow.com/get-started/ko/platform/workspaces/asset-library.md)에 저장되며, 각 이미지에는 촬영 시간이 [메타데이터](https://docs.roboflow.com/datasets/create-and-upload/adding-data/image-metadata#capture-time).

주석 파일이 포함된 업로드나 두 개 이상의 폴더에 이미지가 있는 업로드는 즉시 시작되지 않고 대상이 지정될 때까지 대기합니다. Agent가 파일을 모델이나 워크스페이스로 보내며, 메시지에서 대상을 지정하지 않은 경우 먼저 확인을 요청합니다. 모델에 업로드하는 경우 폴더 이름(예: `train`, `valid`, `test`)이 데이터 분할을 지정합니다. 폴더 이름이나 주석에 분할 정보가 없는 파일은 기본적으로 학습 70%, 검증 20%, 테스트 10%로 나뉩니다.

### 클라우드 스트리밍

Agent에게 카메라 연결을 요청하고, 기존 소스를 선택한 다음 [클라우드 스트리밍](https://docs.roboflow.com/deployment/roboflow-cloud/cloud-streaming)을 사용해 워크플로 초안을 미리 보세요. 카메라가 연결된 네트워크의 커넥터에는 "네트워크 스트림"을, 임시 브라우저 세션에는 "웹캠" 또는 "휴대폰"을 사용하세요.

사용 가능한 카메라 미리보기를 계속 실행하려면 명시적으로 배포를 요청하세요. 승격하면 게시하거나 다시 시작하지 않고 현재 스냅샷, 런타임 상태, 싱크 설정을 보존합니다. 임시 웹캠 또는 휴대폰 세션은 승격할 수 없습니다. 나중에 수정 사항을 적용하려면 배포를 업데이트해 달라고 명시적으로 요청하세요. 게시만으로는 실행 중인 작업이 변경되지 않습니다.

중지할 워크플로 또는 작업의 이름을 지정하세요. 미리보기 연결을 끊거나 채팅을 닫아도 별도의 지속적 배포는 중지되지 않습니다. 전체 절차는 [Agent 빠른 시작 가이드](https://docs.roboflow.com/deployment/roboflow-cloud/cloud-streaming/quickstart#roboflow-agent) 를 따르고, 결제 및 사용 기간 제한은 [가격 및 제한](https://docs.roboflow.com/deployment/roboflow-cloud/cloud-streaming/pricing-and-limits) 을 참고하세요. 앱 내 작업은 독립형 공개 SDK 메서드가 아닙니다.

### 백그라운드 작업

Agent가 시작한 장시간 작업은 채팅 중에도 계속 실행됩니다. 여기에는 모델 학습, Universe 데이터 세트 복사, 자동 레이블 지정, 데이터 세트 버전 생성, 프로젝트 병합, 클래스 재매핑, 데이터 분할 재조정, 배치 처리 작업이 포함됩니다. 채팅 상자 위의 알약 모양 표시기에 실행 중인 작업 수가 표시됩니다. 이를 클릭하거나 왼쪽 메뉴에서 "백그라운드 작업"을 클릭하면 "실행 중" 및 "완료됨" 목록이 있는 패널이 열립니다. 작업을 클릭하면 해당 작업이 만든 페이지가 열립니다.

탭을 닫았다가 나중에 다시 돌아오더라도 작업이 완료되면 Agent가 채팅에서 알려줍니다. 대화 내에서 시작한 작업만 여기에 표시됩니다. 앱의 다른 곳이나 API를 통해 시작한 학습 작업은 여기에 표시되지 않으며, 대신 활동 센터에서 추적할 수 있습니다.

### 워크스페이스 LLM 키

자체 OpenAI 또는 Azure OpenAI 키로 Agent를 실행하면 데이터가 Roboflow의 LLM 키를 거치지 않습니다. 이 설정은 워크플로 편집기 어시스턴트, 사용자 지정 블록 어시스턴트, Agent API에도 적용됩니다.

{% hint style="info" %}
이 기능을 사용하려면 Roboflow가 워크스페이스에서 기능을 활성화해야 합니다. 계정 담당자에게 문의해 요청하세요. EU 지역에서는 사용할 수 없습니다.
{% endhint %}

1. 워크스페이스 설정에서 "타사 키"를 클릭하세요.
2. OpenAI API 키를 추가하거나 Azure OpenAI의 "리소스 이름"과 "Azure OpenAI API 키"를 추가하세요.
3. "워크스페이스 LLM 키"에서 "제공업체"와 "모델"을 선택하세요. Azure OpenAI의 경우 "배포 이름"과 "이 배포에서 사용하는 모델"도 입력하세요.
4. "연결 테스트"를 클릭하세요.
5. "워크스페이스 LLM 키 적용"을 켠 다음 "저장"을 클릭하세요.

이 설정을 켜면 모든 요청에 사용자의 키가 사용됩니다. 키가 작동하지 않으면 요청이 오류와 함께 중단되며 Roboflow의 키로 대체되지 않습니다. 워크플로의 OpenAI 및 Gemini 블록은 워크스페이스 키를 사용하고, 이를 사용할 수 없는 AI 기능(예: 다른 LLM 블록)은 비활성화됩니다. 대화 추적은 기록되지 않으며 LLM 비용은 크레딧으로 청구되지 않습니다.

"Enforce Workspace LLM Keys"가 켜져 있으면 이미지 생성이 비활성화됩니다.

Workflow OpenAI 블록과 Auto Label은 "Third Party Keys"의 "OpenAI API Key"를 사용합니다. Azure OpenAI 리소스에서 실행하려면 여기에 Azure 키를 입력하고 "Azure OpenAI Endpoint"를 입력하세요(예: `https://my-resource.openai.azure.com`). Azure에서 각 배포의 이름을 해당 배포에서 실행하는 모델 이름으로 지정하세요(예: `gpt-6-astra`). OpenAI API 키가 없으면 Agent가 Workflow에 OpenAI 블록을 추가할 수 없습니다.

{% hint style="info" %}
Agent는 선택한 모델에서 실행되므로 Roboflow 키를 사용할 때와 다르게 동작할 수 있습니다. 모델이 지원하는 기능에 따라 일부 작업의 동작이나 결과가 달라질 수 있습니다.
{% endhint %}

## HTTP API

Agent API를 사용하면 `api.roboflow.com`을 통해 Roboflow AI 에이전트와 상호작용할 수 있습니다. 자연어 지시를 보내 [Workflow](https://docs.roboflow.com/workflows/build/create-a-workflow)를 만들거나 수정할 수 있습니다. 에이전트가 만든 Workflow는 바로 활성화됩니다. 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) 를 사용하는 경우 에이전트는 해당 폴더 범위 내의 Workflow와 모델에만 액세스할 수 있으며 폴더 밖에 있는 프로젝트는 볼 수 없습니다. 에이전트에 워크스페이스 모델 목록을 요청하면 호출자가 이미 볼 수 있는 모델만 반환됩니다.

### 채팅

에이전트에게 메시지를 보냅니다. 새 대화를 시작하거나 `conversation_id`.

{% openapi src="/files/0e5638be82bf2745ff3620eb2bd9f5a98dedf9b1" path="/{workspace}/agent/chat" method="post" %}
[agent-api.yaml](https://83860450-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1YMZNIiZMBdlCHUDeZMP%2Fuploads%2Fgit-blob-c0a8fd5007c2ed69b13d766f3c42b30ce62a46f4%2Fagent-api.yaml?alt=media)
{% endopenapi %}

### Workflow 게시

에이전트가 만들거나 수정한 Workflow의 최신 초안을 배포합니다.

{% openapi src="/files/0e5638be82bf2745ff3620eb2bd9f5a98dedf9b1" path="/{workspace}/agent/workflows/{workflowUrl}/publish" method="post" %}
[agent-api.yaml](https://83860450-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1YMZNIiZMBdlCHUDeZMP%2Fuploads%2Fgit-blob-c0a8fd5007c2ed69b13d766f3c42b30ce62a46f4%2Fagent-api.yaml?alt=media)
{% endopenapi %}

### 대화 목록 보기

{% openapi src="/files/0e5638be82bf2745ff3620eb2bd9f5a98dedf9b1" path="/{workspace}/agent/conversations" method="get" %}
[agent-api.yaml](https://83860450-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1YMZNIiZMBdlCHUDeZMP%2Fuploads%2Fgit-blob-c0a8fd5007c2ed69b13d766f3c42b30ce62a46f4%2Fagent-api.yaml?alt=media)
{% endopenapi %}

### 대화 보기

{% openapi src="/files/0e5638be82bf2745ff3620eb2bd9f5a98dedf9b1" path="/{workspace}/agent/conversations/{id}" method="get" %}
[agent-api.yaml](https://83860450-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1YMZNIiZMBdlCHUDeZMP%2Fuploads%2Fgit-blob-c0a8fd5007c2ed69b13d766f3c42b30ce62a46f4%2Fagent-api.yaml?alt=media)
{% endopenapi %}

## MCP 서버

AI 에이전트를 [MCP 서버](https://docs.roboflow.com/get-started/ko/agents/mcp-server.md) 에 연결하면 다음 도구를 사용해 Roboflow Agent에 작업을 맡길 수 있습니다.

<table data-search="false"><thead><tr><th width="290">도구</th><th>설명</th></tr></thead><tbody><tr><td><code>agent_chat</code></td><td>Roboflow AI 에이전트와 채팅합니다.</td></tr><tr><td><code>agent_chat_result</code></td><td>아직 실행 중인 작업의 결과를 가져옵니다.</td></tr><tr><td><code>agent_conversations_list</code></td><td>워크스페이스의 에이전트 대화 목록을 표시합니다.</td></tr><tr><td><code>agent_conversation_get</code></td><td>메시지 기록이 포함된 대화 하나를 가져옵니다.</td></tr><tr><td><code>agent_workflow_publish</code></td><td>에이전트가 수정한 Workflow의 최신 초안을 게시합니다.</td></tr></tbody></table>
