많은 AI 애플리케이션은 자연어를 통해 사용자와 상호작용합니다. 그러나 일부 사용 사례에서는 모델이 구조화된 입력을 사용하여 API, 데이터베이스 또는 파일 시스템과 같은 외부 시스템과 직접 인터페이스해야 합니다.Tools는 agents가 작업을 수행하기 위해 호출하는 컴포넌트입니다. 잘 정의된 입력과 출력을 통해 모델이 세상과 상호작용할 수 있도록 하여 모델의 기능을 확장합니다. Tools는 호출 가능한 함수와 그 입력 스키마를 캡슐화합니다. 이들은 호환되는 chat models에 전달될 수 있으며, 모델이 tool을 호출할지 여부와 어떤 인수로 호출할지 결정할 수 있게 합니다. 이러한 시나리오에서 tool calling은 모델이 지정된 입력 스키마에 부합하는 요청을 생성할 수 있도록 합니다.
tool을 생성하는 가장 간단한 방법은 @tool decorator를 사용하는 것입니다. 기본적으로 함수의 docstring이 tool의 설명이 되어 모델이 언제 사용할지 이해하는 데 도움이 됩니다:
Copy
from langchain.tools import tool@tooldef search_database(query: str, limit: int = 10) -> str: """Search the customer database for records matching the query. Args: query: Search terms to look for limit: Maximum number of results to return """ return f"Found {limit} results for '{query}'"
Type hints는 tool의 입력 스키마를 정의하므로 필수입니다. docstring은 모델이 tool의 목적을 이해하는 데 도움이 되도록 유익하고 간결해야 합니다.
@tool("calculator", description="Performs arithmetic calculations. Use this for any math problems.")def calc(expression: str) -> str: """Evaluate mathematical expressions.""" return str(eval(expression))
Accessing state:Tools는 ToolRuntime을 사용하여 현재 graph state에 액세스할 수 있습니다:
Copy
from langchain.tools import tool, ToolRuntime# Access the current conversation state@tooldef summarize_conversation( runtime: ToolRuntime) -> str: """Summarize the conversation so far.""" messages = runtime.state["messages"] human_msgs = sum(1 for m in messages if m.__class__.__name__ == "HumanMessage") ai_msgs = sum(1 for m in messages if m.__class__.__name__ == "AIMessage") tool_msgs = sum(1 for m in messages if m.__class__.__name__ == "ToolMessage") return f"Conversation has {human_msgs} user messages, {ai_msgs} AI responses, and {tool_msgs} tool results"# Access custom state fields@tooldef get_user_preference( pref_name: str, runtime: ToolRuntime # ToolRuntime parameter is not visible to the model) -> str: """Get a user preference value.""" preferences = runtime.state.get("user_preferences", {}) return preferences.get(pref_name, "Not set")
tool_runtime 매개변수는 모델에서 숨겨집니다. 위의 예제에서 모델은 tool 스키마에서 pref_name만 볼 수 있으며 - tool_runtime은 요청에 포함되지 않습니다.
Updating state:Command를 사용하여 agent의 state를 업데이트하거나 graph의 실행 흐름을 제어하세요:
Copy
from langgraph.types import Commandfrom langchain.messages import RemoveMessagefrom langgraph.graph.message import REMOVE_ALL_MESSAGESfrom langchain.tools import tool, ToolRuntime# Update the conversation history by removing all messages@tooldef clear_conversation() -> Command: """Clear the conversation history.""" return Command( update={ "messages": [RemoveMessage(id=REMOVE_ALL_MESSAGES)], } )# Update the user_name in the agent state@tooldef update_user_name( new_name: str, runtime: ToolRuntime) -> Command: """Update the user's name.""" return Command(update={"user_name": new_name})
store를 사용하여 대화 전반에 걸쳐 영구 데이터에 액세스하세요. store는 runtime.store를 통해 액세스되며 사용자별 또는 애플리케이션별 데이터를 저장하고 검색할 수 있습니다.Tools는 ToolRuntime을 통해 store에 액세스하고 업데이트할 수 있습니다:
Copy
from typing import Anyfrom langgraph.store.memory import InMemoryStorefrom langchain.agents import create_agentfrom langchain.tools import tool, ToolRuntime# Access memory@tooldef get_user_info(user_id: str, runtime: ToolRuntime) -> str: """Look up user info.""" store = runtime.store user_info = store.get(("users",), user_id) return str(user_info.value) if user_info else "Unknown user"# Update memory@tooldef save_user_info(user_id: str, user_info: dict[str, Any], runtime: ToolRuntime) -> str: """Save user info.""" store = runtime.store store.put(("users",), user_id, user_info) return "Successfully saved user info."store = InMemoryStore()agent = create_agent( model, tools=[get_user_info, save_user_info], store=store)# First session: save user infoagent.invoke({ "messages": [{"role": "user", "content": "Save the following user: userid: abc123, name: Foo, age: 25, email: [email protected]"}]})# Second session: get user infoagent.invoke({ "messages": [{"role": "user", "content": "Get user info for user with id 'abc123'"}]})# Here is the user info for user with ID "abc123":# - Name: Foo# - Age: 25# - Email: [email protected]
runtime.stream_writer를 사용하여 tools가 실행될 때 사용자 정의 업데이트를 스트리밍하세요. 이는 tool이 수행하는 작업에 대한 실시간 피드백을 사용자에게 제공하는 데 유용합니다.
Copy
from langchain.tools import tool, ToolRuntime@tooldef get_weather(city: str, runtime: ToolRuntime) -> str: """Get weather for a given city.""" writer = runtime.stream_writer # Stream custom updates as the tool executes writer(f"Looking up data for city: {city}") writer(f"Acquired data for city: {city}") return f"It's always sunny in {city}!"
tool 내부에서 runtime.stream_writer를 사용하는 경우, tool은 LangGraph 실행 컨텍스트 내에서 호출되어야 합니다. 자세한 내용은 Streaming을 참조하세요.