에이전트#
에이전트는 이미지, 모델, 조건 및 작업을 시각적 워크플로로 연결합니다. YOLO를 사용해 자세히 살펴볼 이미지가 무엇인지 결정하거나, 비전-언어 모델에 이미지 설명을 요청하거나, 선택한 이미지를 검토용 데이터셋에 모을 수 있습니다.
사이드바에서 에이전트를 열거나 platform.ultralytics.com/agents로 이동하세요. 에이전트는 개인 및 팀 작업 공간에서 로그인한 모든 사용자의 사이드바에 표시되며, 활성화해야 하는 얼리 액세스 설정은 없습니다.
첫 번째 워크플로 실행하기#
- 에이전트를 열고 블록 추가 > 템플릿을 클릭한 다음 YOLO → VLM 모니터를 선택하세요.
- 입력 이미지 블록을 선택하고 업로드된 데이터셋을 선택한 다음 사람이 포함된 이미지를 선택하세요. 공유 체험판에서는 최대 4메가픽셀의 이미지를 사용하세요.
- 기본 YOLO26 nano 모델을 그대로 사용하세요. YOLO가 사람을 한 명 이상 감지하면 조건이 통과됩니다.
- 장면 설명을 선택하고 비전-언어 모델을 선택한 다음 프롬프트를 입력하세요. 아직 설정하지 않았다면 설정 > API 키에서 해당 공급자의 키를 추가하세요. 팀 작업 공간에서는 작업 공간 소유자에게 공급자 키를 추가하거나 교체해 달라고 요청하세요.
- 소규모 실행을 위해 공유 체험판 · 60초를 선택한 상태로 두고 실행을 클릭하세요.
- 블록이 업데이트되는 과정을 확인하고 출력을 살펴보세요. 사람이 감지되지 않으면 설명 분기를 실행하지 않고 조건이 완료됩니다.
초안을 저장하기 전에 실행할 수 있습니다. 워크플로 저장을 사용해 워크플로의 이름을 지정하고 나중에 사용할 수 있도록 저장한 다음, 변경 사항을 적용한 뒤 다시 저장하세요. Python 버튼을 누르면 생성된 워크플로 코드가 표시됩니다.
템플릿으로 시작하기#
| 템플릿 | 워크플로 | 용도 |
|---|---|---|
| YOLO → VLM 모니터 | 이미지 → YOLO → 조건 → 비전-언어 모델 → 출력 | 사람이 감지된 경우에만 장면 설명 |
| 불확실한 감지 결과 수집 | 데이터셋 → 배포 → 신뢰도 조건 → 데이터셋 | 감지가 불확실한 이미지로 검토용 데이터셋 만들기 |
| 캡처 및 알림 | 이미지 → YOLO → 조건 → 데이터셋 및 Slack | 동일한 조건에서 이미지를 저장하고 채널에 알림 보내기 |
템플릿은 편집하여 사용할 수 있는 시작점입니다. 실행하기 전에 작업 공간에 맞게 이미지, 배포, 대상 데이터셋 및 통합을 선택하세요. 이 워크플로는 실행을 클릭할 때 실행되며, 모니터 템플릿은 선택한 입력 이미지를 분석합니다.
실행 환경 선택하기#
실행 옆의 실행 선택기를 사용해 워크플로의 하드웨어를 선택할 수 있습니다.
| 선택 항목 | 용도 | 제한 및 요금 |
|---|---|---|
| 공유 체험판 · 60초 | 소규모 워크플로 테스트 | 최대 60초, 입력 이미지 총 20개(각 최대 4메가픽셀), 모델/공급자 호출 20회입니다. 공식 YOLO26 nano 모델을 사용하는 로컬 YOLO 모델 한 개를 지원합니다. |
| 기존 전용 배포 | 더 큰 데이터셋, 더 긴 실행 시간 또는 다른 로컬 모델 | 요건을 충족하는 무료 전용 배포를 포함해 해당 배포의 기존 하드웨어와 요금이 적용됩니다. 전체 워크플로 실행 시간이나 이미지 수에는 제한이 없습니다. |
| 새 배포… | 빌더에서 전용 하드웨어 만들기 | 기존 배포 생성 및 요금 대화상자가 열립니다. 리소스를 선택한 다음 배포가 준비될 때까지 기다리세요. |
공유 체험판은 분당 세 번 실행할 수 있으며, 전용 배포에서 실행할 때는 속도 제한이 없습니다. Platform 실행은 최대 20개 블록을 지원합니다. 모델/공급자 호출에는 YOLO, 비전-언어 모델, 배포 예측, Slack 및 Webhook 작업이 포함됩니다. 분기를 사용하면 입력 이미지당 호출 횟수가 늘어날 수 있습니다.
전용 실행은 선택한 배포에서 체크포인트가 적용된 요청으로 계속 진행됩니다. 브라우저를 닫거나 새로고침해도 실행이 중단되지 않습니다. 기존 배포 제한과 공급자 제한은 계속 적용되며, 언어 모델 사용 요금은 키에 연결된 공급자에게 청구됩니다. 하드웨어 옵션은 배포 요금을 참조하세요.
배포 블록은 예측 단계에서 사용할 엔드포인트를 선택합니다. 실행 선택기는 워크플로 자체를 실행할 위치를 지정합니다. 두 항목에 동일한 전용 배포를 선택할 수 있습니다.
블록 구성하기#
| 블록 | 용도 |
|---|---|
| 이미지 | 이미지 또는 기본적으로 최대 10개 프레임으로 샘플링한 동영상을 업로드하거나, 업로드된 데이터셋에서 이미지 한 장을 선택합니다. |
| 들어오는 연결이 없는 데이터셋 | 선택한 데이터셋과 분할에서 이미지를 읽으며, 입력 한도를 설정할 수 있습니다. |
| YOLO | 공식 모델 또는 작업 공간의 학습된 모델을 실행합니다. |
| 배포 | 준비 상태인 기존 Platform 배포를 통해 예측합니다. |
| LLM | 이미지와 이전 단계의 컨텍스트를 선택한 언어 모델 또는 비전-언어 모델에 전송합니다. |
| 게이트 | 조건 또는 실행 주기를 사용해 후속 실행을 제어합니다. |
| 들어오는 연결이 있는 데이터셋 | 들어오는 이미지를 대상 데이터셋에 추가합니다. |
| Slack | 작업 공간에 연결된 Slack 채널로 메시지를 보냅니다. |
| Webhook | POST JSON 본문을 HTTPS 엔드포인트로 전송합니다. |
| 내보내기 | Platform의 기존 내보내기 워크플로를 사용해 모델을 내보냅니다. |
| 출력 | 이전 단계의 결과를 표시합니다. |
블록을 선택해 설정을 편집하세요. 출력을 다른 블록에 연결하면 결과를 다음 단계로 전달할 수 있습니다. 하나의 출력을 여러 블록에 연결할 수 있습니다. 예를 들어 하나의 조건을 대상 데이터셋과 Slack 모두에 연결할 수 있습니다. 각 분기는 동일하게 평가된 조건을 사용합니다.
조건으로 감지 결과 필터링하기#
감지 개수와 신뢰도 필터에는 동일한 게이트 블록을 사용하세요. 이전 단계의 결과, 모든 클래스 또는 특정 클래스, 비교 연산자를 선택합니다. 예를 들면 다음과 같습니다.
- 사람 수 ≥ 1: 사람이 한 명 이상 감지되면 계속 진행합니다.
- 신뢰도 0.25~0.5: 범위에 포함되는 감지 결과가 하나 이상 있으면 계속 진행합니다.
- 특정 클래스의 신뢰도 범위: 해당 클래스의 불확실한 감지 결과만 수집합니다.
신뢰도 필터는 개별 감지 결과를 확인합니다. 점수가 0.3 및 0.9인 이미지도 감지 결과 하나가 일치하므로 0.25–0.5 범위를 통과합니다. 감지 결과가 없는 이미지는 신뢰도 조건을 통과하지 못합니다. 평가하려는 감지 결과를 유지할 수 있도록 예측 모델의 신뢰도 임계값을 충분히 낮게 설정하세요.
조건이 일치하지 않으면 후속 출력 없이 완료됩니다. 해당 이미지에 대해서는 연결된 작업이 실행되지 않습니다.
검토용 이미지 수집#
Collect Uncertain Detections를 열고 소스 데이터셋과 분할을 선택한 다음, 예측 배포를 선택하고 신뢰도 범위를 설정합니다. 마지막 Dataset 블록에서 기존 대상 데이터셋을 선택합니다. 필요한 경우 먼저 Datasets 페이지에서 데이터셋을 만듭니다.
대상 데이터셋의 train 분할에는 라벨이 없는 원본 이미지가 저장됩니다. 이미 존재하는 사본은 건너뛰며, 일반 데이터셋 저장 용량 할당량이 적용됩니다. 소스 라벨과 모델 예측은 어노테이션으로 복사되지 않습니다. 대상 데이터셋을 기존 어노테이션 편집기에서 열어 수집된 이미지를 검토하고 라벨을 지정합니다.
워크스페이스에서 접근할 수 있는 호스팅 이미지와 편집 권한이 있는 대상 데이터셋을 사용합니다. 연결된 클라우드 스토리지 및 온프레미스 데이터셋은 수집 대상으로 사용할 수 없습니다.
조건부 Slack 알림 전송#
Settings > Integrations에서 Slack을 연결한 다음, 조건을 Slack 블록에 연결합니다. 메시지를 입력하고 {output}을 사용해 업스트림 결과를 포함합니다. Capture and Alert는 동일한 조건을 데이터셋에도 연결하므로, 조건에 일치하는 이미지가 수집되고 연결된 채널로 메시지가 전송됩니다.
워크플로 Slack 메시지는 블록에서 설정합니다. 이 메시지는 Settings의 학습, 내보내기 및 배포 알림 설정과 별개입니다.
웹훅 전송#
Webhook 블록은 결과마다 POST 하나를 Content-Type: application/json과 함께 공개 HTTPS URL로 전송하므로, JSON 요청을 수락하는 모든 서비스에서 조건의 결과를 수신할 수 있습니다. 대상 URL과 문자열 안에 {output}를 포함하는 최대 10,000자 길이의 JSON 본문을 입력하면, 해당 토큰은 업스트림 결과로 대체되며 블록은 종단 블록으로서 나가는 연결을 허용하지 않습니다. 리디렉션은 따르지 않으며, 연결은 5초 후 시간 초과되고, 2xx가 아닌 응답은 블록을 실패 처리합니다.
진행 상황 확인 및 실행 중지#
활성 블록에는 녹색 스피너가 표시됩니다. 완료된 블록에는 녹색 체크 표시와 녹색 테두리가, 실패한 블록에는 빨간색 테두리가 표시됩니다. 각 블록에 도달한 입력 수가 표시되며, 조건이 일치하지 않으면 다운스트림 블록은 실행되지 않습니다.
페이지를 새로고침하면 실행 진행 상황과 선택된 실행 배포가 복원됩니다. 일치하는 워크플로의 완료된 결과는 계속 표시됩니다. 활성 실행을 취소하려면 Stop을 클릭합니다. 취소는 실행 중인 블록이 취소 지점에 도달할 때까지 대기합니다. 실행 배포를 중지하거나 삭제해도 워크플로가 취소됩니다.
API로 Agents 관리#
Agents API를 사용하면 코드에서 Agents를 나열하고 저장 및 삭제할 수 있으며, Python SDK에서는 이를 ultralytics-platform>=0.1.74의 client.agents로 사용할 수 있습니다. 저장 시 캔버스에 표시되는 것과 동일한 블록 오류가 반환됩니다. 실행은 여전히 캔버스에서 시작합니다. 저장된 Agent를 https://platform.ultralytics.com/agents?workflow={id}에서 열고 Run을 클릭합니다.
문제 해결#
- 실행이 공유 체험판 한도를 초과합니다: 적격한 무료 배포를 포함한 전용 배포를 선택하거나 이미지 해상도, 입력 수 및 모델/공급자 호출 수를 줄입니다.
- 배포를 준비 중이거나 중지된 상태입니다: 준비가 완료될 때까지 기다리거나 Deployments에서 배포를 시작합니다.
- 공급자 키가 없습니다: Settings > API Keys에서 선택한 공급자를 연결합니다. 팀 워크스페이스에서는 워크스페이스 소유자에게 키를 추가하거나 교체해 달라고 요청합니다.
- 대상에 도달하는 이미지가 없습니다: 조건과 예측 신뢰도 임계값을 확인합니다. 탐지 결과가 비어 있으면 신뢰도 범위를 충족하지 않습니다.
- 수집된 이미지에 라벨이 없습니다: 수집 기능은 검토할 원본 이미지를 추가합니다. 기존 어노테이션 도구를 사용해 라벨을 지정합니다.