TrueFoundryへのAgnoエージェントのデプロイ

このガイドでは、 Agno エージェントをTrueFoundryにデプロイする方法をご紹介します。TrueFoundryは、DevOpsやMLOpsの専門知識が最小限でAIデプロイメントを簡素化するように設計されたプラットフォームです。TrueFoundryは、インフラ管理、スケーリング、監視を自動化し、デプロイの複雑さに煩わされることなく、インサイトの導出に集中できるようにします。数回クリックするだけで、自然言語のリクエストをSQLクエリや動的なグラフに変換でき、データ探索をシームレスかつインテリジェントにします。手動でのクエリは不要です！

直接お試しになりたい場合は、TrueFoundryプラットフォームにアクセスし、「Live Demos」と「agno-Streamlit」に移動してください。エージェントワークフローのライブデモをご覧いただけます。

アーキテクチャ概要

このプロジェクトは、連携して動作するいくつかの主要なコンポーネントで構成されています。

クエリ・エージェント

• 自然言語理解にGPT-4oを使用
• ClickHouse向けに適切なSQLクエリを生成
• 事前設定されたデータベースに対してSQLクエリを実行
• データを表形式で返し、可視化エージェントへの入力とする

可視化エージェント：2番目のAIエージェントで、

• データに基づいて最適な可視化タイプを決定
• matplotlib/seabornを使用してプロットを生成
• 可視化のフォーマットとスタイルを処理

FastAPIバックエンド：RESTful APIで、

• agno を使用してエージェント間の連携を調整
• 非同期ジョブ処理を管理
• プロット画像と結果を提供

Streamlit フロントエンド：ユーザーインターフェースで、

• 直感的なクエリインターフェースを提供
• リアルタイムの処理状況を表示
• インタラクティブな可視化を表示

データフロー

ユーザーはStreamlitを通じて自然言語クエリを送信します。

• クエリエージェントは、agnoとGPT-4oを使用してClickHouse用のSQLクエリを生成します。
• ClickHouseデータベースに対してSQLクエリを実行します。
• 結果は表形式で返され、可視化エージェントへの入力となります。
• 可視化エージェントは可視化を生成し、表示用の画像を返します。

はじめに

リポジトリをクローンする

まず、 TrueFoundry Getting Started Examples リポジトリに移動し、クローンします。

git clone <https://github.com/truefoundry/getting-started-examples.git>

agno Plot Agent ディレクトリに移動します。

cd getting-started-examples/plot_agent/agno_plot_agent

環境設定

仮想環境を作成し、アクティブ化します。

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

依存関係をインストールします。

pip install uv
uv install

環境変数の設定

を新規作成します。 .env ファイル:

# Truefoundry LLMGateway Configuration if using Truefoundry LLM Gateway for calling models
LLM_GATEWAY_BASE_URL=your_llm_gateway_base_url_here
LLM_GATEWAY_API_KEY=your_llm_gateway_api_key_here

# OPENAI API Configuration if not using Truefoundry LLM Gateway
OPENAI_API_KEY=<your_openai_api_key_here>

CLICKHOUSE_HOST=your_clickhouse_host
CLICKHOUSE_PORT=443
CLICKHOUSE_USER=your_user
CLICKHOUSE_PASSWORD=your_password
CLICKHOUSE_DATABASE=default
agno_VERBOSE=true

‍
注: TrueFoundry LLM Gatewayを使用する場合、モデルIDの形式は provider-name/model-name (例: openai-main/gpt-4o)となります。 .env ファイルに、環境設定セクションに示されている正しいLLM Gateway認証情報が含まれていることを確認してください。

ClickHouseの認証情報を取得するには、 ClickHouseでアカウントを作成し、サインインしてサービスを作成します。サービスをクリックすると、左サイドバーの中央に接続ボタンが表示されます。これをクリックすると、以下に示す認証情報が表示されます。ファイルをアップロードしてデータベースを作成するか、定義済みのものを使用できます。

Agnoエージェントの実装

from agno.agent import Agent
from agno.models.openai import OpenAIChat
from plot_tools import PlotTools
from query_tools import QueryTools
import os
# Query Agent for SQL generation - Using TrueFoundry LLM Gateway
sql_agent: Agent = Agent(
                        model=OpenAIChat(
                            id="openai-main/gpt-4o",  # Format: provider-name/model-name
                            api_key=os.getenv("LLM_GATEWAY_API_KEY"),
                            base_url=os.getenv("LLM_GATEWAY_BASE_URL")
                        ),
                        description="",
                        instructions=[],
                        tools=[ClickHouseTools()],
                        show_tool_calls=True,
                        markdown=True,
                        response_model=SQLQueryResult,
                        structured_outputs=True,
                        )
# Visualization Agent - Using TrueFoundry LLM Gateway
plot_agent: Agent = Agent(
                          model=OpenAIChat(
                              id="openai-main/gpt-4o",
                              api_key=os.getenv("LLM_GATEWAY_API_KEY"),
                              base_url=os.getenv("LLM_GATEWAY_BASE_URL")
                          ),
                          description="",
                          instructions=[],
                          tools=[PlotTools()],
                          markdown=True,
                          response_model=VisualizationRequest,
                          structured_outputs=True,
                          )

サービスの実行

agnoワークフローを起動

agno run

FastAPIバックエンドを起動:

python api.py

Streamlit UIを起動 (新しいターミナル):

streamlit run app.py

TrueFoundryでのデプロイ

前提条件

TrueFoundry CLIをインストール:

pip install -U "truefoundry"

TrueFoundryにログイン:

tfy login --host "<https://app.truefoundry.com>"

デプロイ手順

1. TrueFoundryのデプロイセクションに移動します。

2. 下部にあるサービスをクリックします。
3. クラスターワークスペースを選択します。
4. ラップトップ、GitHub、またはDockerからデプロイできます。ラップトップからデプロイする場合は、上記の前提条件が完了していることを確認してください。
5. TrueFoundryプラットフォームはdeploy.pyファイルを生成し、プロジェクトに追加します。このファイルを編集して環境変数を追加する必要があります。生成されたファイル内のenvセクションを見つけて、資格情報を追加してください:
6. 生成された deploy.py を編集し、 env セクション:

env={
    "OPENAI_API_KEY": "your_openai_api_key",
    "CLICKHOUSE_HOST": "your_clickhouse_host",
    "CLICKHOUSE_PORT": "443",
    "CLICKHOUSE_USER": "your_user",
    "CLICKHOUSE_PASSWORD": "your_password",
    "CLICKHOUSE_DATABASE": "default",
    "AGNO_VERBOSE": "true"
},

デプロイのテスト

テストクエリを送信:

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"query": "Show me the cost trends by model over the last week"}' \
  <https://agno-plot-agent-demo-8000.aws.demo.truefoundry.cloud/query>

成功レスポンス例:

{
  "job_id": "1234-abcd-5678-efgh"
}

APIエンドポイント

• クエリを送信:

curl -X POST <http://localhost:8000/query> -H "Content-Type: application/json" -d '{"query": "Your query here."}'

• クエリステータスの確認:

curl -X GET <http://localhost:8000/status/{job_id}>

• プロット画像の取得:

curl -X GET <http://localhost:8000/plot/{job_id}> > plot.png

フロントエンドとCORS

FastAPIでのCORS設定:

from fastapi.middleware.cors import CORSMiddleware

app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

Streamlitでの環境変数の定義:

import os

FASTAPI_ENDPOINT = os.getenv("FASTAPI_ENDPOINT", "<http://localhost:8000>")

デプロイ後の注意事項

• StreamlitからFastAPIへのAPI接続をテストする。
• Streamlitの .env ファイルをFastAPIエンドポイントで更新する。
• CORS設定がStreamlitからのリクエストを許可していることを確認する。

TrueFoundryを通じてデプロイメントを監視および管理するには、以下を行います。

• ログの表示
• リソース使用状況の監視
• オートスケーリングルールの設定
• バックエンドのヘルスチェック（/health)、APIドキュメント (/docs)、およびメトリクスは /metrics

エージェントにトレースを追加する

トレース機能は、エージェントが実行される際に内部で何が起こっているかを理解するのに役立ちます。Truefoundryのトレース機能を使用すると、わずかなコードを追加するだけで、エージェントの実行パス、行われたツール呼び出し、使用されたコンテキスト、発生したレイテンシーを把握できます。

以下をインストールする必要があります

 pip install traceloop-sdk

その後、トレースを有効にするために必要な環境変数を追加します

"TRACELOOP_BASE_URL": "<your_host_name>/api/otel" # "https://internal.devtest.truefoundry.tech/api/otel"
"TRACELOOP_HEADERS"="Authorization=Bearer%20<your_tfy_api_key>"

エージェントを定義しているコードベースでは、トレースを有効にするためにこれらの行を追加するだけです。

from traceloop.sdk import Traceloop
from traceloop.sdk.decorators import workflow, agent, task
Traceloop.init(app_name="agno")

次に、エージェントとワークフローに以下のようにデコレーターを追加します

@agent(name="sql_and_plot_workflow")
@workflow(name="plotting workflow")
@task(name="execute sql query")

これらの手順で、あなたのagnoエージェントワークフローはTrueFoundryに正常にデプロイされました！