Roboflow 에이전트

워크플로와 Rapid 모델을 만들고, 실행하고, 디버그하는 앱 내 Roboflow 에이전트와 해당 HTTP 채팅 API.

소개

Roboflow Agent는 귀하의 워크스페이스 그리고 생성, 편집, 실행 및 디버그할 수 있습니다 워크플로. 또한 이를 사용하여 설정할 수도 있습니다 Rapid 모델. 워크스페이스 왼쪽 사이드바에서 "Agent"를 클릭하여 Agent에 액세스하세요.

기능

Agent는 다음을 할 수 있습니다:

• 빌드 워크플로 자연어 설명으로부터 빌드하고, 실행하며, 실패를 자동으로 수정합니다(턴당 최대 3회 재시도). 모든 입력 모드를 지원합니다: 이미지 URL, RTSP 스트림, 로컬 비디오 및 웹캠.

• 첨부된 이미지와 비디오를 이해합니다. 채팅에 이미지나 짧은 비디오를 첨부, 드래그 앤 드롭 또는 붙여넣기할 수 있습니다. Agent는 미디어를 분석하여 무엇이 담겨 있는지 파악하고, 이를 바탕으로 워크플로를 빌드한 다음, 동일한 미디어에서 워크플로를 다시 실행하여 결과를 검증합니다.

• 설정 및 관리 Rapid 모델.

• 요청 시 데이터셋을 관리합니다: 프로젝트의 학습, 검증, 테스트 분할을 재조정 또는 프로젝트 병합 하여 새 프로젝트로 만듭니다. 두 작업 모두 Activity Center에서 추적할 수 있는 백그라운드 작업으로 실행됩니다.

• 프로젝트 생성 "+" 탭에서. "Create" 아래의 "New model"을 클릭하고, 프로젝트 유형을 선택한 다음 나머지 양식을 작성하세요. 생성되면 탭이 새 프로젝트로 바뀝니다.

• 시작 모델 학습 프로젝트 탭에서 실행합니다. "Train" 버튼은 탭 안에서 전체 학습 흐름(engine, architecture 및 version 단계)을 열어 주며, 데이터셋 내보내기를 준비해 줍니다.

• 열린 워크플로, Rapid 모델, 사용량 보기, 프로젝트 및 계획을 탭으로 정리하세요. "+" 탭을 사용해 닫은 항목을 다시 열거나 새 항목을 만드세요. 후속 대화는 이전 채팅의 산출물을 상속합니다.

• "+" 탭에서 모델 중 하나를 여세요. "Recent models"에서 하나를 선택하거나 검색하여 워크스페이스의 모든 모델을 볼 수 있습니다. 모델은 대화와 함께 유지되므로 새로고침 후 다시 열립니다.

• "Dataset" 섹션이 있는 프로젝트 탭을 여세요 프로젝트의 이미지를 라벨링 단계별로 그룹화합니다 (Unassigned, Annotating, Review, Dataset). 주석 편집기에서 아무 이미지를 열고, 작업을 다음 단계로 이동시키고, 검토 중인 이미지를 승인하거나 거부하세요.

• 워크플로의 입력 이미지에 감지 영역을 그릴 수 있는 영역 편집기를 여세요.

• UI 이벤트에 반응합니다: Rapid 학습 실패를 진단하고, 워크플로 실행 오류를 조사하며(채팅 입력 위의 "Investigate" 프롬프트를 통해), Rapid 소스 워크플로가 준비되면 자동으로 계속합니다.

• 워크스페이스의 "Historical Usage" 탭을 여세요 크레딧 사용량 대시보드 질문에 맞는 필터(기간, 기능, 귀속, 누적/일별, 크레딧/달러)와 함께. Agent는 대화가 이어지는 동안 탭을 동기화 상태로 유지합니다. "View Billing" 권한이 필요합니다.

• 설정 Vision Events 워크플로에서. 모델을 실행하는 워크플로를 만들 때, Agent는 Vision Events 블록을 추가하고 올바른 사용 사례, 필요하면 하나를 생성합니다.

• "Settings" 섹션이 있는 프로젝트 탭을 여세요. 여기서 Active Learning 해당 프로젝트에서 켜거나 끄고, 수집 한도와 조건을 편집할 수 있습니다.

• 귀하의 Vision Events 데이터(예: "지난주에 실패가 몇 건이었나요?", "어떤 카메라가 가장 많은 결함을 생성하나요?"). Agent는 이벤트를 집계하고, 시간 경과에 따른 성공 및 실패율을 추적하며, 숫자 필드의 합계, 평균, 최소값, 최대값 또는 고유 값 개수를 구할 수 있습니다. 총계는 귀하의 사용 사례 레코드, 사용자 지정 메타데이터를 포함하여, 또는 일별/주별로 버킷화할 수 있습니다(버킷은 UTC를 사용합니다). 질문이 워크스페이스의 보존 기간, Agent는 0으로 답하는 대신 조회할 수 있는 가장 이른 날짜를 알려줍니다. "View Vision Events" 권한이 필요합니다. 참조: 이벤트 조회.

• Vision Events를 초안 작성, 미리보기, 예약하기 요약 보고서 원하는 다이제스트를 평이한 설명으로 입력하면 생성합니다(예: "라인별 성공 및 실패 건수의 매주 금요일 아침 다이제스트"). Agent는 이벤트가 실제로 전송하는 필드로 보고서를 만들고, 실제 데이터로 미리보기를 보여 주며, 즉시 또는 선택한 일정에 맞춰 이메일로 보낼 수 있습니다.

• 귀하의 엣지 장치에 대해 읽기 전용으로 접근하여 질문에 답변합니다 Deployment Manager 플릿, 구성, 원격 측정, 로그, 이벤트 및 스트림. Deployment Manager를 일일이 클릭하는 대신 장치 상태나 스트림 오류에 대해 물어보세요(예: "어떤 장치가 오프라인인가요?", "왜 이 스트림에서 오류가 났나요?"). 장치 자격 증명은 Agent와 절대 공유되지 않습니다.

HTTP API

Agent API를 사용하면 Roboflow AI agent와 상호작용할 수 있습니다 api.roboflow.com. 자연어 지침을 보내 생성하거나 편집할 수 있습니다 워크플로워크플로를 만든 뒤, 준비되면 게시할 수 있습니다. 모든 편집 내용은 명시적으로 게시하기 전까지 초안으로 저장됩니다.

인증 방식은 다음과 같습니다 API 키. 다음을 사용하는 경우 범위 지정 API 키 폴더 제한이 있으면 agent는 해당 폴더 범위 내의 워크플로에만 액세스할 수 있습니다.

채팅

POST /:workspace/agent/chat

AI agent에게 메시지를 보내세요. agent는 새 워크플로를 만들고, 기존 워크플로를 편집하며, 워크스페이스에 대한 질문에 답할 수 있습니다. 워크플로 변경 사항은 초안으로 저장됩니다.

새 대화를 시작하거나 기존 대화를 이어가려면 다음을 전달하세요 conversation_id.

헤더

이름	값
Content-Type	application/json

본문

이름	유형	설명	필수
api_key	string	워크스페이스 API 키.
message	string	agent에게 전달할 지시사항 또는 질문.
conversation_id	string	이어질 기존 대화의 ID입니다. 새 대화를 시작하려면 생략하세요.
mode	string	agent (기본값) 또는 plan. plan 모드에서는 agent가 변경을 가하지 않고 수행할 작업을 개괄합니다.

예시 요청

curl -X POST "https://api.roboflow.com/my-workspace/agent/chat" \\
  -H "Content-Type: application/json" \\
  -d '{
    "api_key": "'"$ROBOFLOW_API_KEY"'",
    "message": "자동차를 감지하고 개수를 세는 워크플로를 만들어 주세요"
  }'

응답

{
  "text": "'Car Counter'라는 워크플로를 만들었습니다 ...",
  "workflows": [
    {
      "id": "wf_abc123",
      "name": "Car Counter",
      "url": "car-counter",
      "specification": { ... }
    }
  ],
  "conversation_id": "conv_xyz789"
}

필드	설명
text	agent의 응답 텍스트.
workflows	이번 턴에 생성되거나 수정된 워크플로입니다. 각 항목에는 id, name, url, 그리고 초안 specification.
conversation_id	대화 ID입니다. 대화를 계속하려면 후속 요청에서 이를 다시 전달하세요.

필요한 범위: workflow:create 및 workflow:update.

워크플로 게시

POST /:workspace/agent/workflows/:workflowUrl/publish

agent가 생성하거나 편집한 워크플로의 최신 초안 버전을 배포합니다. 게시되지 않은 초안이 없으면 엔드포인트는 400.

예시 요청

curl -X POST "https://api.roboflow.com/my-workspace/agent/workflows/car-counter/publish?api_key=$ROBOFLOW_API_KEY"

응답

{
  "workflowId": "wf_abc123",
  "workflowUrl": "car-counter",
  "versionId": "v-1700000000",
  "status": "published"
}

필요한 범위: workflow:update.

대화 목록

GET /:workspace/agent/conversations

워크스페이스의 모든 agent 대화를 반환합니다.

쿼리

이름	유형	설명	필수
api_key	string	워크스페이스 API 키.
source	string	출처로 필터링: api 또는 web.
workflow	string	워크플로 URL 슬러그로 필터링합니다. 이 워크플로를 참조하는 대화만 반환합니다.

예시 요청

curl "https://api.roboflow.com/my-workspace/agent/conversations?api_key=$ROBOFLOW_API_KEY&source=api"

응답

{
  "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

모든 메시지를 포함한 전체 대화를 반환합니다.

예시 요청

curl "https://api.roboflow.com/my-workspace/agent/conversations/conv_xyz789?api_key=$ROBOFLOW_API_KEY"

응답

{
  "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": "'Car Counter'라는 워크플로를 만들었습니다 ..." }]
    }
  ]
}

필요한 범위: workflow:read.

오류 응답

모든 엔드포인트는 오류를 다음과 같이 반환합니다 { "error": "..." } 적절한 HTTP 상태 코드와 함께.

상태	의미
400	잘못된 요청(누락된 message, 게시할 초안 없음 등)
401	API 키가 없거나 유효하지 않습니다.
402	크레딧이 부족합니다.
403	범위가 부족하거나, 워크플로가 폴더 범위 밖에 있거나, 이 워크스페이스에서 agent 기능이 비활성화되어 있습니다.
404	워크플로 또는 대화를 찾을 수 없습니다.
500	내부 서버 오류.

워크스페이스 수준에서 agent 기능이 비활성화되어 있으면, 채팅 및 게시 엔드포인트는 403 함께 "error_type": "AGENT_DISABLED".