파일 주고받기

API 키만으로 웹앱과 동등하게 파일을 넣고(인바운드) 받을(아웃바운드) 수 있습니다.

파일 넣기 (인바운드)

두 가지 방법 중 하나로 POST /messages의 attachments에 실어 보냅니다. 각 첨부는 origin_url 또는 file_id 중 정확히 하나만 지정하세요(둘 다/둘 다 아님 = 400).

방법 A — 원격 URL 참조 (작은 파일·이미 호스팅된 파일)

-d '{
  "command": "이 문서 요약해줘",
  "attachments": [{ "name": "report.pdf", "mime": "application/pdf",
                    "origin_url": "https://…/report.pdf" }]
}'

서버가 그 URL을 당겨옵니다. 인증 헤더는 전달하지 않으므로 공개 또는 사전서명(presigned) URL이어야 합니다.

방법 B — 업로드 티켓 (대용량 바이너리, 권장 · 최대 50MB)

Vercel 요청 본문 4.5MB 한도를 우회해 Storage에 직접 올린 뒤 file_id로 참조합니다(웹앱과 동일 메커니즘). files:write 스코프가 필요해요.

# 1) 티켓 발급
curl -X POST https://daiops.com/api/v1/workspaces/$WS/files \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"files":[{"name":"report.pdf","size":1048576}]}'
# → { "data": { "uploads": [{ "name":"report.pdf", "file_id":"…", "upload_url":"https://…?token=…" }], "method":"PUT" } }

# 2) 파일 바이트를 upload_url로 직접 PUT
curl -X PUT "<upload_url>" --data-binary @report.pdf -H "x-upsert: true"

# 3) 메시지에서 file_id로 참조
-d '{"command":"이 PDF 요약해줘",
     "attachments":[{"name":"report.pdf","mime":"application/pdf","file_id":"<file_id>"}]}'

한도 & 정책

개별 50MB, 요청당 최대 20개.
확장자는 안전 화이트리스트(코드·문서·이미지 등). 신뢰하는 통합에 files:write:unrestricted를 부여하면 위험 형식만 차단하는 deny-list로 완화됩니다.
처리 못 한 첨부는 조용히 버리지 않고 응답 rejected_attachments:[{name,reason}](비스트리밍) 또는 에이전트 답변으로 통보됩니다.

파일 받기 (아웃바운드)

에이전트가 산출물을 만들면 스트림 완료 직전 attachment 이벤트로 다운로드 URL(7일)이 옵니다. 이것이 파일 발견의 정본입니다(텍스트 스트림의 내부 마커를 파싱하지 마세요).

event: attachment
data: { "v":1, "attachments":[{ "filename":"summary.pdf", "mime":"application/pdf", "size":12345, "download_url":"https://…" }] }

비스트리밍(stream:false) 응답은 같은 정보를 attachments 필드로 줍니다.
download_url을 그대로 GET하면 내려받습니다(추가 인증 불필요 — signed URL).

샌드박스 경로를 이미 알고 온디맨드로 받으려면 (tools:read):

curl -X POST https://daiops.com/api/v1/workspaces/$WS/files/download \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"path":"/workspace/.outputs/summary.pdf"}'
# → { "data": { "download_url":"…", "filename":"summary.pdf", "mime":"…", "size":12345 } }

과거 대화의 산출물을 다시 찾으려면 → 세션 & 대화 이어쓰기

채널별 파일 지원

채널	인바운드	아웃바운드 발견
REST	`origin_url` · `file_id`(업로드 티켓)	`attachment` 이벤트 / 블로킹 `attachments` / 세션 메시지 조회
A2A	FilePart `uri` · `bytes`	FilePart artifact(`file.uri`)
MCP	(인바운드 미지원)	`chat_with_employee` 응답의 `<generated_files>` · `deliver_file` 도구

다음 단계

이전결재 & 시크릿 (HITL)다음 REST (스트리밍)