Agno エージェントを実行する方法とデバッグ方法を学習します。Agent.run() or Agent.arun() を呼び出してエージェントを実行します。
エージェントとは、言語モデルが実行フローを制御する AI プログラムです。エージェントの核心は、指示によりガイドされた、ループ内でツールを使用するモデルです。
Agno 2.x : Learn : エージェント – エージェントの実行とデバッグ
作成 : クラスキャット・セールスインフォメーション
作成日時 : 10/20/2025
バージョン : Agno 2.1.8
* 本記事は docs.agno.com の以下のページを独自に翻訳した上で、補足説明を加えてまとめ直しています。スニペットはできる限り日本語を使用しています :
* サンプルコードの動作確認はしておりますが、必要な場合には適宜、追加改変しています。
* ご自由にリンクを張って頂いてかまいませんが、sales-info@classcat.com までご一報いただけると嬉しいです。
Agno 2.x : Learn : エージェント – エージェントの実行
Agno エージェントを実行する方法を学習します。
Agent.run() or Agent.arun() を呼び出してエージェントを実行します。それらの動作の仕組みは :
- エージェントはモデルに送信するコンテキスト (システムメッセージ、ユーザーメッセージ、チャット履歴、ユーザメモリ、セッション状態、その他の関連入力) を構築します。
- エージェントはこのコンテキストをモデルに送信します。
- モデルは入力を処理して、メッセージかツール呼び出しかで応答します。
- モデルがツール呼び出しを行う場合、エージェントはそれを実行して結果をモデルに返します。
- モデルは更新されたコンテキストを処理し、このループを、モデルがツール呼び出しのない最終的なメッセージを生成するまで繰り返します。
- エージェントはこの最終的な応答を呼び出し元に返します。
基本的な実行
Agent.run() 関数はエージェントを実行して、出力を RunOutput オブジェクトか RunOutputEvent オブジェクトのストリーム (stream=True の場合) のいずれかとして返します。例えば :
from agno.agent import Agent, RunOutput
from agno.models.anthropic import Claude
from agno.tools.hackernews import HackerNewsTools
from agno.utils.pprint import pprint_run_response
from dotenv import load_dotenv
load_dotenv()
agent = Agent(
model=Claude(id="claude-sonnet-4-5"),
tools=[HackerNewsTools()],
instructions="トピックに関するレポートを作成します。レポートのみを出力します。" ,
markdown=True,
)
# エージェントを実行してレスポンスを変数として返します
response: RunOutput = agent.run("米国でトレンドの AI エージェント・フレームワーク")
# markdown 形式でレスポンスを表示します
pprint_run_response(response, markdown=True)
出力例
╭─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ 取得したHacker │ │ Newsのトップストーリーには、AIエージェント・フレームワークに直接関連する記事が見つかりませんでした。現在の技術トレンドの状況に基づいて、米国で… │ │ │ │ ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────── │ │ ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ │ │ ┃ 米国でトレンドのAIエージェント・フレームワーク ┃ │ │ ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛ │ │ │ │ │ │ エグゼクティブサマリー │ │ │ │ 2025年現在、米国のAI開発コミュニティでは、AIエージェントフレームワークが急速に進化しています。これらのフレームワークは、大規模言語モデル(LLM) … │ │ │ │ │ │ 主要なAIエージェント・フレームワーク │ │ │ │ 1. LangChain │ │ │ │ • 特徴: LLMアプリケーション開発の先駆的フレームワーク │ │ • 強み: │ │ • 豊富なドキュメントとコミュニティサポート │ │ • 多様なLLMプロバイダーとの統合 │ │ • チェーン、エージェント、メモリ機能の包括的実装 │ │ • ユースケース: チャットボット、質問応答システム、データ分析エージェント │ │ │ │ 2. AutoGPT / AgentGPT │ │ │ │ • 特徴: 自律型AIエージェントの実装 │ │ • 強み: │ │ • 目標設定による自律的タスク実行 │ │ • マルチステップ推論能力 │ │ • インターネット検索とツール使用の統合 │ │ • ユースケース: リサーチタスク、コンテンツ生成、自動化ワークフロー │ │ │ │ 3. CrewAI │ │ │ │ • 特徴: マルチエージェント協調フレームワーク │ │ • 強み: │ │ • 役割ベースのエージェント設計 │ │ • エージェント間のタスク委譲 │ │ • 構造化されたワークフロー管理 │ │ • ユースケース: チーム作業のシミュレーション、複雑なプロジェクト管理 │ │ │ │ 4. Microsoft Semantic Kernel │ │ │ │ • 特徴: エンタープライズグレードのオーケストレーションエンジン │ │ • 強み: │ │ • .NET、Python、Javaのサポート │ │ • プラグインアーキテクチャ │ │ • Microsoftエコシステムとの深い統合 │ │ • ユースケース: エンタープライズアプリケーション、業務自動化 │ │ │ │ 5. LlamaIndex (GPT Index) │ │ │ │ • 特徴: データインデックスと検索に特化 │ │ • 強み: │ │ • 高度なRAG(Retrieval-Augmented Generation)機能 │ │ • 多様なデータソース統合 │ │ • 効率的なドキュメント処理 │ │ • ユースケース: ナレッジベース構築、ドキュメント検索システム │ │ │ │ 6. Haystack │ │ │ │ • 特徴: エンドツーエンドのNLPフレームワーク │ │ • 強み: │ │ • パイプラインベースのアーキテクチャ │ │ • カスタマイズ可能なコンポーネント │ │ • プロダクション向け設計 │ │ • ユースケース: 質問応答、セマンティック検索、文書処理 │ │ │ │ │ │ 技術トレンド │ │ │ │ アーキテクチャパターン │ │ │ │ 1 ReAct (Reasoning + Acting): 推論と行動を組み合わせたパターン │ │ 2 Tree of Thoughts: 複数の推論パスを探索する手法 │ │ 3 Plan-and-Execute: 計画フェーズと実行フェーズの分離 │ │ │ │ 重要な技術的考慮事項 │ │ │ │ • メモリ管理: 短期・長期メモリの実装 │ │ • ツール使用: 外部APIやデータベースへのアクセス │ │ • エラーハンドリング: 失敗からの回復メカニズム │ │ • コスト最適化: LLM API呼び出しの効率化 │ │ │ │ │ │ 選定基準 │ │ │ │ フレームワーク選択時の主要な考慮事項： │ │ │ │ 1 プロジェクト規模: プロトタイプ vs. エンタープライズ │ │ 2 技術スタック: 使用言語とエコシステム │ │ 3 カスタマイズ性: 要件に応じた柔軟性 │ │ 4 コミュニティサポート: ドキュメントと事例の充実度 │ │ 5 パフォーマンス要件: レイテンシとスループット │ │ │ │ │ │ まとめ │ │ │ │ AIエージェント・フレームワークの領域は急速に成熟しており、2025年には様々なユースケースに対応した選択肢が存在します。LangChainが汎用的な選択肢 … │ │ │ │ 開発者は、プロジェクトの要件、チームの専門知識、長期的な保守性を考慮してフレームワークを選択することが重要です。多くの場合、複数のフレームワー… │ │ │ │ ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────── │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
💡 Agent.arun() を使用してエージェントを非同期に実行することもできます。この 例 をご覧ください。
Run Input
input パラメータはエージェントに送信する入力です。それは文字列、リスト、辞書、メッセージ、pydantic モデルやメッセージのリストで構いません。例えば :
from agno.agent import Agent, RunOutput
from agno.models.anthropic import Claude
from agno.tools.hackernews import HackerNewsTools
from agno.utils.pprint import pprint_run_response
agent = Agent(
model=Claude(id="claude-sonnet-4-5"),
tools=[HackerNewsTools()],
instructions="Write a report on the topic. Output only the report.",
markdown=True,
)
# Run agent with input="Trending startups and products."
response: RunOutput = agent.run(input="トレンドの LLM アプリ・フレームワーク")
# Print the response in markdown format
pprint_run_response(response, markdown=True)
出力例
╭─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ │ │ ┃ トレンドのLLMアプリ・フレームワーク ┃ │ │ ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛ │ │ │ │ 現在のHacker │ │ Newsのトップストーリーを調査したところ、LLM（大規模言語モデル）関連のアプリケーションやフレームワークに関するトレンドが見られました。以下、主 … │ │ │ │ │ │ 1. DeepSeek OCR │ │ │ │ 概要: │ │ DeepSeek AIが公開した最新のOCR（光学文字認識）プロジェクトで、GitHubで注目を集めています（211ポイント、55コメント）。 │ │ │ │ 特徴: │ │ │ │ • DeepSeekは中国発のAI企業で、高性能なオープンソースLLMの開発で知られています │ │ • OCR機能をLLMと統合し、画像から文字情報を抽出する技術を提供 │ │ • マルチモーダルAIアプリケーションの構築に活用可能 │ │ │ │ トレンドとしての意義: │ │ │ │ • LLMの応用範囲が、純粋なテキスト処理から視覚的な文書理解へと拡大していることを示しています │ │ • オープンソースでの公開により、開発者コミュニティでの活用が期待されます │ │ │ │ │ │ 2. Q/Kdb向けLLMコード生成の最適化 │ │ │ │ 概要: │ │ 「Don't Force Your LLM to Write Terse [Q/Kdb] Code: An Information Theory Argument」という記事（45ポイント、21コメント）が注目されています。 │ │ │ │ 主なポイント: │ │ │ │ • 情報理論の観点から、LLMに簡潔すぎるコードを書かせることの問題点を指摘 │ │ • 金融業界で広く使われるQ/Kdb+言語において、可読性とLLMのコード生成能力のバランスを議論 │ │ • LLMを実務で活用する際の実践的なガイドライン │ │ │ │ 実務への示唆: │ │ │ │ • LLMベースのコード生成ツールを導入する際、言語の特性とLLMの特性を考慮する必要性 │ │ • プロンプトエンジニアリングにおける新しい視点を提供 │ │ │ │ │ │ 3. 関連トレンド：Gleam OTP │ │ │ │ 概要: │ │ Gleam言語のOTP実装（121ポイント、40コメント）がランクインしています。 │ │ │ │ 特徴: │ │ │ │ • フォールトトレラントなマルチコアプログラムをアクターモデルで構築 │ │ • Erlang VM上で動作し、型安全性を提供 │ │ • 分散システムやリアルタイム処理に適しています │ │ │ │ LLMとの関連性: │ │ │ │ • LLMアプリケーションのバックエンドインフラとして、並行処理と耐障害性が重要視されています │ │ • マイクロサービスアーキテクチャでLLM APIを統合する際の選択肢として注目されています │ │ │ │ │ │ 現在のLLMフレームワークのトレンド分析 │ │ │ │ 調査結果から以下のトレンドが読み取れます： │ │ │ │ マルチモーダル化の加速 │ │ │ │ • テキストのみならず、画像認識（OCR）などを統合したLLMアプリケーションが増加 │ │ • DeepSeek OCRのような専門的なツールの登場 │ │ │ │ 実務適用における最適化 │ │ │ │ • 特定のドメイン（金融、データベース言語など）でのLLM活用ノウハウの蓄積 │ │ • プロンプトエンジニアリングから、言語・フレームワーク選択まで含めた総合的な最適化 │ │ │ │ インフラストラクチャの重要性 │ │ │ │ • AWS障害の影響（複数の記事で500ポイント超）が示すように、LLMアプリのインフラ依存性が課題 │ │ • 分散システムや耐障害性を持つフレームワークへの関心の高まり │ │ │ │ │ │ 結論 │ │ │ │ 現在のトレンドとして、LLMアプリケーション開発は以下の方向に進化しています： │ │ │ │ 1 機能の多様化: テキスト処理からマルチモーダル処理へ │ │ 2 実務適用の成熟: 理論から実践的なベストプラクティスへ │ │ 3 インフラの重要性: 可用性と拡張性を考慮した設計の必要性 │ │ │ │ 今後は、これらの要素を統合した包括的なLLMアプリケーションフレームワークの登場が期待されます。 │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ python work/agent_run2.py 1.02s user 0.18s system 2% cpu 45.327 total
Run Output
Agent.run() 関数は、ストリーミングでない場合に RunOutput オブジェクトを返します。中心的な属性の一部は以下です :
- run_id: 実行の id。
- agent_id: エージェントの id。
- agent_name: エージェントの名前。
- session_id: セッションの id。
- user_id: ユーザの id。
- content: レスポンスのコンテンツ。
- content_type: コンテンツの型。構造化出力の場合、これは pydantic モデルのクラス名です。
- reasoning_content: 推論コンテンツ。
- messages: モデルに送信されたメッセージのリスト。
- metrics: 実行のメトリクス。詳細は Metrics 参照。
- model: 実行に使用されたモデル。
See detailed documentation in the RunOutput documentation.
ストリーミング
ストリーミングを有効にするには、run() を呼び出す際に stream=True を設定します。これは単一のレスポンスではなく、RunOutputEvent オブジェクトのイテレータを返します。
from typing import Iterator
from agno.agent import Agent, RunOutputEvent, RunEvent
from agno.models.anthropic import Claude
from agno.tools.hackernews import HackerNewsTools
agent = Agent(
model=Claude(id="claude-sonnet-4-5"),
tools=[HackerNewsTools()],
instructions="トピックに関するレポートを作成します。レポートのみを出力します。",
markdown=True,
)
# Run agent and return the response as a stream
stream: Iterator[RunOutputEvent] = agent.run("トレンドのプログラミング言語", stream=True) # type:ignore
for chunk in stream:
if chunk.event == RunEvent.run_content:
print(chunk.content)
💡 For asynchronous streaming, see this example.
ストリーミングの中間ステップ
より詳細なストリーミングについては、stream_intermediate_steps=True を設定することで中間ステップを有効にできます。これはエージェントの中間プロセスについてリアルタイムの更新情報を提供します。例えば :
# Stream with intermediate steps
response_stream: Iterator[RunOutputEvent] = agent.run(
"Trending products",
stream=True,
stream_intermediate_steps=True
)
イベント処理
response stream を反復処理することでイベントが到着した時点で処理できます :
from agno.agent import Agent, RunEvent
from agno.models.anthropic import Claude
from agno.tools.hackernews import HackerNewsTools
agent = Agent(
model=Claude(id="claude-sonnet-4-5"),
tools=[HackerNewsTools()],
instructions="Write a report on the topic. Output only the report.",
markdown=True,
)
stream = agent.run("Trending products", stream=True, stream_intermediate_steps=True)
for chunk in stream:
if chunk.event == RunEvent.run_content:
print(f"Content: {chunk.content}")
elif chunk.event == RunEvent.tool_call_started:
print(f"Tool call started: {chunk.tool.tool_name}")
elif chunk.event == RunEvent.reasoning_step:
print(f"Reasoning step: {chunk.content}")
✅ RunEvents make it possible to build exceptional agent experiences.
実行ユーザとセッションの指定
エージェント実行時に使用するユーザとセッションを、user_id と session_id パラメータを渡すことで指定できます。これは、現在の実行を正しいユーザとセッションに関連づけることを保証します。例えば :
agent.run("Tell me a 5 second short story about a robot", user_id="john@example.com", session_id="session_123")
For more information see the Agent Sessions documentation.
画像 / 音声 / 動画 / ファイルを渡す
images, audio, video, or files パラメータを渡すことで、エージェントに画像、音声、動画やファイルを渡すことができます。例えば :
agent.run("Tell me a 5 second short story about this image", images=[Image(url="https://example.com/image.jpg")])
For more information see the Multimodal Agents documentation.
実行の一時停止と再開
エージェント実行は、human-in-the-loop フローが初期化されている場合、一時停止できます。それから Agent.continue_run() メソッドを呼び出すことで、エージェントの実行を再開できます。
See more details in the Human-in-the-Loop documentation.
実行のキャンセル
Agent.cancel_run() メソッドを呼び出すことで、実行はキャンセルできます。See more details in the Cancelling a Run documentation.
Agno 2.x : Learn : エージェント – エージェントのデバッグ
Agno エージェントをデバッグする方法を学習します。
Agno は、開発エクスペリエンスを次のレベルに引き上げる、非常に適切に構築されたデバッグモードを備えています。それは実行フローと中間ステップを理解するのに役立ちます。例えば :
- モデルに送信されたメッセージとモデルが生成した応答を検査します。
- 中間ステップをトレースして、トークン使用量、実行時間 等のメトリクスを監視します。
- ツール呼び出し、エラーとその結果を検査します。
デバッグモード
デバッグモードを有効にするには :
- エージェントの debug_mode パラメータを設定し、すべての実行に対して有効にします。
- run メソッドの debug_mode パラメータを設定し、現在の実行に対して有効にします。
- AGNO_DEBUG 環境変数を True に設定し、すべてのエージェントに対して有効にします。
from agno.agent import Agent
from agno.models.anthropic import Claude
from agno.tools.hackernews import HackerNewsTools
agent = Agent(
model=Claude(id="claude-sonnet-4-5"),
tools=[HackerNewsTools()],
instructions="トピックに関するレポートを作成します。レポートのみを出力します。",
markdown=True,
debug_mode=True,
# debug_level=2, # Uncomment to get more detailed logs
)
# Run agent and print response to the terminal
agent.print_response("トレンドの LLM モデル")
💡 You can set debug_level=2 to get even more detailed logs.
Here’s how it looks:
インタラクティブ CLI
Agno はまた、エージェントをコマンドライン・アプリケーションとして実行できる、事前構築済みのインタラクティブ CLI も備えています。これを使用して、エージェントとの会話のやり取りをテストできます。
from agno.agent import Agent
from agno.db.sqlite import SqliteDb
from agno.models.anthropic import Claude
from agno.tools.hackernews import HackerNewsTools
agent = Agent(
model=Claude(id="claude-sonnet-4-5"),
tools=[HackerNewsTools()],
db=SqliteDb(db_file="tmp/data.db"),
add_history_to_context=True,
num_history_runs=3,
markdown=True,
)
# Run agent as an interactive CLI app
agent.cli_app(stream=True)
以上