블로그 | 모하지?

원문: Koog Documentation — data-transfer-between-nodes 이 글은 Koog 공식 문서의 data-transfer-between-nodes 페이지를 한국어로 옮긴 번역본입니다. 문서 구조와 링크 의미를 유지하되, MkDocs 전용 UI 문법은 블로그에서 읽기 좋도록 정리했습니다.

개요

Koog는 AIAgentStorage을 사용하여 데이터를 저장하고 전달하는 방법을 제공합니다. 서로 다른 노드 또는 하위 그래프 간에 데이터를 전달하는 유형이 안전한 방법입니다.

스토리지는 에이전트 노드에서 사용 가능한 storage 속성(storage: AIAgentStorage)을 통해 액세스할 수 있습니다. AI 에이전트 시스템의 다양한 구성 요소 전반에 걸쳐 원활한 데이터 공유가 가능합니다.

키 및 값 구조

키-값 데이터 저장 구조는 AIAgentStorageKey 데이터 클래스에 의존합니다. 에 대한 자세한 내용은 AIAgentStorageKey, 아래 섹션을 참조하세요.

AIAgentStorageKey

스토리지는 데이터를 저장하고 검색할 때 유형 안전성을 제공하기 위해 유형화된 키 시스템을 사용합니다.

AIAgentStorageKey<T> 클래스는 데이터를 식별하고 액세스하는 데 사용되는 저장소 키를 나타냅니다. 여기 있습니다 이 수업의 주요 특징:

일반 유형 매개변수 T는 이 키와 연관된 데이터 유형을 지정하여 유형 안전성을 제공합니다.
각 키에는 보다 쉽게 식별하고 디버깅할 수 있는 문자열 식별자인 name 속성이 있습니다.
각 키 인스턴스는 고유합니다. name은 고유성을 결정하는 데 사용되지 않으므로 여러 개를 갖는 것이 허용됩니다. 같은 이름의 키입니다. 이를 통해 다음 위험 없이 기존 전략 구성 요소를 다시 사용할 수 있습니다. 실수로 저장소의 데이터를 덮어썼습니다.

사용 예

다음 섹션에서는 스토리지 키를 생성하고 이를 사용하여 데이터를 저장하고 검색하는 실제 예를 제공합니다.

데이터를 나타내는 클래스 정의

전달하려는 데이터를 저장하는 첫 번째 단계는 데이터를 나타내는 클래스를 만드는 것입니다. 여기에 예가 있습니다. 기본 사용자 데이터가 포함된 간단한 클래스:

코틀린

1class UserData(2   val name: String,3   val age: Int4)

자바

1record UserData(2    String name,3    int age4) {}

정의한 후에는 클래스를 사용하여 아래 설명된 대로 스토리지 키를 생성합니다.

저장소 키 만들기

정의된 데이터 구조에 대해 유형이 지정된 스토리지 키를 생성합니다.

코틀린

1val userDataKey = createStorageKey<UserData>("user-data")

자바

1AIAgentStorageKey<UserData> userDataKey = AIAgentStorage.createStorageKey("user-data");

createStorageKey 함수는 식별 및 디버깅 목적으로 사용되는 단일 문자열 매개변수를 사용합니다.

데이터 저장

생성된 스토리지 키를 사용하여 데이터를 저장하려면 노드에서 storage.set(key: AIAgentStorageKey<T>, value: T) 메서드를 사용합니다.

코틀린

1val nodeSaveData by node<Unit, Unit> {2    storage.set(userDataKey, UserData("John", 26))3}

자바

1var nodeSaveData = AIAgentNode.builder("nodeSaveData")2    .withInput(String.class)3    .withOutput(String.class)4    .withAction((input, ctx) -> {5        ctx.getStorage().set(userDataKey, new UserData("John", 26));6        return "";7    })8    .build();

데이터 검색 중

데이터를 검색하려면 노드에서 storage.get 메서드를 사용합니다.

코틀린

1val nodeRetrieveData by node<String, Unit> { message ->2    storage.get(userDataKey)?.let { userFromStorage ->3        println("Hello dear $userFromStorage, here's a message for you: $message")4    }5}

자바

1var nodeRetrieveData = AIAgentNode.builder("nodeRetrieveData")2    .withInput(String.class)3    .withOutput(String.class)4    .withAction((message, ctx) -> {5        var userData = ctx.getStorage().get(userDataKey);6        System.out.println("Hello dear %s, here's a message for you: %s".formatted(userData, message));7        return "";8    })9    .build();

API 문서

AIAgentStorage 클래스와 관련된 전체 참조는 AIAgentStorage을 참조하세요.

AIAgentStorage 클래스에서 사용 가능한 개별 함수에 대해서는 다음 API 참조를 확인하세요.

추가 정보

AIAgentStorage은 동시 액세스가 올바르게 처리되도록 Mutex를 사용하여 스레드로부터 안전합니다.
값을 검색할 때 유형 캐스팅이 자동으로 처리되어 애플리케이션 전체에서 유형 안전성이 보장됩니다.
Null을 허용하지 않는 값에 액세스하려면 키가 없으면 예외를 발생시키는 getValue 메서드를 사용하세요.
저장된 모든 키-값 쌍을 제거하는 clear 메서드를 사용하여 저장소를 완전히 지울 수 있습니다.