Kickoff Crew

개요

Crew를 CrewAI AMP 플랫폼에 배포한 후에는 웹 인터페이스 또는 API를 통해 실행을 시작할 수 있습니다. 이 가이드는 두 가지 접근 방식을 모두 다룹니다.

방법 1: 웹 인터페이스 사용

1단계: 배포된 Crew로 이동하기

CrewAI AMP에 로그인합니다.
프로젝트 목록에서 crew 이름을 클릭합니다.
crew의 상세 페이지로 이동합니다.

2단계: 실행 시작

crew의 상세 페이지에서 실행을 시작할 수 있는 두 가지 옵션이 있습니다:

옵션 A: 빠른 시작

Test Endpoints 섹션에서 Kickoff 링크를 클릭합니다.
JSON 에디터에서 crew에 필요한 입력 파라미터를 입력합니다.
Send Request 버튼을 클릭합니다.

옵션 B: 시각적 인터페이스 사용

crew 상세 페이지에서 Run 탭을 클릭합니다.
양식 필드에 필요한 입력값을 입력합니다.
Run Crew 버튼을 클릭합니다.

3단계: 실행 진행 상황 모니터링

실행을 시작한 후:

kickoff_id가 포함된 응답을 받게 됩니다. - 이 ID를 복사하세요
이 ID는 실행을 추적하는 데 필수적입니다

4단계: 실행 상태 확인

실행 진행 상황을 모니터링하려면:

Test Endpoints 섹션에서 “Status” 엔드포인트를 클릭하세요
지정된 필드에 kickoff_id를 붙여넣으세요
“Get Status” 버튼을 클릭하세요

상태 응답에는 다음이 표시됩니다:

현재 실행 상태(running, completed 등)
진행 중인 작업에 대한 세부 정보
지금까지 생성된 모든 출력

5단계: 최종 결과 보기

실행이 완료되면:

상태가 completed로 변경됩니다.
전체 실행 결과와 출력을 확인할 수 있습니다.
더 자세한 내용을 보려면 crew 상세 페이지의 Executions 탭을 확인하세요.

방법 2: API 사용

CrewAI AMP REST API를 사용하여 프로그래밍 방식으로 crews를 시작할 수도 있습니다.

인증

모든 API 요청에는 인증을 위한 베어러 토큰이 필요합니다:

curl -H "Authorization: Bearer YOUR_CREW_TOKEN" https://your-crew-url.crewai.com

베어러 토큰은 crew의 상세 페이지의 Status 탭에서 확인할 수 있습니다.

크루 상태 확인

작업을 실행하기 전에 크루가 정상적으로 실행되고 있는지 확인할 수 있습니다:

curl -H "Authorization: Bearer YOUR_CREW_TOKEN" https://your-crew-url.crewai.com

요청이 성공하면 크루가 정상적으로 동작 중임을 나타내는 메시지가 반환됩니다:

Healthy%

1단계: 필요한 입력값 확인

먼저, crew에서 요구하는 입력값이 무엇인지 확인합니다:

curl -X GET \
  -H "Authorization: Bearer YOUR_CREW_TOKEN" \
  https://your-crew-url.crewai.com/inputs

응답은 예를 들어 다음과 같이 필수 입력 파라미터 배열을 포함한 JSON 객체로 반환됩니다:

{ "inputs": ["topic", "current_year"] }

이 예시에서는 해당 crew에서 두 개의 입력값인 topic과 current_year를 필요로 함을 보여줍니다.

2단계: kickoff 실행

필수 입력값을 제공하여 실행을 시작합니다:

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_CREW_TOKEN" \
  -d '{"inputs": {"topic": "AI Agent Frameworks", "current_year": "2025"}}' \
  https://your-crew-url.crewai.com/kickoff

응답에는 추적에 필요한 kickoff_id가 포함됩니다:

{ "kickoff_id": "abcd1234-5678-90ef-ghij-klmnopqrstuv" }

3단계: 실행 상태 확인

kickoff_id를 사용하여 실행 상태를 가져옵니다:

curl -X GET \
  -H "Authorization: Bearer YOUR_CREW_TOKEN" \
  https://your-crew-url.crewai.com/status/abcd1234-5678-90ef-ghij-klmnopqrstuv

응답은 실행 상태, 진행 상황, 결과를 보여줍니다. 새 응답을 받으려면 요청을 다시 보내십시오. 다음은 실행 중인 크루의 응답 예시입니다:

{
  "state": "RUNNING",
  "status": "Task is Running",
  "progress": {
    "unit": "task",
    "completed": 1,
    "total": 3,
    "remaining": 2,
    "current": "write_report",
    "current_agent": "Researcher",
    "started_at": "2025-09-10T18:00:00+00:00",
    "updated_at": "2025-09-10T18:02:14+00:00",
    "duration_seconds": 134.0
  },
  "last_event": {
    "type": "tool_usage_started",
    "timestamp": "2025-09-10T18:02:14+00:00",
    "tool_name": "SerperDevTool",
    "agent_role": "Researcher"
  },
  "events_count": 24,
  "events_by_type": {
    "crew_kickoff_started": 1,
    "task_started": 2,
    "agent_execution_started": 2,
    "tool_usage_started": 3
  },
  "triggered_by": { "type": "user", "id": "4711" },
  "execution_origin": "api",
  "source": "memory"
}

응답 필드

필드	설명
`state`	실행 상태입니다: `PENDING`, `STARTED`, `RUNNING`, `SUCCESS`, `FAILED`, `PAUSED` 또는 `REVOKED`.
`status`	상태에 대한 짧은 메시지입니다.
`result`	최종 출력입니다. 실행이 끝날 때까지 이 필드는 비어 있습니다.
`result_json`	출력이 JSON 객체인 경우의 JSON 형식 최종 출력입니다.
`usage_metrics`	실행의 토큰 수입니다.
`progress`	완료된 작업의 양입니다. 진행 상황을 참조하십시오.
`last_event`	가장 최근 이벤트입니다. 이벤트를 참조하십시오.
`events`	가장 최근 이벤트 목록입니다. 가장 오래된 이벤트가 먼저 옵니다.
`events_count`	실행이 보낸 이벤트의 수입니다.
`events_by_type`	각 유형별 이벤트의 수입니다.
`triggered_by`	실행을 시작한 주체입니다. 실행 주체를 참조하십시오.
`execution_origin`	요청의 출처입니다. 실행 출처를 참조하십시오.
`last_step`	가장 최근 에이전트 스텝입니다. 크루에만 해당합니다.
`last_executed_task`	크루가 완료한 가장 최근 태스크입니다. 크루에만 해당합니다.
`flow_id`	사람의 피드백을 기다리는 플로우의 식별자입니다.
`source`	데이터의 출처입니다: `memory` 또는 `application`.

값이 없는 필드는 null입니다.

진행 상황

progress 객체는 완료된 작업의 양을 보여줍니다.

필드	설명
`unit`	작업 단위입니다. 크루는 `task`를 사용합니다. 플로우는 `step`을 사용합니다.
`completed`	완료된 단위의 수입니다.
`total`	실행에 포함된 단위의 수입니다.
`remaining`	완료되지 않은 단위의 수입니다.
`current`	지금 실행 중인 태스크 또는 메서드의 이름입니다.
`current_agent`	지금 작업 중인 에이전트의 역할입니다.
`started_at`	워커가 실행을 시작한 시각입니다.
`updated_at`	가장 최근 변경의 시각입니다.
`duration_seconds`	시작부터 `updated_at`까지의 초 수입니다.

플로우는 실행 중에 다음 스텝을 선택합니다. 플로우가 끝나기 전에는 스텝의 수를 알 수 없습니다. 따라서 플로우에서는 total과 remaining이 항상 null입니다:

{
  "unit": "step",
  "completed": 4,
  "total": null,
  "remaining": null,
  "current": "summarize",
  "current_agent": null,
  "started_at": "2025-09-10T18:00:00+00:00",
  "updated_at": "2025-09-10T18:00:41+00:00",
  "duration_seconds": 41.2
}

플로우에서는 백분율을 계산하지 마십시오. completed 값을 스텝의 개수로 표시하십시오.

이벤트

이벤트는 특정 시점에 실행이 무엇을 했는지 보여줍니다. 각 이벤트는 요약입니다. 이벤트에는 프롬프트, 출력, 플로우 상태가 포함되지 않습니다.

필드	설명
`type`	이벤트의 유형입니다. 예: `task_started`.
`timestamp`	이벤트의 시각입니다.
`crew_name`	이벤트에 있는 경우 크루의 이름입니다.
`flow_name`	이벤트에 있는 경우 플로우의 이름입니다.
`method_name`	이벤트에 있는 경우 플로우 메서드의 이름입니다.
`task_name`	이벤트에 있는 경우 태스크의 이름입니다.
`agent_role`	이벤트에 있는 경우 에이전트의 역할입니다.
`tool_name`	이벤트에 있는 경우 도구의 이름입니다.
`model`	이벤트에 있는 경우 모델의 이름입니다.
`error`	이벤트에 있는 경우 오류 메시지입니다.

events 목록은 가장 최근 이벤트 100개를 유지합니다. 실행이 그보다 많은 이벤트를 보내면 플랫폼이 가장 오래된 이벤트를 목록에서 제거합니다. events_count 필드는 전체 이벤트의 수를 제공합니다. events_by_type 필드도 전체 이벤트를 계산합니다. 목록이 가득 차도 이 두 필드는 정확하게 유지됩니다.

실행 주체

triggered_by 객체는 누가 실행을 시작했는지 보여줍니다.

필드	설명
`type`	주체의 유형입니다: `user`, `service_account` 또는 `unknown`.
`id`	CrewAI AMP에서의 주체 식별자입니다.

응답은 유형과 식별자만 제공합니다. 이름, 이메일 주소, 조직은 제공하지 않습니다. 배포의 모든 토큰은 해당 배포의 모든 실행 상태를 읽을 수 있습니다. 따라서 응답에는 개인 정보가 포함되지 않습니다. 요청이 배포의 고정 AUTH_TOKEN을 사용하면 유형은 unknown입니다. 플랫폼이 주체를 알 수 없으면 triggered_by는 null입니다.

실행 출처

execution_origin 필드는 실행이 어떻게 시작되었는지 보여줍니다.

값	설명
`ui`	사용자가 CrewAI AMP 인터페이스에서 실행을 시작했습니다.
`schedule`	스케줄이 실행을 시작했습니다.
`trigger`	자동화 트리거가 실행을 시작했습니다.
`chat`	채팅 메시지가 실행을 시작했습니다.
`hitl-resume`	사람의 피드백 이후 플랫폼이 실행을 계속했습니다.
`replay`	리플레이가 실행을 시작했습니다.
`api`	배포 API에 대한 요청이 실행을 시작했습니다.

선택 설정

이벤트 로그를 변경하려면 배포에 다음 환경 변수를 설정하십시오.

변수	기본값	설명
`CREWAI_STATUS_EVENTS`	`true`	이벤트 로그와 진행 데이터를 중지하려면 값을 `false`로 설정합니다.
`CREWAI_STATUS_MAX_EVENTS`	`100`	`events` 목록에 유지할 이벤트의 수입니다.
`CREWAI_STATUS_EVENT_FLUSH_SECONDS`	`2.0`	이벤트 로그를 두 번 기록하는 사이의 최소 초 수입니다.

다음 제한이 적용됩니다:

crewAI 1.15.21 이하 버전을 실행하는 배포는 진행 데이터와 이벤트 데이터에 null을 반환합니다. 프로젝트의 crewAI 버전을 올린 다음 크루를 다시 배포하십시오.
대기열에서 기다리는 실행의 상태는 PENDING입니다. 이 실행은 triggered_by에 null을 반환합니다.
사람의 피드백 이후 계속되는 플로우는 피드백 이후의 스텝만 계산합니다.
"source": "application"인 응답은 진행 데이터와 이벤트 데이터에 null을 반환합니다.

실행 처리

장기 실행

오랜 시간이 걸릴 수 있는 실행의 경우:

주기적으로 상태를 확인하는 폴링 메커니즘을 구현하는 것을 고려하세요
실행 완료 시 알림을 받을 수 있도록 웹훅(가능한 경우)을 사용하세요
잠재적인 타임아웃에 대비하여 오류 처리를 구현하세요

실행 컨텍스트

실행 컨텍스트에는 다음이 포함됩니다:

시작 시 제공된 입력값
배포 중에 구성된 환경 변수
태스크 간에 유지되는 상태

실행 실패 디버깅

실행이 실패할 경우:

“Executions” 탭에서 자세한 로그를 확인하세요
“Traces” 탭에서 단계별 실행 세부 정보를 검토하세요
트레이스 세부 정보에서 LLM 응답과 도구 사용 내역을 확인하세요

도움이 필요하신가요?

실행 문제 또는 엔터프라이즈 플랫폼 관련 질문이 있으신 경우, 지원팀에 문의하세요.

시작 안내

빌드

운영

관리

통합 문서

How-To Guides

트리거

학습 자원

개요

방법 1: 웹 인터페이스 사용

1단계: 배포된 Crew로 이동하기

2단계: 실행 시작

옵션 A: 빠른 시작

옵션 B: 시각적 인터페이스 사용

3단계: 실행 진행 상황 모니터링

4단계: 실행 상태 확인

5단계: 최종 결과 보기

방법 2: API 사용

인증

크루 상태 확인

1단계: 필요한 입력값 확인

2단계: kickoff 실행

3단계: 실행 상태 확인

응답 필드

진행 상황

이벤트

실행 주체

실행 출처

선택 설정

실행 처리

장기 실행

실행 컨텍스트

실행 실패 디버깅

도움이 필요하신가요?

​개요

​방법 1: 웹 인터페이스 사용

​1단계: 배포된 Crew로 이동하기

​2단계: 실행 시작

​옵션 A: 빠른 시작

​옵션 B: 시각적 인터페이스 사용

​3단계: 실행 진행 상황 모니터링

​4단계: 실행 상태 확인

​5단계: 최종 결과 보기

​방법 2: API 사용

​인증

​크루 상태 확인

​1단계: 필요한 입력값 확인

​2단계: kickoff 실행

​3단계: 실행 상태 확인

​응답 필드

​진행 상황

​이벤트

​실행 주체

​실행 출처

​선택 설정

​실행 처리

​장기 실행

​실행 컨텍스트

​실행 실패 디버깅

도움이 필요하신가요?

개요

방법 1: 웹 인터페이스 사용

1단계: 배포된 Crew로 이동하기

2단계: 실행 시작

옵션 A: 빠른 시작

옵션 B: 시각적 인터페이스 사용

3단계: 실행 진행 상황 모니터링

4단계: 실행 상태 확인

5단계: 최종 결과 보기

방법 2: API 사용

인증

크루 상태 확인

1단계: 필요한 입력값 확인

2단계: kickoff 실행

3단계: 실행 상태 확인

응답 필드

진행 상황

이벤트

실행 주체

실행 출처

선택 설정

실행 처리

장기 실행

실행 컨텍스트

실행 실패 디버깅