Agno 再入門 : チュートリアル – エージェント・プラットフォーム

by

エージェントプラットフォームのための最も効率的で最小限の基盤 : エージェントの構築と改善を支援する Claude Code プロンプトを備えた、AgentOS、Postgres、Docker、Railway。

Agno 再入門 : チュートリアル – エージェント・プラットフォーム

作成 : クラスキャット・セールスインフォメーション
作成日時 : 05/10/2026
バージョン : v2.6.5

* 本記事は docs.agno.com の以下のページを参考にしています :

* サンプルコードの動作確認はしておりますが、必要な場合には適宜、追加改変しています。

 

クラスキャット AI 研究開発支援サービス ⭐️ 創立30周年（30th Anniversary）🎉💐

◆ クラスキャット は AI に関する各種サービスを提供しています。お気軽にご相談ください :

  • AI 研究開発支援 [詳細]

    1. AI エージェント構築支援
    2. 画像認識 (医療系含む) / 画像生成

  • AI 導入個別相談会(無償)実施中！ [詳細]

  • PoC(概念実証)を失敗させないための支援 [詳細]

◆ お問合せ : 下記までお願いします。

  • クラスキャット セールス・インフォメーション
  • sales-info@classcat.com
  • ClassCatJP

 

 

Agno 再入門 : チュートリアル – エージェント・プラットフォーム

What is the Agent Platform Template?

エージェントプラットフォームのための最も効率的で最小限の基盤 : エージェントの構築と改善を支援する Claude Code プロンプトを備えた、AgentOS、Postgres、Docker、Railway。

エージェントプラットフォーム・テンプレートは、エージェントプラットフォーム用の基盤となるコードベースです。ポート 8000 ​​の FastAPI、セッションとメモリ管理用の Postgres、ローカル環境用の Docker、本番環境用の Railway、2 つのリファレンスエージェント、そして新しいエージェントを作成、改善、評価するための Claude Code プロンプトのセット。

一度起動したら、コードを書かずに新しいエージェントを公開できます。Claude Code は、テンプレートの docs/ フォルダにあるプロンプトを使用してエージェントファイルを生成し、それを登録し、コンテナを再起動してスモークテストを行います。それから、コンテナのログを読み取り、構築したものを再帰的に改善します。

​

 

Why an agent platform

本番環境でエージェントを運用するすべてのチームは、同じような問題に直面します : エージェントを実行するためのシステムが必要です。セッションはどこかに保存されます。トレースもです。ツールや認証情報もどこかに保存されます。プラットフォームがない場合、新しいエージェントはそれぞれ独自の方法で同じ 6 つの課題を解決しなければなりません。プラットフォームがあれば、開発者はエージェントの構築に専念でき、残りの処理はプラットフォームが担ってくれます。

 

What an agent platform needs

  • ランタイム (層) – (分担) エージェントを実行するサービス。SSE ストリーミング、セッション、スケジューリング、RBAC。

  • ストレージ – セッション、メモリ、ナレッジ、トレース、評価履歴。単一のデータベース。

  • コネクタ – エージェントがアクセスするツール、MCP サーバー、API、CLI。

  • インターフェース – Slack、Discord、Telegram、カスタム UI。ユーザー ID を解決するための単一の場所。

  • インフラストラクチャ – すべてが実行される場所。ローカルでは Docker、本番環境では Railway (または任意のコンテナホスト)。

 

セットアップ

テンプレートを複製して、ローカル環境で 5 分以内に実行できます。

このページでは、エージェントプラットフォーム・テンプレートをあなたのマシン上で実行します: ポート 8000 ​​で動作する FastAPI サービス、セッションとメモリ用の Postgres、そして 2 つのリファレンスエージェント（code_search、web_search）が含まれます。

 

要件

 

ローカルで実行

  1. テンプレートの複製

    git clone https://github.com/agno-agi/agentos-railway-template.git agent-platform
cd agent-platform

  2. 環境の設定

    cp example.env .env

    Open .env and set OPENAI_API_KEY. Everything else has sensible defaults.

  3. プラットフォームの起動

    docker compose up -d --build

    FastAPI アプリケーションと Postgres データベースの2つのコンテナが起動します。初回起動時にはベースイメージが pull され、コンテナが構築されます。以降の起動は瞬時に行われます。

  4. Verify it’s running

    curl http://localhost:8000/health

    出力例

    {"status":"ok","instantiated_at":"2026-05-09T06:56:23.568849Z"}

    Expect {“status”:”ok”}. If you get connection refused, the container is still starting; check docker compose logs -f and wait for the Agno banner.
    The OpenAPI spec is at http://localhost:8000/docs.

 

AgentOS UI への接続

os.agno.com を開いてログインします。

`+Connect AgentOS` をクリックし、`Local` を選択して、http://localhost:8000 を入力し、`Connect` をクリックします。

サイドバーに 2 つのエージェントが表示されます :

  • code_search – ワークスペース内のファイルを読み込み、コードベースに関する質問に答えます。

  • web_search – Webを検索し、引用に基づいた回答を生成します。

Try one prompt against each:

  • 「このリポジトリには何が含まれていますか？」→ code_search はディレクトリ一覧を表示し、構造を説明します。

  • 「Anthropic は最近、エージェントについてどのような記事を公開しましたか？」→ web_search は URL を含む概要を返します。

 

What you have now

  • セッション、スケジューリング、50+ エンドポイントを備えた、ポート 8000 ​​で動作する FastAPI ランタイム。

  • セッション、メモリ、トレースを格納する Postgres データベース。

  • 置き換え、拡張、またはパターンとして使用できる 2 つのリファレンスエージェント。

  • 新しいエージェントを構築するための Claude Code プロンプトを含む（複製したリポジトリ内の）docs/ フォルダ。

 

エージェントの作成

Claude Code プロンプトを使用して、新しいエージェントを生成、登録、スモークテストします。

テンプレートリポジトリには、(複製した agent-platform ディレクトリ内) docs/create-new-agent.md に Claude Code プロンプトが公開されていて、これはエージェントの追加に必要な処理を自動的に実行します: agents/ でのファイルの作成、app/main.py への登録、コンテナの再起動、スモークテストの実行。

 

プロンプトの実行

複製した agent-platform リポジトリで Claude Code を開き、以下をペーストします :

Run docs/create-new-agent.md

Claude は以下のように尋ねます :

  1. エージェントは何をすべきですか? 1 行で説明してください。「指定したリポジトリの GitHub issues を要約する」、「受信した Slack メッセージをトリアージする」等。

  2. どんなツールが必要ですか? Agno の 100+ のツールキットから選ぶか、カスタムツールを説明してください。

  3. 特定の指示はありますか? トーン、フォーマット、エスカレーションルール、システムプロンプトに配置するような内容なら何でも。

Claude は agents/<your_agent>.py を生成し、app/main.py にインポートと登録を追加し、`docker compose restart` を実行して、新しいエージェントのエンドポイントにアクセスして応答を確認します。

単純なエージェント (ツールキット 1 つ、カスタムツールなし) の場合は 5～10 分で完了します。カスタムツールを含むオーダーメイドのエージェントの場合は、さらに時間がかかります。

 

AgentOS UI でのテスト

os.agno.com を開き、サイドバーで新しいエージェントを選択し、現実的なプロンプトを試してみてください。以下のテストを実行してください :

  • 推奨ルート。エージェントを設計した目的。

  • エッジ (境界) ケース。通常とは異なる入力、不完全な情報、曖昧な質問。

  • 悪意のある入力。プロンプト・インジェクション、分布外リクエスト、エージェントに意図しない動作をさせようとする試み。

サイドバーの Sessions と Traces をクリックしてください。実行ごとに、メッセージ履歴、ツール呼び出し、タイミングの完全な情報が記録されます。これが次のページの反復ループの基盤となります。

 

What just happened

  • (アクション) エージェント定義 – (着地点) agents/<your_agent>.py

  • 登録 – app/main.py

  • エンドポイント – http://localhost:8000/agents/<your_agent>

  • テスト実行のセッションとトレース – Postgres、AgentOS UI で確認可能

 

エージェントの改良

Claude Code はプラットフォームからコンテナログを読み込み、エージェントを再帰的に改良します。

プラットフォームを独自に管理することのメリットはここにあります。コンテナログ、エージェントコード、実行中のプラットフォーム、そしてイテレーションツールはすべて 1 つのリポジトリに格納されています。Claude Code はそれらのすべてを把握できます。

 

プロンプトの実行

複製した agent-platform リポジトリで Claude Code を開き、以下を貼り付けます :

Run docs/improve-agent.md

Claude は以下の処理を実行していきます :

  1. エージェントを選択します。先ほど作成したエージェント、または指定したエージェントのいずれかを選択します。

  2. 最新のコンテナログを取得します。docker compose ログを読み込み、実行、セッション、ツール呼び出しを確認します。

  3. 失敗 (failure) モードを特定します。ログを精査し、不適切なプロンプト、ツールの選択ミス、指示の欠落、ハルシネーションなどを検出します。

  4. 変更を提案します。エージェントの指示を編集し、ツールを追加または削除し、プロンプトを厳格化し、ガードレールを追加します。

  5. 再実行して検証します。変更後のエージェントを同じプロンプトでテストし、変更前と変更後を比較し、あなたに変更を保持するかどうかを尋ねます。

 

When to run it

  • 一定期間の運用後 (独自テストのみではない場合)

  • 大規模な変更をデプロイする前。

  • エージェントが意図した動作をしていないというユーザーからの報告があった場合。

  • 定期メンテナンスの一環として定期的に実行する場合。

 

評価

定期的に実行される回帰テストでエージェントの動作を固定化しましょう。

評価 (Evals) はエージェントの回帰テストです。同じプロンプト、同じエージェントを使用し、定期的に実行することで、動作がずれた場合にテストが失敗します。

 

ケースの定義

ケースは evals/cases.py にあります。各ケースはプロンプト、それに応答するエージェント、そして回答が満たすべき基準で構成されています。Case は同じファイルの先頭で定義されている dataclass なので、evals/cases.py を開くとすべてが一箇所に表示されます。

evals/cases.py

CASES: tuple[Case, ...] = (
    Case(
        name="web_search_recent_anthropic_research",
        agent=web_search,
        input="What did Anthropic publish about agent research recently?",
        criteria=(
            "Answers the question by citing at least one real Anthropic URL "
            "(anthropic.com domain). The response is grounded in fetched content "
            "rather than refusing to answer."
        ),
        expected_tool_calls=(_WEB_SEARCH_TOOL,),
    ),
    # add more cases here
)

criteria (基準) は LLM 審査員によって採点されます。expected_tool_calls は、エージェントが実際に期待どおりのツールを使用したかどうかを確認します。_WEB_SEARCH_TOOLは、PARALLEL_API_KEY が設定されているかどうかに基づいて、parallel_search（SDK）とweb_search（MCP）を切り替えます。

 

Run the suite

python -m evals

結果は eval_db を介して Postgres に書き込まれます。評価履歴は os.agno.com にセッションやトレースとともに表示されますので、ケースがいつ失敗し始めたのか、何が変更されたのかを確認できます。

 

以上