메인 콘텐츠로 건너뛰기

개요

아티팩트는 Crew, Agent 또는 Flow가 만드는 이름 있는 파일입니다. HTML 보고서, 마크다운 문서, 차트, PDF, CSV 등이 해당됩니다. 각 아티팩트에는 identifier가 있습니다. 같은 실행에서 같은 identifier로 다시 저장하면 새 버전(v1, v2, …)이 만들어집니다. 로컬에서는 아티팩트가 디스크에 저장됩니다. CrewAI AMP에서는 실행 옆에 표시되며, 사람들이 미리 보고, 내려받고, 공유할 수 있습니다. 아티팩트는 직접 켜야 하는 기능입니다. Task나 Agent의 출력을 저장하거나, 도구로 Agent가 파일을 저장하게 하거나, 직접 작성한 코드에서 저장할 수 있습니다.

Task 또는 Agent 출력 저장

Task에 artifact를 설정합니다. Task가 끝나면 최종 출력이 아티팩트로 저장됩니다. 도구 호출도, 추가 토큰도 없으므로 모델이 저장을 잊을 수 없습니다.
JSON Crew에서는 crew.jsonc의 Task에 추가합니다.

CrewAI가 이름 정하기

세부 정보를 생략하려면 artifact=True를 전달합니다. CrewAI가 다음과 같이 채웁니다.
  • identifier와 title은 Task 이름(또는 설명)에서 가져옵니다. Flow 안에서는 Flow 메서드 이름을 사용합니다. 그 밖의 경우에는 Agent의 role을 사용합니다.
  • kind는 출력을 보고 정합니다. <!doctype html 또는 <html로 시작하면 html, <svg로 시작하면 svg, JSON 객체나 배열이면 json, 그 밖에는 markdown입니다.
같은 Task나 같은 Flow 메서드가 다시 실행되어도 이름이 같으므로, 다시 실행하면 새 아티팩트가 아니라 다음 버전이 만들어집니다.

단일 Agent

Agent.kickoff도 같은 artifact 인자를 Artifact 또는 True로 받습니다.
kickoff_async와 akickoff도 지원합니다.

선언형 Flow

Flow 선언에서는 call: agent 단계의 with 아래에 artifact를 설정합니다.
artifact: true는 메서드 이름을 사용하며, 여기서는 write-report가 됩니다. 세부 정보를 직접 정하려면 {identifier: weekly-report, title: Weekly report, kind: html} 같은 객체를 사용합니다. 실행이 앞서 저장한 아티팩트를 Agent에게 주려면 input_files 아래에 나열합니다. 각 항목은 참조이며, 단계가 실행될 때 불러옵니다.
version이 없으면 최신 버전을 사용합니다. 아티팩트가 없으면 Agent가 실행되기 전에 단계가 실패합니다. 입력 파일에는 crewai[file-processing]이 필요합니다.

Agent가 쓰는 파일 저장

차트, PDF 등 Agent의 도구가 디스크에 쓰는 파일은 file_path에 파일 위치를 설정합니다. CrewAI는 텍스트 출력 대신 그 파일을 저장합니다. image, pdf, file 종류에는 file_path가 필요합니다.
  • 파일을 어디에 쓸지 Agent에게 알려 주세요. 예를 들어 Task 설명에 적습니다.
  • Task에서는 file_path의 {placeholders}가 output_file처럼 kickoff 입력으로 채워집니다. Flow 선언에서는 output/${state.quarter}.png처럼 ${...} 표현식을 사용합니다.
  • 파일은 작업 디렉터리 안에 있어야 합니다. 그 밖의 경로는 거부되므로 차트와 PDF는 프로젝트 디렉터리에 저장하세요.

저장된 아티팩트 사용

저장된 버전은 출력의 artifact에 있으므로, 콜백이나 이후 Flow 단계, 직접 작성한 코드에서 링크를 전달할 수 있습니다.
Flow 선언에서는 ${outputs.write_report.artifact.url}로 읽습니다.

Agent가 아티팩트를 저장하게 하기

Crew에 artifacts=True를 설정하면 모든 Agent가 save_artifact 도구를 받습니다. Agent 하나에 설정하면 그 Agent만 도구를 받습니다.
도구는 identifier, title, kind와 함께 content(텍스트) 또는 file_path(차트 PNG처럼 Agent가 만든 파일) 중 하나를 받습니다. 결과는 JSON입니다.
이후 Task는 이 url을 사용할 수 있습니다. 예를 들어 Slack에 올리거나 이메일에 첨부할 수 있습니다.

코드에서 저장

Flow 단계 같은 Python 코드 어디에서나 save_artifact를 호출할 수 있습니다. Agent가 필요하지 않습니다.
content(str 또는 bytes)나 file_path 중 하나만 전달합니다. 반환값은 id, identifier, title, kind, version, content_type, size, url, share_url을 가진 SavedArtifact입니다.

저장된 아티팩트 읽기

실행이 저장한 아티팩트를 다시 읽으려면 load_artifact를 호출합니다. 최신 버전의 바이트를 반환하며, 버전을 지정하면 그 버전의 바이트를 반환합니다.
이 기능은 사람의 피드백을 기다리며 멈추는 Flow에서 가장 중요합니다. Flow는 나중에 다른 머신에서 재개될 수 있고, 그곳에는 멈추기 전에 쓴 파일이 없지만 아티팩트는 남아 있습니다. 재개된 실행은 보고서를 다시 읽고 수정한 뒤 다음 버전으로 저장합니다.
  • load_artifact는 현재 실행에서 읽습니다. 재개된 Flow가 이어 가는 바로 그 실행입니다.
  • 일치하는 아티팩트나 버전이 없으면 ArtifactNotFoundError가 발생합니다.

Identifier와 버전

  • identifier는 [a-z0-9][a-z0-9_.-]{0,63} 형식이어야 합니다. 예: q3-report.
  • 아티팩트는 하나의 실행에 속합니다. Flow 안의 Crew는 Flow의 실행을 공유하므로 모든 아티팩트가 함께 묶입니다.
  • 실행 중에 같은 identifier로 다시 저장하면 다음 버전이 만들어집니다. 피드백을 받은 뒤 보고서를 다시 만드는 human-in-the-loop Flow에 잘 맞습니다.

종류

아티팩트 저장 위치

로컬에서는 다음 위치에 저장됩니다.
url은 file:// URL이고 share_url은 비어 있습니다. CrewAI AMP에서는 플랫폼이 시작할 때 자체 store를 등록하므로, 같은 코드가 아티팩트를 실행에 업로드합니다. Crew 코드는 바꿀 필요가 없습니다.

실패

아티팩트 저장이 실패해도 실행은 실패하지 않습니다.
  • save_artifact 도구는 오류 메시지를 Agent에게 돌려줍니다.
  • Task(artifact=...)와 kickoff(artifact=...)는 경고를 남기고, 실행은 그대로 완료됩니다. file_path의 파일이 없는 경우도 마찬가지입니다.
  • 직접 작성한 코드에서 save_artifact를 호출하면 오류가 발생하므로, 처리 방법을 직접 정할 수 있습니다.

이벤트

저장할 때마다 이벤트 버스에 ArtifactCreatedEvent가 발생합니다. id, identifier, version, title, kind, content_type, size, url을 포함합니다.
이벤트 리스너를 참고하세요.

사용자 정의 store

아티팩트를 다른 곳으로 보내려면 ArtifactStore를 상속하고 kickoff 전에 등록합니다.
store가 업로드를 재시도한다면 매번 같은 artifact_id를 보내야 받는 쪽에서 중복을 걸러낼 수 있습니다. load는 선택 사항입니다. 없으면 load_artifact가 NotImplementedError를 발생시킵니다.