エージェントプラットフォームのための最も効率的で最小限の基盤 : エージェントの構築と改善を支援する 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?

エージェントプラットフォーム・テンプレートは、エージェントプラットフォーム用の基盤となるコードベースです。ポート 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）が含まれます。

要件

Docker Desktop ( インストール )
OpenAI API キー

ローカルで実行

テンプレートの複製

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

環境の設定
```
cp example.env .env
```
Open .env and set OPENAI_API_KEY. Everything else has sensible defaults.
プラットフォームの起動
```
docker compose up -d --build
```
FastAPI アプリケーションと Postgres データベースの2つのコンテナが起動します。初回起動時にはベースイメージが pull され、コンテナが構築されます。以降の起動は瞬時に行われます。
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 行で説明してください。「指定したリポジトリの GitHub issues を要約する」、「受信した Slack メッセージをトリアージする」等。
どんなツールが必要ですか? Agno の 100+ のツールキットから選ぶか、カスタムツールを説明してください。
特定の指示はありますか? トーン、フォーマット、エスカレーションルール、システムプロンプトに配置するような内容なら何でも。

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 は以下の処理を実行していきます :

エージェントを選択します。先ほど作成したエージェント、または指定したエージェントのいずれかを選択します。
最新のコンテナログを取得します。docker compose ログを読み込み、実行、セッション、ツール呼び出しを確認します。
失敗 (failure) モードを特定します。ログを精査し、不適切なプロンプト、ツールの選択ミス、指示の欠落、ハルシネーションなどを検出します。
変更を提案します。エージェントの指示を編集し、ツールを追加または削除し、プロンプトを厳格化し、ガードレールを追加します。
再実行して検証します。変更後のエージェントを同じプロンプトでテストし、変更前と変更後を比較し、あなたに変更を保持するかどうかを尋ねます。

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 にセッションやトレースとともに表示されますので、ケースがいつ失敗し始めたのか、何が変更されたのかを確認できます。

以上

月	火	水	木	金	土	日
				1	2	3
4	5	6	7	8	9	10
11	12	13	14	15	16	17
18	19	20	21	22	23	24
25	26	27	28	29	30	31