어시스턴트 관리하기

이 페이지에서는 어시스턴트를 만들고, 구성하고, 관리하는 방법을 설명해요. 어시스턴트를 사용하면 기본 그래프 코드를 바꾸지 않고도 배포된 그래프의 동작을 모델 선택, 프롬프트, 도구 사용 가능 여부 같은 설정을 통해 커스터마이즈할 수 있어요.

SDK를 쓰거나 LangSmith UI에서 작업할 수 있어요.

출처: 문서

본문

어시스턴트 구성 이해하기

어시스턴트는 런타임에서 그래프 동작을 커스터마이즈하는 컨텍스트 값을 저장해요. 그래프 코드에 컨텍스트 스키마를 정의하고, 어시스턴트를 만들 때 context 파라미터를 통해 구체적인 컨텍스트 값을 제공하게 돼요.

컨텍스트에서 model_name을 읽어오는 call_model 노드의 예시를 살펴봐요:

class ContextSchema(TypedDict):
    model_name: str

builder = StateGraph(AgentState, context_schema=ContextSchema)

def call_model(state, runtime: Runtime[ContextSchema]):
    messages = state["messages"]
    model = _get_model(runtime.context.get("model_name", "anthropic"))
    response = model.invoke(messages)
    return {"messages": [response]}

import { Annotation } from "@langchain/langgraph";

const ContextSchema = Annotation.Root({
    model_name: Annotation<string>,
    system_prompt: Annotation<string>,
});

const builder = new StateGraph(AgentState, ContextSchema)

function callModel(state: State, runtime: Runtime[ContextSchema]) {
  const messages = state.messages;
  const model = _getModel(runtime.context.model_name ?? "anthropic");
  const response = model.invoke(messages);
  return { messages: [response] };
}

어시스턴트를 만들 때 이러한 구성 필드에 구체적인 값을 제공해요. 어시스턴트는 이 구성을 저장하고, 그래프가 실행될 때마다 그 구성을 적용해요.

LangGraph에서의 구성에 대한 자세한 내용은 러닝타임 컨텍스트 문서를 참고해요.

워크플로에 맞게 SDK 또는 UI를 선택하세요:

SDK 사용하기

어시스턴트 만들기

assistants.create 메서드를 사용해서 새 어시스턴트를 만들어요. 이 메서드에는 다음이 필요해요:

그래프 ID: 이 어시스턴트가 사용할 배포된 그래프의 이름입니다 (예: "agent").
컨텍스트: 그래프의 컨텍스트 스키마와 일치하는 구성 값입니다.
이름: 어시스턴트를 설명하는 이름입니다.

다음 예시는 model_name을 openai로 설정한 어시스턴트를 만들어요:

from langgraph_sdk import get_client

# Initialize the client with your deployment URL
client = get_client(url=<DEPLOYMENT_URL>)

# Create an assistant for the "agent" graph
# The first parameter is the graph ID (also called graph name)
openai_assistant = await client.assistants.create(
    "agent",  # Graph ID of the deployed graph
    context={"model_name": "openai"},
    name="Open AI Assistant"
)

print(openai_assistant)
# Output includes the assistant_id (UUID) that uniquely identifies this assistant

import { Client } from "@langchain/langgraph-sdk";

// Initialize the client with your deployment URL
const client = new Client({ apiUrl: <DEPLOYMENT_URL> });

// Create an assistant for the "agent" graph
const openAIAssistant = await client.assistants.create({
    graphId: 'agent',  // Graph ID of the deployed graph
    name: "Open AI Assistant",
    context: { "model_name": "openai" },
});

console.log(openAIAssistant);
// Output includes the assistant_id (UUID) that uniquely identifies this assistant

curl --request POST \
    --url <DEPLOYMENT_URL>/assistants \
    --header 'Content-Type: application/json' \
    --data '{"graph_id":"agent", "context":{"model_name":"openai"}, "name": "Open AI Assistant"}'

응답:

API는 다음을 포함하는 어시스턴트 객체를 반환해요:

assistant_id: 이 어시스턴트를 고유하게 식별하는 UUID
graph_id: 이 어시스턴트가 구성된 그래프
context: 제공한 구성 값
name, metadata, 타임스탬프 및 기타 필드

{
  "assistant_id": "62e209ca-9154-432a-b9e9-2d75c7a9219b",
  "graph_id": "agent",
  "name": "Open AI Assistant",
  "context": {
    "model_name": "openai"
  },
  "metadata": {},
  "created_at": "2024-08-31T03:09:10.230718+00:00",
  "updated_at": "2024-08-31T03:09:10.230718+00:00"
}

assistant_id(예: "62e209ca-9154-432a-b9e9-2d75c7a9219b" 같은 UUID)는 이 어시스턴트 구성을 고유하게 식별해요. 그래프를 실행해 어떤 구성을 적용할지 지정할 때 이 ID를 사용하게 돼요.

그래프 ID와 어시스턴트 ID

어시스턴트를 만들 때 그래프 ID("agent" 같은 그래프 이름)를 지정해요. 그러면 어시스턴트 ID("62e209ca..." 같은 UUID)가 반환돼요. 그래프를 실행할 때 둘 중 하나를 사용할 수 있어요:

그래프 ID(예: "agent"): 해당 그래프의 기본 어시스턴트를 사용합니다

어시스턴트 ID(UUID): 특정 어시스턴트 구성을 사용합니다

예시는 어시스턴트 사용하기를 참고해요.

어시스턴트 사용하기

어시스턴트를 사용하려면 런을 만들 때 그 assistant_id를 전달해요. 아래 예시는 위에서 만든 어시스턴트를 사용해요:

# Create a thread for the conversation
thread = await client.threads.create()

# Prepare the input
input = {"messages": [{"role": "user", "content": "who made you?"}]}

# Run the graph using the assistant's configuration
# Pass the assistant_id (UUID) as the second parameter
async for event in client.runs.stream(
    thread["thread_id"],
    openai_assistant["assistant_id"],  # Assistant ID (UUID)
    input=input,
    stream_mode="updates",
):
    print(f"Receiving event of type: {event.event}")
    print(event.data)
    print("\n\n")

// Create a thread for the conversation
const thread = await client.threads.create();

// Prepare the input
const input = { "messages": [{ "role": "user", "content": "who made you?" }] };

// Run the graph using the assistant's configuration
// Pass the assistant_id (UUID) as the second parameter
const streamResponse = client.runs.stream(
  thread["thread_id"],
  openAIAssistant["assistant_id"],  // Assistant ID (UUID)
  {
    input,
    streamMode: "updates"
  }
);

for await (const event of streamResponse) {
  console.log(`Receiving event of type: ${event.event}`);
  console.log(event.data);
  console.log("\n\n");
}

# First, create a thread
thread_id=$(curl --request POST \
    --url <DEPLOYMENT_URL>/threads \
    --header 'Content-Type: application/json' \
    --data '{}' | jq -r '.thread_id')

# Run the graph with the assistant ID (UUID)
curl --request POST \
    --url "<DEPLOYMENT_URL>/threads/${thread_id}/runs/stream" \
    --header 'Content-Type: application/json' \
    --data '{
        "assistant_id": "<ASSISTANT_ID>",
        "input": {
            "messages": [
                {
                    "role": "user",
                    "content": "who made you?"
                }
            ]
        },
        "stream_mode": ["updates"]
    }' | \
    sed 's/\r$//' | \
    awk '
    /^event:/ {
        if (data_content != "") {
            print data_content "\n"
        }
        sub(/^event: /, "Receiving event of type: ", $0)
        printf "%s...\n", $0
        data_content = ""
    }
    /^data:/ {
        sub(/^data: /, "", $0)
        data_content = $0
    }
    END {
        if (data_content != "") {
            print data_content "\n\n"
        }
    }
'

응답:

스트림은 그래프가 어시스턴트 구성으로 실행되면서 이벤트를 반환해요:

Receiving event of type: metadata
{'run_id': '1ef6746e-5893-67b1-978a-0f1cd4060e16'}

Receiving event of type: updates
{'agent': {'messages': [{'content': 'I was created by OpenAI...', ...}]}}

그래프 ID vs 어시스턴트 ID 사용하기

그래프를 실행할 때 그래프 ID 또는 어시스턴트 ID를 전달할 수 있어요:
# Option 1: Use graph ID to get the default assistant
client.runs.stream(thread_id, "agent", input=input)

# Option 2: Use assistant ID (UUID) for a specific configuration
client.runs.stream(thread_id, "62e209ca-9154-432a-b9e9-2d75c7a9219b", input=input)

어시스턴트의 새 버전 만들기

assistants.update 메서드를 사용해서 어시스턴트의 새 버전을 만들어요.

업데이트에는 전체 구성이 필요해요

업데이트할 때는 전체 구성을 제공해야 해요. 업데이트 엔드포인트는 이전 버전과 병합하지 않고 처음부터 새 버전을 만들어요. 유지하려는 모든 구성 필드를 포함하세요.

예를 들어 어시스턴트에 시스템 프롬프트를 추가하려면:

# Update the assistant with a new configuration
# IMPORTANT: Include ALL configuration fields, not just the ones you're changing
openai_assistant_v2 = await client.assistants.update(
    openai_assistant["assistant_id"],  # Assistant ID (UUID)
    context={
          "model_name": "openai",  # Must include existing fields
          "system_prompt": "You are a mindful assistant!",  # New field
    },
)

# This creates version 2 and sets it as the active version
# Future runs using this assistant_id will use version 2

// Update the assistant with a new configuration
// IMPORTANT: Include ALL configuration fields, not just the ones you're changing
const openaiAssistantV2 = await client.assistants.update(
    openAIAssistant["assistant_id"],  // Assistant ID (UUID)
    {
        context: {
            model_name: 'openai',  // Must include existing fields
            system_prompt: 'You are a mindful assistant!',  // New field
        },
    },
);

// This creates version 2 and sets it as the active version
// Future runs using this assistant_id will use version 2

curl --request PATCH \
--url <DEPLOYMENT_URL>/assistants/<ASSISTANT_ID> \
--header 'Content-Type: application/json' \
--data '{
"context": {"model_name": "openai", "system_prompt": "You are a mindful assistant!"}
}'

업데이트는 새 버전을 만들고 자동으로 활성 버전으로 설정해요. 이제부터 이 어시스턴트 ID를 사용하는 모든 런은 새 구성을 사용하게 돼요.

이전 어시스턴트 버전 사용하기

어떤 버전을 활성화할지 바꾸려면 setLatest 메서드를 사용해요:

# Roll back to version 1 of the assistant
await client.assistants.set_latest(
    openai_assistant['assistant_id'],  # Assistant ID (UUID)
    1  # Version number
)

# All future runs using this assistant_id will now use version 1

// Roll back to version 1 of the assistant
await client.assistants.setLatest(
    openaiAssistant['assistant_id'],  // Assistant ID (UUID)
    1  // Version number
);

// All future runs using this assistant_id will now use version 1

curl --request POST \
--url <DEPLOYMENT_URL>/assistants/<ASSISTANT_ID>/latest \
--header 'Content-Type: application/json' \
--data '{
"version": 1
}'

활성 버전을 변경한 후에는 이 어시스턴트 ID를 사용하는 모든 런이 지정된 버전의 구성을 사용해요.

UI 사용하기

어시스턴트 만들기

LangSmith UI에서 어시스턴트를 만들 수 있어요:

배포로 이동한 뒤 Assistants 탭을 선택하세요.
+ New assistant를 클릭하세요.
열리는 양식에서:
- 이 어시스턴트가 대상으로 하는 그래프를 선택하세요.
- 이름과 설명을 입력하세요.
- 해당 그래프의 구성 스키마를 사용해서 어시스턴트를 구성하세요.
Create assistant를 클릭하세요.

그러면 스튜디오로 이동해서 어시스턴트를 테스트할 수 있어요. Assistants 탭으로 돌아가면 테이블에 새로 만든 어시스턴트가 보여요.

어시스턴트 사용하기

LangSmith UI에서 어시스턴트를 사용하려면:

배포로 이동한 뒤 Assistants 탭을 선택하세요.
사용할 어시스턴트를 찾으세요.
해당 어시스턴트의 Studio를 클릭하세요.

선택한 어시스턴트로 스튜디오가 열려요. 입력을 제출하면(Graph 또는 Chat 모드), 어시스턴트의 구성이 런에 적용돼요.

어시스턴트의 새 버전 만들기

UI에서 어시스턴트를 업데이트하고 새 버전을 만들려면 Assistants 탭이나 Studio를 사용할 수 있어요. 어느 방법이든 새 버전을 만들고 활성 버전으로 설정해요:

Assistants 탭:

배포로 이동한 뒤 Assistants 탭을 선택하세요.
편집할 어시스턴트를 찾으세요.
Edit를 클릭하세요.
어시스턴트의 이름, 설명 또는 구성을 수정하세요.
변경 사항을 저장하세요.

Studio:

어시스턴트의 Studio를 여세요.
Manage Assistants를 클릭하세요.
어시스턴트의 구성을 편집하세요.
변경 사항을 저장하세요.

이전 어시스턴트 버전 사용하기

Studio에서 이전 버전을 활성으로 설정하려면:

어시스턴트의 Studio를 여세요.
Manage Assistants를 클릭하세요.
어시스턴트를 찾아 사용할 버전을 선택하세요.
해당 버전의 Active 토글을 켜세요.

이렇게 하면 앞으로 모든 런에서 선택한 버전을 사용하도록 어시스턴트가 업데이트돼요.

어시스턴트를 삭제하면 해당 어시스턴트의 모든 버전이 삭제돼요. 현재 단일 버전만 삭제하는 방법은 없어요. 버전을 건너뛰려면 다른 버전을 활성으로 설정하면 돼요.

어시스턴트 관리하기