エージェントの状態について学習します。状態は、セッションの実行全体を通して維持する必要がある任意の種類のデータです。
Agno のエージェントは異なるセッション間や実行間で作業状態を維持しませんが、状態管理機能は提供しています。
Agno 2.x : Learn : エージェント – エージェント状態
作成 : クラスキャット・セールスインフォメーション
作成日時 : 10/28/2025
バージョン : Agno 2.2.1
* 本記事は docs.agno.com の以下のページを独自に翻訳した上で、補足説明を加えてまとめ直しています。スニペットはできる限り日本語を使用しています :
* サンプルコードの動作確認はしておりますが、必要な場合には適宜、追加改変しています。
* ご自由にリンクを張って頂いてかまいませんが、sales-info@classcat.com までご一報いただけると嬉しいです。
Agno 2.x : Learn : エージェント – エージェント状態
エージェントの状態について学習します。
状態は、セッションの実行全体を通して維持する必要がある任意の種類のデータです。
エージェントの単純ながらも一般的なユースケースは、ユーザ向けにリスト、アイテムやその他の「情報」を管理することです。例えば、買い物リスト、todo リスト、ウィッシュリスト 等。これらは session_state を使用して簡単に管理できます。エージェントはツール呼び出しで session_state にアクセスや更新することができて、システムメッセージを通してモデルにそれらを公開できます。
そしてセッション状態は設定されたデータベースに永続化され、そのセッション内の実行全体で利用可能です。
Info : 「ステートレス性 (Statelessness)」の理解 : Agno のエージェントは異なるセッション間や実行間で作業状態を維持しませんが、状態管理機能は提供しています :
- エージェントの session_state パラメータは新しいセッション用のデフォルトの状態テンプレートを提供します。
- get_session_state() メソッドはデータベースから特定のセッションのセッション状態を取得します。
- 作業状態は実行毎に管理されて、セッション毎にデータベースに永続化されます。
- エージェントインスタンス (or その属性) 自体は実行中変更されません。
状態管理
Agno は強力で洗練された状態管理システムを提供します。それがどのように動作するかは以下の通りです :
- エージェントの session_state パラメータをデフォルトの状態変数の辞書で設定できます。
- ツール呼び出しやその他の関数で session_state 状態を更新できます。
- description や instructions の状態変数を参照することで、システムメッセージ経由で現在の session_state を LLM と共有できます。
- session_state を agent.run() に渡すこともできます、これはエージェントのデフォルト状態より優先されます。
- session_state はデータベースにセッション毎に保存され、そのセッション内で実行全体にわたり永続化されます。
- agent.run() で session_id 経由でセッションを切り替える場合、適切なセッション状態がデータベースからロードされます。
買い物リストを管理するエージェントの例は以下になります :
session_state.py
from agno.agent import Agent
from agno.db.sqlite import SqliteDb
from agno.models.openai import OpenAIChat
# アイテムを買い物リストに追加するツールの定義
def add_item(session_state, item: str) -> str:
"""Add an item to the shopping list."""
session_state["shopping_list"].append(item)
return f"買い物リストは現在 {session_state['shopping_list']} です。"
# 状態を維持するエージェントの作成
agent = Agent(
model=OpenAIChat(id="gpt-4.1"),
# セッションとそれらの状態を保存するデータベース
db=SqliteDb(db_file="tmp/agents.db"),
# セッション状態を空の買い物リストで初期化
session_state={"shopping_list": []},
tools=[add_item],
# instructions でセッション状態の変数を使用できます。
instructions="現在の状態 (買い物リスト) は: {shopping_list}",
markdown=True,
)
# Example usage
agent.print_response("ミルク、卵とパンを買い物リストに追加してください", stream=True)
print(f"最終的なセッション状態は: {agent.get_session_state()}")
出力例
INFO Successfully created table 'agno_sessions'
┏━ Message ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ ┃
┃ ミルク、卵とパンを買い物リストに追加してください ┃
┃ ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
┏━ Response (3.8s) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ ┃
┃ ミルク、卵、パンを買い物リストに追加しました。 ┃
┃ ┃
┃ 現在の買い物リスト: ┃
┃ ┃
┃ • ミルク ┃
┃ • 卵 ┃
┃ • パン ┃
┃ ┃
┃ 他に追加したいものはありますか？ ┃
┃ ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
最終的なセッション状態は: {'shopping_list': ['ミルク', '卵', 'パン']}
Info : session_state 変数は引数としてツールに自動的に渡されます。この変数への更新は共有状態において自動的に反映されます。
セッション内で複数の実行にわたり状態を維持する
セッションの大きな利点は、同じセッション内で複数の実行に渡り状態を維持できることです。例えば、エージェントはユーザが買い物リストを追跡する支援をするとしましょう。
Info : 実行に渡り状態を保持するには、db パラメータを通してストレージを設定する必要があります。
shopping_list.py
from textwrap import dedent
from agno.agent import Agent
from agno.db.sqlite import SqliteDb
from agno.models.openai import OpenAIChat
# 買い物リストを管理するツールの定義
def add_item(session_state, item: str) -> str:
"""Add an item to the shopping list and return confirmation."""
# アイテムがリストにまだ含まれていない場合は、それを追加します。
if item.lower() not in [i.lower() for i in session_state["shopping_list"]]:
session_state["shopping_list"].append(item) # type: ignore
return f"買い物リストに '{item}' を追加しました"
else:
return f"'{item}' は既に買い物リストにあります"
def remove_item(session_state, item: str) -> str:
"""Remove an item from the shopping list by name."""
# Case-insensitive search
for i, list_item in enumerate(session_state["shopping_list"]):
if list_item.lower() == item.lower():
session_state["shopping_list"].pop(i)
return f"買い物リストから '{list_item}' を削除しました"
return f"'{item}' は買い物リストで見つかりませんでした"
def list_items(session_state) -> str:
"""List all items in the shopping list."""
shopping_list = session_state["shopping_list"]
if not shopping_list:
return "買い物リストは空です。"
items_text = "\n".join([f"- {item}" for item in shopping_list])
return f"現在の買い物リストは:\n{items_text}"
# 状態を維持する、買い物リストマネージャ・エージェントを作成します
agent = Agent(
model=OpenAIChat(id="gpt-4.1"),
# セッション状態を空の買い物リストで初期化します (default session state for all sessions)
session_state={"shopping_list": []},
db=SqliteDb(db_file="tmp/example.db"),
tools=[add_item, remove_item, list_items],
# instruction で、セッション状態の変数を使用できます
instructions=dedent("""\
あなたのジョブは買い物リストを管理することです。
買い物リストは空から始まります。あなたはアイテムを追加し、アイテムを名前で削除し、すべてのアイテムをリストアップできます。
現在の買い物リストは: {shopping_list}
"""),
markdown=True,
)
# Example usage
agent.print_response("ミルク、卵とパンを買い物リストに追加してください", stream=True)
print(f"セッション状態: {agent.get_session_state()}")
agent.print_response("パンを買いました", stream=True)
print(f"セッション状態: {agent.get_session_state()}")
agent.print_response("りんごとみかんが必要です", stream=True)
print(f"セッション状態: {agent.get_session_state()}")
agent.print_response("リストには何がありますか?", stream=True)
print(f"セッション状態: {agent.get_session_state()}")
agent.print_response(
"リストからすべて削除して、バナナとヨーグルトだけにして最初からやり直してください",
stream=True,
)
print(f"セッション状態: {agent.get_session_state()}")
出力例
INFO Successfully created table 'agno_sessions'
┏━ Message ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ ┃
┃ ミルク、卵とパンを買い物リストに追加してください ┃
┃ ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
┏━ Response (6.9s) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ ┃
┃ 買い物リストに以下のアイテムを追加しました。 ┃
┃ ┃
┃ • ミルク ┃
┃ • 卵 ┃
┃ • パン ┃
┃ ┃
┃ 他に追加・削除したいものはありますか？ ┃
┃ ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
セッション状態: {'shopping_list': ['ミルク', '卵', 'パン']}
┏━ Message ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ ┃
┃ パンを買いました ┃
┃ ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
┏━ Response (3.4s) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ ┃
┃ パンを買い物リストから削除しました。 ┃
┃ ┃
┃ 現在の買い物リスト： ┃
┃ ┃
┃ • ミルク ┃
┃ • 卵 ┃
┃ ┃
┃ 他にリストを更新しますか？ ┃
┃ ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
セッション状態: {'shopping_list': ['ミルク', '卵']}
┏━ Message ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ ┃
┃ りんごとみかんが必要です ┃
┃ ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
┏━ Response (3.3s) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ ┃
┃ ┃
┃ • 買い物リストに「りんご」と「みかん」を追加しました。 ┃
┃ ┃
┃ 現在の買い物リスト ┃
┃ ┃
┃ • ミルク ┃
┃ • 卵 ┃
┃ • りんご ┃
┃ • みかん ┃
┃ ┃
┃ 他に追加したいものはありますか？ ┃
┃ ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
セッション状態: {'shopping_list': ['ミルク', '卵', 'りんご', 'みかん']}
┏━ Message ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ ┃
┃ リストには何がありますか? ┃
┃ ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
┏━ Response (1.5s) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ ┃
┃ 現在の買い物リストに入っているアイテムは以下の通りです。 ┃
┃ ┃
┃ • ミルク ┃
┃ • 卵 ┃
┃ • りんご ┃
┃ • みかん ┃
┃ ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
セッション状態: {'shopping_list': ['ミルク', '卵', 'りんご', 'みかん']}
┏━ Message ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ ┃
┃ リストからすべて削除して、バナナとヨーグルトだけにして最初からやり直してください ┃
┃ ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
┏━ Response (5.1s) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ ┃
┃ 📝 現在の買い物リスト ┃
┃ ┃
┃ • バナナ ┃
┃ • ヨーグルト ┃
┃ ┃
┃ すべてリセットして、バナナとヨーグルトだけにしました。ご希望通りやり直しました！ ┃
┃ ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
セッション状態: {'shopping_list': ['バナナ', 'ヨーグルト']}
エージェント型セッション状態
Agno は、エージェントがセッション状態を自動的に更新することを可能にする方法を提供しています。単純に、enable_agentic_state パラメータを True に設定します。
agentic_session_state.py
from agno.agent import Agent
from agno.models.openai import OpenAIChat
from agno.db.sqlite import SqliteDb
agent = Agent(
db=SqliteDb(db_file="tmp/agents.db"),
model=OpenAIChat(id="gpt-4.1"),
session_state={"shopping_list": []},
add_session_state_to_context=True, # Required so the agent is aware of the session state
enable_agentic_state=True, # Adds a tool to manage the session state
)
agent.print_response("ミルク、卵とパンを買い物リストに追加してください", stream=True)
print(f"セッション状態: {agent.get_session_state()}")
出力例
┏━ Message ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ ┃
┃ ミルク、卵とパンを買い物リストに追加してください ┃
┃ ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
┏━ Response (3.1s) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ ┃
┃ ミルク、卵、パンを買い物リストに追加しました。必要なものが他にもあれば教えてください！ ┃
┃ ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
セッション状態: {'shopping_list': ['ミルク', '卵', 'パン']}
以上