8月8日、Soner Yıldırımが「Building a Streamlit UI for My LangGraph AI Agent」と題した記事を公開した。LangGraphのグラフ本体を一切変更せずにStreamlitのチャットUIを被せる——この「エージェントとUIの完全分離」という設計方針こそが本記事の核心であり、同じグラフをCLI・API・WhatsAppといった複数のチャネルから呼び出せる拡張性を生む。

設計の核心：エージェントとUIを完全に分離する

この実装で最も重要なポイントは、LangGraphのグラフ本体にStreamlit固有のロジックを一切持ち込まないという設計方針だ。StreamlitはLangGraphエージェントのラッパーとして機能し、状態を画面に表示しユーザー操作をエージェントに渡すだけに徹する。

この分離により、グラフ側のコードに手を入れることなく、CLI・API・WhatsApp・別フロントエンドといった任意のインターフェースから同一のエージェントを呼び出せる構造になっている。UIをStreamlitに依存させず、エージェントをUIに依存させない——この双方向の独立性が、本実装を単なる「画面追加」ではなく再利用可能な設計パターンたらしめている。

背景：CLIで動いていた予約エージェントをUI化する

Soner Yıldırımは以前の記事で、15分かかる顧客サービスの予約プロセスを自動化するLangGraphベースのAIエージェントを構築した。このエージェントは、顧客の要望把握・料金計算・日程提案・予約確定まで一連の予約フローを処理する。

ただし初版はPythonのCLIで動作するだけで、UIは最低限だった。本記事ではそのエージェントにStreamlit製のインタラクティブなUIを被せる実装を解説している。ソースコードはGitHubのcustomer-service-agentで公開されている。

実装の要点

セッション状態の管理

Streamlitの重要な特性として、ウィジェットへの操作があるたびにPythonスクリプト全体が再実行されるという点がある。通常のローカル変数は再実行のたびに消えるため、会話履歴やグラフ状態を保持するにはst.session_stateを使う必要がある。

def initialize_session() -> None:
    if "graph" in st.session_state:
        return
    llm = ChatOpenAI(
        model=os.getenv("OPENAI_MODEL", "gpt-4o-mini"),
        temperature=0,
    )
    handler = create_langfuse_handler()
    st.session_state.graph = build_graph(llm)
    st.session_state.handler = handler
    st.session_state.config = graph_config(
        str(uuid4()),
        handler,
    )
    st.session_state.agent_state = INITIAL_STATE.copy()
    st.session_state.started = False

コード中のcreate_langfuse_handler()およびflush_langfuse()は、LLMの入出力・レイテンシ・コストをトレースするオブザーバビリティツールLangfuseのハンドラを生成・フラッシュするためのヘルパーだ。エージェントの挙動を可視化・デバッグするために組み込まれている。

関数冒頭のif "graph" in st.session_stateチェックが肝で、これがないと再実行のたびにグラフが初期化されてしまう。同様の理由でthread_id（LangGraphが会話を識別するためのID）も固定する必要があり、毎回新しいUUIDを生成すると全メッセージが別会話として扱われる。

グラフの呼び出しと状態の保存

ユーザーからの入力（チャットメッセージやボタンクリック）は_invoke関数がまとめて処理する。

def _invoke(customer_text: str) -> None:
    graph_input: dict[str, Any] = {"messages": [HumanMessage(content=customer_text)]}
    if not st.session_state.started:
        graph_input.update(INITIAL_STATE)
        graph_input["messages"] = [HumanMessage(content=customer_text)]
        st.session_state.started = True
    try:
        result = st.session_state.graph.invoke(graph_input, config=st.session_state.config)
        st.session_state.agent_state = result
        flush_langfuse(st.session_state.handler)
    except Exception:
        st.session_state.started = bool(st.session_state.agent_state.get("messages"))
        st.error("The assistant could not process that request. Please try again.")

初回メッセージのみINITIAL_STATE（空の予約詳細・日程オプション・料金・ステータス）でグラフを初期化し、以降は返ってきたグラフ状態をそのままセッションに保存する。LangGraphのadd_messagesリデューサーにより、新メッセージは既存の会話履歴に追記される形になる。これはLangGraph固有の概念で、グラフの状態スキーマにアノテーションとして指定することで、invokeのたびにメッセージリストを手動で連結する実装を不要にする仕組みだ。

画面の描画

現在のグラフ状態を画面要素に変換するrender関数群（_render_messagesなど）もstreamlit_app.py内に定義する。たとえば_render_messagesはstate["messages"]から会話履歴を取得し、StreamlitのチャットバブルUIとして表示する。メッセージがない初期状態では定型の挨拶文を表示する。

def _render_messages(state: AgentState) -> None:
    if not state.get("messages"):
        with st.chat_message("assistant"):
            st.write(
                "Hi! I can help you book house or couch cleaning. "
                "Tell me what you need, including the size and service address."
            )
        return
    for message in state["messages"]:
        if isinstance(message, HumanMessage):
            role = "user"
        elif isinstance(message, AIMessage):
            role = "assistant"
        else:
            continue
        with st.chat_message(role):
            st.write(str(message.content))

実際の動作

ローカルでの起動は以下のコマンドで行う（パッケージ管理にはPoetryを使用）。

poetry run streamlit run customer_service_agent/streamlit_app.py

http://localhost:8501/でページが開く。動作確認にはOpenAI APIキーが必要で、数セント程度のコストがかかる。

実際の画面例：

住所を伝えずにメッセージを送ると、エージェントが住所を追加で聞いてくる。

最初のメッセージに住所を含めると、追加質問なしに料金を提示。承認すると3つの日程候補を提示し、選択後に予約が完了する。

今後の展開

著者はWhatsApp連携などの機能追加を計画しており、地元ビジネスへの販売も視野に入れているとのことだ。WhatsApp対応が実現した場合、エージェント本体のグラフは変更不要で、WhatsApp向けのI/Oアダプターを新たに実装するだけで済む。これはまさに本記事で示した「エージェントとUIの完全分離」設計の恩恵であり、チャネルが増えるほどこのアーキテクチャの価値が際立つ構造になっている。

詳細はBuilding a Streamlit UI for My LangGraph AI Agentを参照していただきたい。