状態は、エージェントが実行を通して維持する必要がある任意の種類のデータです。Agno は強力で洗練された状態管理システムを提供しています。
Agno : ユーザガイド : コンセプト : エージェント – エージェント状態
作成 : クラスキャット・セールスインフォメーション
作成日時 : 07/17/2025
バージョン : Agno 1.7.4
* 本記事は docs.agno.com の以下のページを独自に翻訳した上で、補足説明を加えてまとめ直しています :
* サンプルコードの動作確認はしておりますが、必要な場合には適宜、追加改変しています。
* ご自由にリンクを張って頂いてかまいませんが、sales-info@classcat.com までご一報いただけると嬉しいです。
Agno ユーザガイド : コンセプト : エージェント – エージェント状態
状態は、エージェントが実行を通して維持する必要がある任意の種類のデータです。
Note : エージェントの単純ながら一般的なユースケースは、ユーザのためにリスト、アイテム、やその他の「情報」を管理することです。例えば、買い物リスト、todo リスト、ウィッシュリスト 等です。
これは session_state を使用して簡単に管理できます。エージェントはツール呼び出し内で session_state を更新し、説明と指示内でそれらをモデルに公開します。
Agno は強力で洗練された状態管理システムを提供しています、それがどのように動作するか以下に示します :
- エージェントは session_state パラメータを持ちます。
- この session_state 辞書に状態変数を追加します。
- ツール呼び出しや他の関数内でこの session_state 辞書を更新します。
- 説明と手順内で現在の session_state をモデルと共有します。
- session_state はエージェント・セッションとともに保存され、データベースに永続化されます。つまり、実行サイクルに渡り利用可能です。これはまた、agent.run() の呼び出し間でセッションを切り替える場合、状態がロードされて利用可能になることを意味します。
- agent.run() でエージェントに session_state を渡し、エージェント初期化時に設定された状態を効果的に上書きすることもできます。
エージェントが買い物リストを管理する例が以下です :
session_state.py
from agno.agent import Agent
from agno.models.openai import OpenAIChat
# Define a tool that adds an item to the shopping list
def add_item(agent: Agent, item: str) -> str:
"""Add an item to the shopping list."""
agent.session_state["shopping_list"].append(item)
return f"The shopping list is now {agent.session_state['shopping_list']}"
# Create an Agent that maintains state
agent = Agent(
model=OpenAIChat(id="gpt-4o-mini"),
# Initialize the session state with a counter starting at 0
session_state={"shopping_list": []},
tools=[add_item],
# You can use variables from the session state in the instructions
instructions="Current state (shopping list) is: {shopping_list}",
# Important: Add the state to the messages
add_state_in_messages=True,
markdown=True,
)
# Example usage
agent.print_response("Add milk, eggs, and bread to the shopping list", stream=True)
print(f"Final session state: {agent.session_state}")
複数の実行に渡る状態の維持
セッションの大きな利点は、複数の実行に渡り状態を維持できる能力です。例えば、ユーザが買い物リストを追跡するのをエージェントが支援しているとします。
Note : add_state_in_messages=True を設定することで、session_state 辞書のキーが説明と指示で変数として利用できるようになります。
このパターンを使用して shopping_list を指示に直接追加します。
shopping_list.py
from textwrap import dedent
from agno.agent import Agent
from agno.models.openai import OpenAIChat
# Define tools to manage our shopping list
def add_item(agent: Agent, item: str) -> str:
"""Add an item to the shopping list and return confirmation."""
# Add the item if it's not already in the list
if item.lower() not in [i.lower() for i in agent.session_state["shopping_list"]]:
agent.session_state["shopping_list"].append(item)
return f"Added '{item}' to the shopping list"
else:
return f"'{item}' is already in the shopping list"
def remove_item(agent: Agent, item: str) -> str:
"""Remove an item from the shopping list by name."""
# Case-insensitive search
for i, list_item in enumerate(agent.session_state["shopping_list"]):
if list_item.lower() == item.lower():
agent.session_state["shopping_list"].pop(i)
return f"Removed '{list_item}' from the shopping list"
return f"'{item}' was not found in the shopping list"
def list_items(agent: Agent) -> str:
"""List all items in the shopping list."""
shopping_list = agent.session_state["shopping_list"]
if not shopping_list:
return "The shopping list is empty."
items_text = "\n".join([f"- {item}" for item in shopping_list])
return f"Current shopping list:\n{items_text}"
# Create a Shopping List Manager Agent that maintains state
agent = Agent(
model=OpenAIChat(id="gpt-4o-mini"),
# Initialize the session state with an empty shopping list
session_state={"shopping_list": []},
tools=[add_item, remove_item, list_items],
# You can use variables from the session state in the instructions
instructions=dedent("""\
Your job is to manage a shopping list.
The shopping list starts empty. You can add items, remove items by name, and list all items.
Current shopping list: {shopping_list}
"""),
show_tool_calls=True,
add_state_in_messages=True,
markdown=True,
)
# Example usage
agent.print_response("Add milk, eggs, and bread to the shopping list", stream=True)
print(f"Session state: {agent.session_state}")
agent.print_response("I got bread", stream=True)
print(f"Session state: {agent.session_state}")
agent.print_response("I need apples and oranges", stream=True)
print(f"Session state: {agent.session_state}")
agent.print_response("whats on my list?", stream=True)
print(f"Session state: {agent.session_state}")
agent.print_response("Clear everything from my list and start over with just bananas and yogurt", stream=True)
print(f"Session state: {agent.session_state}")
指示で状態を使用
add_state_in_messages=True を設定すると、指示 (instructions) でセッション状態の変数を使用できます。
Note : Don’t use the f-string syntax in the instructions. Directly use the {key} syntax, Agno substitutes the values for you.
state_in_instructions.py
from textwrap import dedent
from agno.agent import Agent
from agno.models.openai import OpenAIChat
agent = Agent(
model=OpenAIChat(id="gpt-4o-mini"),
# Initialize the session state with a variable
session_state={"user_name": "John"},
# You can use variables from the session state in the instructions
instructions="Users name is {user_name}",
show_tool_calls=True,
add_state_in_messages=True,
markdown=True,
)
agent.print_response("What is my name?", stream=True)
Your name is John.
実行時の状態変更
agent.run() で session_id をエージェントに渡すと、指定された session_id を持つセッションに切り替えて、セッションに設定された任意の状態をロードします。
これは、特定のユーザ向けにセッションを継続したい場合に有用です。
changing_state_on_run.py
from agno.agent import Agent
from agno.models.openai import OpenAIChat
agent = Agent(
model=OpenAIChat(id="gpt-4o-mini"),
add_state_in_messages=True,
instructions="Users name is {user_name} and age is {age}",
)
# Sets the session state for the session with the id "user_1_session_1"
agent.print_response("What is my name?", session_id="user_1_session_1", user_id="user_1", session_state={"user_name": "John", "age": 30})
# Will load the session state from the session with the id "user_1_session_1"
agent.print_response("How old am I?", session_id="user_1_session_1", user_id="user_1")
# Sets the session state for the session with the id "user_2_session_1"
agent.print_response("What is my name?", session_id="user_2_session_1", user_id="user_2", session_state={"user_name": "Jane", "age": 25})
# Will load the session state from the session with the id "user_2_session_1"
agent.print_response("How old am I?", session_id="user_2_session_1", user_id="user_2")
┏━ Message ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ ┃ ┃ ┃ What is my name? ┃ ┃ ┃ ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛ ┏━ Response (1.8s) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ ┃ ┃ ┃ Your name is John. ┃ ┃ ┃ ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛ ┏━ Message ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ ┃ ┃ ┃ How old am I? ┃ ┃ ┃ ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛ ┏━ Response (2.1s) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ ┃ ┃ ┃ You are 30 years old, John. ┃ ┃ ┃ ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛ ┏━ Message ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ ┃ ┃ ┃ What is my name? ┃ ┃ ┃ ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛ ┏━ Response (1.7s) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ ┃ ┃ ┃ Your name is Jane. ┃ ┃ ┃ ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛ ┏━ Message ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ ┃ ┃ ┃ How old am I? ┃ ┃ ┃ ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛ ┏━ Response (1.7s) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ ┃ ┃ ┃ You are 25 years old. ┃ ┃ ┃ ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
データベースへの状態の永続化
session_state はエージェント・セッションの一部で、ストレージ・ドライバが提供されている場合には各実行後にデータベースに保存されます。
買い物リストを維持し状態をデータベースに永続化するエージェントの例が以下になります。このスクリプトを複数回実行して、状態が永続化されていることを確認してください。
session_state_storage.py
"""Run `pip install agno openai sqlalchemy` to install dependencies."""
from agno.agent import Agent
from agno.models.openai import OpenAIChat
from agno.storage.sqlite import SqliteStorage
# Define a tool that adds an item to the shopping list
def add_item(agent: Agent, item: str) -> str:
"""Add an item to the shopping list."""
if item not in agent.session_state["shopping_list"]:
agent.session_state["shopping_list"].append(item)
return f"The shopping list is now {agent.session_state['shopping_list']}"
agent = Agent(
model=OpenAIChat(id="gpt-4o-mini"),
# Fix the session id to continue the same session across execution cycles
session_id="fixed_id_for_demo",
# Initialize the session state with an empty shopping list
session_state={"shopping_list": []},
# Add a tool that adds an item to the shopping list
tools=[add_item],
# Store the session state in a SQLite database
storage=SqliteStorage(table_name="agent_sessions", db_file="tmp/data.db"),
# Add the current shopping list from the state in the instructions
instructions="Current shopping list is: {shopping_list}",
# Important: Set `add_state_in_messages=True`
# to make `{shopping_list}` available in the instructions
add_state_in_messages=True,
markdown=True,
)
# Example usage
agent.print_response("What's on my shopping list?", stream=True)
print(f"Session state: {agent.session_state}")
agent.print_response("Add milk, eggs, and bread", stream=True)
print(f"Session state: {agent.session_state}")
以上