에이전트는 Microsoft 검색 공유 세션에서 작업을 수행할 때 연구 보고서, 데이터 세트, 구성 파일 또는 계산 결과와 같은 파일을 생성하는 경우가 많습니다. 이러한 파일은 Azure Blob Storage 저장소 자산으로 저장되고 작업 결과의 일부로 추적됩니다. 공유 세션을 통해 파일이 흐르는 방식을 이해하면 유용한 출력을 생성하는 작업을 디자인하고 파일 콘텐츠를 확인하는 유효성 검사 요구 사항을 작성할 수 있습니다. Microsoft 검색 앱은 이러한 파일을 Azure Blob Storage 대신 디스크에 로컬로 저장하지만 여기에 설명된 수명 주기 및 상속 동작은 둘 다에 적용됩니다. Microsoft 검색 및 Microsoft 검색 앱 참조하세요.
에이전트가 파일로 작업하는 방법
에이전트는 Azure Blob Storage 직접 상호 작용하지 않습니다. 대신 플랫폼이 모든 에이전트에 삽입하는 기본 제공 도구 집합을 사용합니다.
| 도구 | Purpose |
|---|---|
| GetResourceContext | 에이전트의 작업 영역에서 사용할 수 있는 모든 파일을 나열합니다. 파일 이름, URI 및 설명을 반환합니다. |
| PreviewResource | 파일의 내용을 읽습니다. 파일을 열어 내부 내용을 확인하는 것처럼 작동합니다. |
| WriteResource | 지정된 콘텐츠 및 파일 이름을 사용하여 새 파일을 만듭니다. |
| ShareResource | 파일을 스토리지 자산으로 승격하여 사용자에게 표시되도록 합니다. |
| UpdateResourceDetails | 기존 파일의 설명 또는 메타데이터를 업데이트합니다. |
에이전트가 WriteResource 호출하면 플랫폼은 Blob Storage에 콘텐츠를 업로드하고, 스토리지 자산(Azure Resource Manager 리소스)을 만들고, 다른 도구에서 찾을 수 있도록 태스크의 데이터 컨텍스트에 파일을 추가합니다. 이 파일은 작업 결과에도 다음과 같이 storageAssetId표시됩니다.
중요합니다
에이전트는 사용자의 ID가 아닌 플랫폼의 관리 ID를 통해 Blob Storage에 액세스합니다. 즉, 관리자가 액세스 권한을 부여하지 않으면 에이전트가 볼 수 없는 파일을 만들 수 있습니다. VS Code에서 출력 파일을 보려면 스토리지 계정에 스토리지 Blob 데이터 판독 기(또는 기여자)가 필요하며 네트워크가 스토리지 엔드포인트에 연결할 수 있어야 합니다. 파일 링크를 클릭할 때 액세스 오류가 표시되면 관리자에게 문의하세요. 필요한 구성은 Microsoft 검색의 Azure Blob Storage 참조하세요.
지원되는 파일 형식
기본 제공 파일 도구는 텍스트 기반 콘텐츠에서만 작동합니다. 에이전트가 파일을 작성하면 콘텐츠가 UTF-8로 인코딩된 텍스트로 저장됩니다. 에이전트가 파일을 읽을 때 콘텐츠는 최대 미리 보기 크기가 30KB인 텍스트로 반환됩니다.
기본적으로 지원되는 형식
이러한 형식의 파일은 WriteResource 를 사용하여 만들고 PreviewResource를 사용하여 읽을 수 있습니다.
- Markdown(
.md) - 일반 텍스트(
.txt) - CSV(
.csv) - JSON(
.json) - Python(
.py) - YAML(
.yaml,.yml) - 확장이 없는 파일
미리 볼 수 없는 형식
PreviewResource는 이진 파일 형식을 차단하고 파일 콘텐츠 대신 오류 메시지를 반환합니다. 차단된 형식은 다음과 같습니다.
- 문서(
.docx,.pdf) - 이미지(
.jpg,.png,.gif) - 오디오/비디오(
.mp3,.mp4) - 아카이브 (
.zip,.tar,.gz) - 과학적 데이터(
.hdf5) - 실행 파일(
.exe)
메모
슈퍼컴퓨터에서 실행되는 사용자 지정 도구를 통해 공유 세션에 이진 파일을 저장할 수 있습니다. 파일은 스토리지 자산으로 존재하며 다운로드할 수 있지만 에이전트는 기본 제공 도구를 사용하여 해당 콘텐츠를 읽을 수 없습니다. 이진 형식으로 작업하려면 고유한 작업을 통해 .docx 파일을 만들고 읽을 수 있는 Word 문서 도구와 같이 형식을 이해하는 사용자 지정 도구를 사용합니다.
스토리지 자산 및 데이터 컨텍스트
두 가지 개념은 Microsoft 검색에서 파일이 작동하는 방식의 핵심입니다.
Storage asset: Blob Storage의 파일을 나타내는 Azure Resource Manager 리소스입니다. 각 스토리지 자산에는 고유한 ID, Blob 콘텐츠에 대한 경로 및 이름 및 설명과 같은 메타데이터가 있습니다. 작업 결과에 표시되는
storageAssetIds경우 스토리지 자산에 대한 참조입니다.데이터 컨텍스트: 가상 파일 URI를 실제 Blob 위치에 매핑하는 대화별 인덱스입니다. 에이전트가 GetResourceContext를 호출하면 데이터 컨텍스트에서 읽어 사용할 수 있는 파일을 검색합니다. 업스트림 또는 부모 작업에서 상속된 파일도 데이터 컨텍스트에 표시되므로 파일이 원래 기록된 위치에 관계없이 GetResourceContext 는 단일 검색 지점입니다.
파일은 discovery:// URI로 지정됩니다. 에이전트는 discovery://resources/my-container/paths/writes/report.md와 같은 URI를 PreviewResource에 전달하여 콘텐츠를 읽습니다. 플랫폼은 이러한 가상 URI에서 실제 Blob Storage 경로로의 변환을 처리합니다.
작업 간에 파일이 이동하는 방법
다중 작업 공유 세션을 디자인할 때 파일 표시 유형을 이해하는 것이 중요합니다. 파일은 두 상속 경로와 태스크의 자체 상태를 통해 다운스트림 작업에 도달합니다.
에이전트에서 볼 수 있는 내용
작업이 시작되면 해당 에이전트에서 다음을 볼 수 있습니다.
- 작업 자체
storageAssetIds에 명시적으로 나열된 파일(태스크를 만들거나 업데이트할 때 설정됨). - 해당 태스크의 이전 실행에서 생성된 파일(
taskResult.storageAssetIds에 저장됨). - 부모 체인 상속. 하위 작업은 부모
storageAssetIds에 연결된 스토리지 자산을 상속합니다. 루트 작업에 연결하는 입력은 모든 하위 작업으로 전이적으로 전달됩니다. - 의존성 그래프 상속.
dependsOn=[A]가 있는 작업은 A의taskResult.StorageAssetIds로부터 출력을 상속받습니다. 상속은 전이적입니다. 즉, A → B → C이면 C는 B와 A의 출력을 모두 볼 수 있습니다. 중복 항목은 중복 제거됩니다.
모든 상속된 파일은 실행 기록에서 inheritedStorageAssets 작업 아래 기록되며, parentStorageAssetCount 및 dependencyStorageAssetCount의 세부 내역이 제공되어 각 파일의 출처를 감사할 수 있습니다.
상속된 파일은 로컬로 작성된 파일과 함께 에이전트의 데이터 컨텍스트에 표시됩니다. 에이전트는 여전히 GetResourceContext 를 호출하여 나열하고 PreviewResource 를 호출하여 콘텐츠를 읽어야 합니다. 파일이 프롬프트에 자동으로 삽입되지 않습니다.
자동으로 전파되지 않는 기능
- 명시적
dependsOn에지가 없는 형제 작업입니다. 종속성을 선언하지 않는 두 형제 작업은, 한쪽이 다른 쪽보다 먼저 끝나더라도 파일 출력물을 공유하지 않습니다. - 세션 간에 공유된 파일 상속은 하나의 공유 세션으로 한정됩니다. 파일은 공유 세션 경계를 넘지 않습니다.
- 프롬프트 콘텐츠입니다. 상속된 파일은 데이터 컨텍스트를 통해 검색할 수 있습니다. 해당 콘텐츠는 에이전트가 PreviewResource를 사용하여 읽을 때만 대화를 입력합니다.
상향 전파 (루트 가시성)
자식 작업이 완료되면 해당 출력 파일도 부모 작업의 taskResult.storageAssetIds로 복사됩니다. 이 전파는 계층 구조를 따라 자식 노드에서 부모, 조부모를 거쳐 최종적으로 루트 작업에까지 이어집니다. 전파 기능을 사용하면 루트 작업이 전체 공유 세션의 모든 출력 파일을 수집하여 모든 아티팩트를 한곳에서 찾을 수 있게 해줍니다.
중요합니다
상향 전파 및 종속성 상속은 두 가지 메커니즘입니다. 상향 전파는 사용자가 출력을 찾을 수 있도록 출력을 루트 작업에 집계합니다. 종속성 및 부모 체인 상속은 업스트림 파일을 다운스트림 에이전트에서 사용할 수 있게 합니다.
실질적인 의미
다음 작업 계층 구조를 고려합니다.
Root Task
├── Task A (produces findings.csv)
├── Task B (produces analysis.md)
├── Task C (dependsOn=[A, B], produces report.md)
└── Task D (no dependsOn, produces notes.md)
- 작업 A의 에이전트는
findings.csv를 작성합니다. 작업 B의 에이전트가 씁니다.analysis.md - 작업 C의 에이전트는 C가 둘 다에 의존하므로 A와 B를 모두 상속받습니다
findings.csvanalysis.md두 파일은 모두 C의 데이터 컨텍스트에 표시되고 C의 에이전트는 PreviewResource를 사용하여 읽을 수 있습니다. - 작업 D에는 A나 B로 가는
dependsOn에지가 없으므로 D의 에이전트는 . 명시적 종속성이 없는 형제는 출력을 공유하지 않습니다. - 모든 작업이 완료되면 루트 태스크는
storageAssetIds상속 에지에 관계없이 위쪽 전파를 통해 모든 출력(findings.csv,analysis.md,report.md,notes.md)을 포함합니다.
작업 결과 텍스트에 주요 결과를 포함하는 것은 여전히 좋은 방법입니다. 인식은 다운스트림 작업에 대한 컨텍스트를 작성할 때 해당 텍스트를 사용하며 에이전트가 상속된 모든 파일을 열지 않더라도 결론을 내립니다. 그러나 더 이상 정보를 공유하는 유일한 방법은 아닙니다. dependsOn 는 파일을 전파하기 위해 지원되는 메커니즘입니다.
검색 엔진이 파일 출력의 유효성을 검사하는 방법
인식이 완료된 작업의 유효성을 검사하는 경우 유효성 검사 프로세스의 일부로 파일 출력을 검사할 수 있습니다. 유효성 검사 에이전트는 태스크의 스토리지 자산을 수신하고 동일한 기본 제공 도구(GetResourceContext 및 PreviewResource)를 사용하여 유효성 검사 요구 사항에 따라 파일 콘텐츠를 읽고 평가합니다.
사용할 도구가 아니라 파일에 포함해야 하는 항목을 설명하는 유효성 검사 요구 사항을 작성합니다.
유효한 유효성 검사 요구 사항:
- "출력 파일을 읽고 5개 이상의 데이터 행이 포함되어 있는지 확인합니다."
- "보고서에 방법론 섹션 및 결론이 포함되어 있는지 확인합니다."
- "JSON 출력에 유효한 분자 가중치 값이 포함되어 있는지 확인합니다."
덜 효과적인 유효성 검사 요구 사항:
- "파일이 생성되었는지 확인"(너무 모호하고 콘텐츠를 확인하지 않음)
- "storageAssetId가 비어 있지 않은지 확인"(콘텐츠가 아닌 메타데이터 확인)
메모
유효성 검사는 텍스트 기반 파일만 검사할 수 있습니다. 태스크에서 이진 파일(예: .docx 사용자 지정 도구)을 생성하는 경우 유효성 검사 에이전트는 파일이 스토리지 자산으로 존재하는지 확인할 수 있지만 해당 콘텐츠를 읽을 수 없습니다. 이진 출력의 경우 파일 콘텐츠 확인이 아닌 작업 결과 텍스트에서 에이전트가 보고한 내용에 초점을 맞춘 유효성 검사 요구 사항을 작성합니다.
사용자 지정 도구를 통해 이진 파일 작업
기본 제공 도구에서 지원하지 않는 파일 형식의 경우 슈퍼컴퓨터에서 실행되는 사용자 지정 도구를 만들 수 있습니다. 사용자 지정 도구는 내부적으로 이진 형식을 처리하고 에이전트가 호출할 수 있는 작업을 노출합니다.
현재 제한 사항
| Limitation | 설명 |
|---|---|
| Discovery Studio에서 파일 업로드 없음 | 기존 데이터 자산을 작업 및 공유 세션에 연결할 수 있지만 Studio 인터페이스를 통해 로컬 컴퓨터에서 파일을 업로드할 수는 없습니다. |
| 형제 작업은 파일을 자동으로 공유하지 않습니다. | 상속은 작업 계층 구조와 그래프를 dependsOn 따릅니다. 명시적 dependsOn 에지가 없는 형제 작업은 서로의 출력을 볼 수 없으며 파일은 공유 세션 경계를 넘지 않습니다. |
| 텍스트 전용 네이티브 도구 | 기본 제공 파일 도구는 텍스트 콘텐츠에서만 작동합니다. 이진 파일에는 슈퍼 컴퓨터의 사용자 지정 도구가 필요합니다. |
| 30KB 미리 보기 제한 | PreviewResource는 파일의 처음 30KB를 반환합니다. 큰 파일은 잘립니다. |
| 계획하는 동안 파일 콘텐츠 인식 없음 | 검색 엔진은 작업 유효성 검사 중에 파일을 평가하지만 작업을 계획하거나 분해할 때는 파일 내용을 검사하지 않습니다. |