LangGraph

本ガイドでは、セットアップから実践的なユースケースまで、LangGraph と SambaNova を連携させる手順を解説します。LangGraph は、ステートフルで長時間実行されるワークフローやエージェントを構築するための低レベルの基盤フレームワークです。

前提条件

作業を始める前に、以下の環境を準備してください。

有効な API キーを取得済みの SambaCloud アカウント
Python 3.10 以上がインストールされていること。langgraph と langchain-sambanova は Python 3.9 以前をサポートしていません。
グラフからツールを呼び出す場合は、Function calling (関数呼び出し) に対応したモデル。本ページの例では、Function calling に対応した Meta-Llama-3.3-70B-Instruct を使用します。対応モデルの一覧は Function calling と JSON モードをご参照ください。Function calling 非対応のモデルでツール呼び出しグラフを実行すると、モデルはツール呼び出しを一切発行しないため、グラフは通常のテキスト応答を返し、ツールノードは完全にスキップされます。

macOS には Python 3.9 が標準搭載されており、python ではなく python3 として提供されます。python3 --version でバージョンを確認してください。3.10 未満の場合は、pyenv、uv、または brew install python@3.12 で対応バージョンをインストールしてから先へ進んでください。

インストールとセットアップ

仮想環境を作成します。

python3 -m venv .venv
source .venv/bin/activate
python --version

必要なライブラリをインストールします。

pip install langchain-sambanova langchain langgraph

API キーを設定します。

export SAMBANOVA_API_KEY="your-api-key"

各パッケージは、本ページの例のそれぞれ異なる部分を担っています。

パッケージ	提供内容
`langchain-sambanova`	SambaCloud と通信するチャットモデル `ChatSambaNova`
`langgraph`	`StateGraph`、`MessagesState`、およびグラフの始点・終点を示す `START` と `END`。あわせて、`ToolNode` と `tools_condition` を提供する `langgraph-prebuilt`、`InMemorySaver` を提供する `langgraph-checkpoint` もインストールされます。
`langchain`	`@tool` デコレーターなどの `langchain-core` プリミティブに加え、手組みのグラフではなく事前構築済みエージェントを使いたくなった場合の `langchain.agents.create_agent`

本ページの例は、langchain-sambanova 1.1.1、langgraph 1.2.10、langchain 1.3.14 で動作確認済みです。まったく同じ組み合わせを再現するには、pip install langchain-sambanova==1.1.1 langchain==1.3.14 langgraph==1.2.10 でバージョンを固定してください。

クイックスタート

SambaCloud のチャットモデルをインスタンス化し、最初のメッセージを送信します。

from langchain_sambanova import ChatSambaNova

llm = ChatSambaNova(model="Meta-Llama-3.3-70B-Instruct")
response = llm.invoke([("human", "Hello!")])
print(response.content)

以下のような出力が表示されます。

Hello. How can I help you today?

ChatSambaNova は環境変数 SAMBANOVA_API_KEY からキーを読み取ります。invoke は AIMessage を返すため、response.content が応答テキストになります。応答が表示されれば、モデルをグラフに組み込む準備は完了です。

グラフの構築

モデルを単一ノードのグラフに追加します。MessagesState スキーマは add_messages リデューサーを使用するため、各ノードの戻り値は会話を置き換えるのではなく、会話に追記されます。

from langchain_sambanova import ChatSambaNova
from langgraph.graph import END, START, MessagesState, StateGraph

llm = ChatSambaNova(model="Meta-Llama-3.3-70B-Instruct")


def chat(state: MessagesState) -> MessagesState:
    return {"messages": [llm.invoke(state["messages"])]}


builder = StateGraph(MessagesState)
builder.add_node("chat", chat)
builder.add_edge(START, "chat")
builder.add_edge("chat", END)
graph = builder.compile()

result = graph.invoke({"messages": [("human", "Hello!")]})
print(result["messages"][-1].content)

以下のような出力が表示されます。

Hello. How can I help you today?

graph.invoke は単一の応答ではなく、最終状態を返します。MessagesState は蓄積型のため、result["messages"] には会話全体が格納されます。先頭が入力で、末尾がモデルの AIMessage です。この例で result.content ではなく result["messages"][-1].content を読み取っているのはそのためです。代わりに状態全体を出力すると、参照しているデータの形を確認できます。

{'messages': [HumanMessage(content='Hello!', ...), AIMessage(content='Hello. How can I help you today?', ...)]}

ツールと条件付きエッジの追加

ノードが 1 つだけでは、まだエージェントとは言えません。ツールを呼び出すかどうかをモデルに判断させるには、ツールをモデルにバインドし、ツールを実行する ToolNode を追加し、条件付きエッジで両者の間をルーティングします。tools_condition は最後のメッセージを検査し、ツール呼び出しが含まれていれば "tools" を返し、含まれていなければグラフを終了します。tools から model へ戻るエッジがループを構成するため、モデルは各ツールの結果を確認したうえで、別のツールを呼び出すか応答を返すかを選択できます。

from langchain_core.tools import tool
from langchain_sambanova import ChatSambaNova
from langgraph.graph import START, MessagesState, StateGraph
from langgraph.prebuilt import ToolNode, tools_condition


@tool
def get_exchange_rate(base: str, quote: str) -> str:
    """Return the exchange rate from one currency code to another."""
    rates = {("USD", "EUR"): 0.92, ("USD", "JPY"): 157.0}
    rate = rates.get((base.upper(), quote.upper()))
    if rate is None:
        return f"No rate available for {base} to {quote}."
    return f"1 {base.upper()} = {rate} {quote.upper()}"


tools = [get_exchange_rate]
llm = ChatSambaNova(model="Meta-Llama-3.3-70B-Instruct").bind_tools(tools)


def call_model(state: MessagesState) -> MessagesState:
    return {"messages": [llm.invoke(state["messages"])]}


builder = StateGraph(MessagesState)
builder.add_node("model", call_model)
builder.add_node("tools", ToolNode(tools))
builder.add_edge(START, "model")
builder.add_conditional_edges("model", tools_condition)
builder.add_edge("tools", "model")
graph = builder.compile()

result = graph.invoke({"messages": [("human", "How many euros is 100 US dollars?")]})
for message in result["messages"]:
    message.pretty_print()

上記の get_exchange_rate ツールは、2 つ目の API キーなしで例を実行できるよう、ハードコードされたレートを返します。数値を実際に利用する場合は、実際のレート API に置き換えてください。

各メッセージに対する pretty_print は、ループが実際に実行されたことを確認する最も手軽な方法です。質問、モデルのツール呼び出し、ツールの結果、最終的な応答の 4 つのメッセージが表示されるはずです。

================================ Human Message =================================

How many euros is 100 US dollars?
================================== Ai Message ==================================
Tool Calls:
  get_exchange_rate (call_abc123)
 Call ID: call_abc123
  Args:
    base: USD
    quote: EUR
================================= Tool Message =================================
Name: get_exchange_rate

1 USD = 0.92 EUR
================================== Ai Message ==================================

100 US dollars is about 92 euros.

メッセージが 2 つ (質問とテキスト応答) しか表示されない場合、モデルはツール呼び出しを発行していません。モデルが Function calling に対応していることを確認し、ツールをいつ使うべきかが明確に伝わるように docstring を記述してください。

このグラフを必ずしも手作業で構築する必要はありません。from langchain.agents import create_agent を使えば、同等のコンパイル済み ReAct エージェントを 1 回の呼び出しで取得できます。独自のノード、カスタムルーティング、状態フィールドを追加する必要がある場合に、グラフを自分で構築してください。

ターンをまたいだ状態の永続化

graph.invoke の各呼び出しは毎回新しい状態から始まるため、上のグラフは何も記憶できません。会話を維持するには、チェックポインターを指定してコンパイルし、thread_id を渡します。チェックポインターはスレッドごとに状態を保存し、thread_id でどの会話を継続するかを選択します。

from langchain_sambanova import ChatSambaNova
from langgraph.checkpoint.memory import InMemorySaver
from langgraph.graph import END, START, MessagesState, StateGraph

llm = ChatSambaNova(model="Meta-Llama-3.3-70B-Instruct")


def chat(state: MessagesState) -> MessagesState:
    return {"messages": [llm.invoke(state["messages"])]}


builder = StateGraph(MessagesState)
builder.add_node("chat", chat)
builder.add_edge(START, "chat")
builder.add_edge("chat", END)
graph = builder.compile(checkpointer=InMemorySaver())

config = {"configurable": {"thread_id": "conversation-1"}}
graph.invoke({"messages": [("human", "My name is Ada.")]}, config)
result = graph.invoke({"messages": [("human", "What is my name?")]}, config)
print(result["messages"][-1].content)

以下のような出力が表示されます。

Your name is Ada.

2 回目の呼び出しで送信しているのは新しい質問だけですが、チェックポインターが conversation-1 の保存済みメッセージを復元するため、モデルは最初のターンの内容を保持しています。thread_id を新しい値に変更すると、モデルは名前を知らない状態に戻ります。

InMemorySaver は状態をプロセス内に保持し、終了時に失われます。これはローカル開発に適した挙動です。MemorySaver は同じクラスの後方互換エイリアスです。デプロイする用途では、langgraph-checkpoint-postgres の PostgresSaver など、永続化されるチェックポインターを使用してください。

ユースケースの例

LangGraph を SambaCloud と組み合わせて使用することで、Web 検索、検索拡張生成 (RAG)、SQL エージェントなどのマルチエージェントワークフローを構築できます。以下は、これらのパターンをそのまま実行できる完全な実装例です。

Agentic Search: Web 検索ツールと SambaCloud のモデルを組み合わせたチャットボットを構築するノートブックです。
Agentic Graph RAG: ノートブックではなく完全なアプリケーションで、インテリジェントなルーティングと生成された Cypher クエリを使用して、医療系グラフデータベースに対する自然言語の質問に回答します。LangGraph と FastAPI で構築され、Web インターフェースを備えています。

トラブルシューティング

command not found: python

macOS には python 実行ファイルが用意されておらず、python3 のみが提供されます。仮想環境の作成には python3 -m venv .venv を使用してください。source .venv/bin/activate で有効化した後は、環境内で python が期待どおりに動作します。

sambanova.SambaNovaError: The api_key client option must be set

ChatSambaNova はオブジェクトの構築時に HTTP クライアントを作成するため、SAMBANOVA_API_KEY が未設定の場合、リクエストが送信される前の ChatSambaNova(...) の行で失敗します。echo $SAMBANOVA_API_KEY で、キーがプロセスから参照できることを確認してください。export は実行したシェルにのみ適用されるため、新しいターミナルや新しいエディタセッションでは再度設定が必要です。

sambanova.AuthenticationError: Error code: 401 - Incorrect API key provided

キーは設定されていますが、有効ではありません。SambaCloud ポータルからもう一度コピーしてください。

ModuleNotFoundError: No module named 'langgraph' or 'langchain_sambanova'

仮想環境が有効になっていません。source .venv/bin/activate を再度実行し、プロンプトに (.venv) が表示されることを確認してから、ステップ 2 のインストールコマンドを再実行してください。

モデルを指定していないのにモデルのエラーが発生する

model= を省略すると、ChatSambaNova は自身のデフォルトである Llama-4-Maverick-17B-128E-Instruct にフォールバックします。このモデルは SambaCloud では提供終了となりすでに提供されていないため、別のモデルで気付かないうちに実行されるのではなく、リクエストが失敗します。常に model= を明示的に指定し、SambaCloud モデルに記載の ID を使用してください。

ChatSambaNovaCloud が動作しない

古いチュートリアルでは ChatSambaNovaCloud をインポートしています。langchain-sambanova 1.x では、この名前は実装を持たない非推奨 (deprecated) のプレースホルダです。クラスには @deprecated(since="0.2.0", removal="1.0.0") が付与され、本体は空になっています。ChatSambaNova を使用してください。SambaCloud と SambaStack の両方に対応し、base_url からどちらに接続するかを選択します。

AttributeError: 'dict' object has no attribute 'content'

グラフの結果に対して .content を呼び出しています。graph.invoke が返すのはメッセージではなく状態のディクショナリなので、まず result["messages"][-1].content のように状態から最後のメッセージを取り出してください。.content を直接読み取れる AIMessage を返すのは llm.invoke だけです。

ValueError: Checkpointer requires one or more of the following 'configurable' keys: thread_id, checkpoint_ns, checkpoint_id

チェックポインター付きでグラフをコンパイルしたにもかかわらず、config なしで呼び出しています。チェックポインターはどの会話を読み込むかを知る必要があるため、毎回の呼び出しで thread_id を渡してください: graph.invoke(payload, {"configurable": {"thread_id": "conversation-1"}})。会話を継続するには同じ値を再利用し、新しい会話を始めるには新しい値を使用します。

langgraph.errors.GraphRecursionError: Recursion limit of 25 reached

グラフが END に到達せずループし続けています。ツール呼び出しグラフでは通常、モデルがツールを呼び出し、結果に満足できず、再度呼び出すことが原因です。message.pretty_print() でメッセージを出力し、何が繰り返されているかを確認してください。例外を送出するのではなく、利用可能な回答か明確なエラー文字列を返すようにツールを修正し、完了の判断基準がモデルに伝わるように docstring を明確にしてください。上限を引き上げるのは、ループ自体が正しく動作するようになってからにします: graph.invoke(payload, {"recursion_limit": 50})。

LangGraphDeprecatedSinceV10: create_react_agent has been moved to langchain.agents

langgraph-prebuilt 1.1 以降では、create_react_agent は非推奨です。from langgraph.prebuilt import create_react_agent を from langchain.agents import create_agent に置き換え、create_agent(model, tools) を呼び出してください。ToolNode と tools_condition は非推奨ではないため、上で示した手組みのグラフは引き続き有効です。

モデルがテキストで応答し、ツールを呼び出さない

よくある原因は 2 つあります。1 つ目は、モデルが Function calling に対応しておらず、そもそもツール呼び出しを発行できないケースです。Function calling と JSON モードで対応状況を確認してください。2 つ目は、グラフは構築したもののツールをバインドしておらず、モデルがツールの存在を知らないケースです。ToolNode(tools) はツール呼び出しを実行するだけで、ツールの存在をモデルに知らせるわけではありません。グラフ内の ToolNode(tools) と、モデルへの .bind_tools(tools) の両方が必要です。

参考情報

LangGraph の公式ドキュメント: グラフ API の全体像、永続化バックエンド、ストリーミングオプション
PyPI の langchain-sambanova: コンストラクターオプションと ChatSambaNova のリファレンス
SambaCloud モデル: 最新のモデル ID、コンテキストウィンドウ、Function calling 対応モデル
Function calling と JSON モード: ツール呼び出しを発行できるモデルの確認
SambaCloud API リファレンス

概要

開発者ツール

フレームワーク

インターフェースとローコード

データとインフラ

マルチモーダル

評価とモニタリング

前提条件

インストールとセットアップ

クイックスタート

グラフの構築

ツールと条件付きエッジの追加

ターンをまたいだ状態の永続化

ユースケースの例

トラブルシューティング

参考情報

​前提条件

​インストールとセットアップ

​クイックスタート

​グラフの構築

​ツールと条件付きエッジの追加

​ターンをまたいだ状態の永続化

​ユースケースの例

​トラブルシューティング

​参考情報

前提条件

インストールとセットアップ

クイックスタート

グラフの構築

ツールと条件付きエッジの追加

ターンをまたいだ状態の永続化

ユースケースの例

トラブルシューティング

参考情報