クイックスタート：コードベースのアプリケーションの作成 - Platform For AI

LangStudio のコードモードを使用すると、Python コードを使用して Agent アプリケーションを構築できます。クラウドでのアプリケーションの作成、デバッグ、デプロイのエンドツーエンドのプロセスをサポートします。このトピックでは、ツール呼び出し、スキル、ストリーミング出力をサポートする Agent アプリケーションを 5 分 未満で作成し、デプロイする方法について説明します。

ステップ 1：アプリケーションの作成とランタイムのアタッチ

まず、アプリケーションを作成し、開発とデバッグのための ランタイム 環境を準備する必要があります。

PAI コンソールにログインします。上部のナビゲーションバーで、中国 (杭州) などのターゲットリージョンを選択します。
左側のナビゲーションウィンドウで、Model Application > Application Development (LangStudio) を選択して、目的のワークスペースに移動します。
Applications タブで、Create Application をクリックし、ドロップダウンリストから Code Mode を選択します。
Create Application ページで、次のパラメーターを設定できます：
- Creation Method: Create from Template を選択し、LLM Basic テンプレートを選択します。
- Name： AI Chat Agent など、アプリケーションの名前を入力します。
- Select Runtime：ランタイムは、ワークフローを実行およびデバッグするために必要なコンピューティング環境であり、その選択はデバッグのための必須ステップです。
  - 既存のランタイム： ドロップダウンリストからランタイムを選択します。
  - アクティブなランタイムなし: New Runtime をクリックして、デフォルト構成でランタイムを作成します。このランタイムは開発およびデバッグフェーズ専用で、最終的にデプロイされるサービスとは独立しています。
  複数のアプリケーションで 1 つのランタイムを共有できます。
- Working Path：これは、ワークフローの設定、ログ、およびデバッグ中に生成される一時ファイルを保存するために使用される OSS バケットパスです。ランタイムを選択すると、対応する作業パスが自動的に読み込まれます。
- Description (任意)：アプリケーションの説明を入力します。
Confirm をクリックすると、システムによって自動的に開発者ページに移動します。

ステップ 2：プロジェクトテンプレートの理解と環境変数の設定

プロジェクトテンプレートの説明

LLM Basic テンプレートは、迅速に開始できるように基本的な Agent プロジェクト構造を提供します。

project/
├── agent.py          # エントリーファイル： FastAPI アプリと API エンドポイントを定義
├── agent_loop.py     # コアロジック： LLM 呼び出しとツール実行ループを処理
├── agui.py           # AG-UI プロトコルのイベントストリーム変換
├── skills.py         # スキルシステム： スキルの検出、読み込み、実行
├── skills/           # スキルディレクトリ
│   ├── get-current-time/
│   └── create-plan/
├── requirements.txt  # Python 依存関係
├── .env              # 環境変数ファイル (手動で作成する必要があります)
└── README.md         # 詳細なドキュメント

agent.py はデフォルトのエントリーファイルです。必ず app という名前のグローバルな FastAPI オブジェクトを提供する必要があります。LangStudio サービスは、サービスを開始するために app オブジェクトを自動的に検出して読み込みます。
サンプルテンプレートの変更および拡張方法については、README.md ファイルをお読みください。

環境変数の設定

このプロジェクトは Alibaba Cloud Model Studio が提供するモデルサービスを使用します。環境変数を介して API キーを提供する必要があります。

プロジェクトのルートディレクトリに .env ファイルを作成します：

DASHSCOPE_API_KEY=your-api-key-here

ランタイムが開始されると、.env ファイルから環境変数が自動的に読み込まれます。

ステップ 3：Agent のデバッグ

デバッグ環境の開始： 開発者ページの右上隅にある [実行] をクリックします。システムが ランタイム 環境を起動し、コードを読み込みます。ランタイムが正常に起動すると、ページの右側にデバッグパネルが表示されます。

API デバッグ

API Debugging タブでは、アプリケーションの API をテストできます。

テストする API (例： POST /) を選択します。
リクエストパラメーターを入力し、リクエストを送信します。

リクエストの例：

{
  "question": "What is the weather like in Beijing today?"
}

期待される応答：

{
  "answer": "The weather in Beijing today is sunny, with temperatures between 10°C and 20°C."
}

チャットパネルでのデバッグ

プラットフォームは、複数ターンのセッションをサポートするビジュアルチャットパネルを提供します：

Chat ページに移動します。
直接質問を入力して会話を開始します。
Agent の応答をリアルタイムで表示します。

チャットパネルは AG-UI プロトコルを使用しており、サービスが /ag-ui エンドポイントをサポートする必要があります。

トレース分析の表示

使用したデバッグ方法に関係なく、プラットフォームは自動的にトレース情報を記録します：

リクエスト期間：各ステージにかかった時間。
LLM 呼び出しの詳細：モデルパラメーターとトークン使用量。
ツール呼び出しの記録：呼び出されたツールとその返された結果。
エラーメッセージ：エラー発生時の詳細なスタックトレース。

ログの表示

コードで例外が発生した場合は、[実行] ページでワーカーログを表示して問題をトラブルシューティングできます。

ステップ 4：サービスのデプロイ

開発とデバッグが完了したら、アプリケーションを安定的でスケーラブルなオンラインサービスとしてデプロイできます。

開発者ページの右上隅で、Deploy をクリックします。
表示される設定ダイアログボックスで、デプロイリソース、サービス名、VPC、その他の情報を設定します。このプロセスにより、FastAPI アプリケーションが PAI-EAS オンラインサービスにパッケージ化されます。
重要
アプリケーションで使用される Alibaba Cloud Model Studio の大規模モデルサービスには、パブリックネットワークアクセスが必要です。デフォルトでは、EAS サービスにはパブリックネットワークアクセスがありません。したがって、サービスをデプロイする際には、パブリックネットワークにアクセスできる VPC と vSwitch を必ず設定する必要があります。これには通常、NAT Gateway の関連付けが必要です。そうしないと、サービスの呼び出しが失敗します。詳細については、「EAS からパブリックまたはプライベートネットワークリソースへのアクセス」をご参照ください。
[デプロイメントフロー] ページで、デプロイ内容が期待どおりであることを確認し、Submit deployment をクリックします。
デプロイには 5〜10 分かかる場合があります。デプロイが完了したら、右上隅の Go to EAS をクリックして、EAS サービスの製品ページに移動します。
Overview タブの Basic Information セクションで、View Endpoint Information をクリックして、エンドポイントと認証トークンを取得します。

リクエストの例：

# <EAS_ENDPOINT> と <EAS_TOKEN> をご利用のサービスエンドポイントと認証トークンに置き換えてください。
curl -X POST '<EAS_ENDPOINT>' \
  -H 'Authorization: Bearer <EAS_TOKEN>' \
  -H "Content-Type: application/json" \
  -d '{"question": "What is the weather like in Beijing today?"}'

サービスの製品ページでモニタリング機能とトレース分析機能を使用して、サービスのパフォーマンスメトリックとすべてのリクエストの詳細なトレースをリアルタイムで表示できます。

ステップ 5：Agent のカスタマイズ

LLM-Basic テンプレートに基づいて、Agent のロジックをカスタマイズできます。以下のセクションでは、最も一般的なカスタマイズ方法について説明します。

1. Agent のペルソナまたはシステムプロンプトの変更

目的： Agent のロール、動作、応答スタイルを定義します。

agent.py の to_messages() メソッドを編集します：

def to_messages(self) -> list:
    return [
        {"role": "system", "content": "あなたはプロの旅行計画アシスタントです。回答は簡潔で、実行可能で、チェックリスト形式で提示する必要があります。"},
        {"role": "user", "content": self.question},
    ]

2. カスタムツール (Function Calling) の追加

目的： Agent が外部 API を呼び出したり、天気の照会やデータベースからのデータ取得など、特定のコードロジックを実行できるようにします。

ツール関数の定義： agent.py ファイルで、標準の Python 関数を定義します。

関数名はツール名としてモデルに公開されます。
パラメーターの型アノテーションにより、ツールスキーマが自動的に生成されます。
async def 非同期関数をサポートします。

# agent.py にツール関数を追加
def geocode(city: str) -> str:
    """都市の地理座標を取得します。"""
    # これを実際の API 呼び出しに置き換えます
    return '{"lat": 39.9042, "lng": 116.4074}'

# agent_loop を呼び出す際に関数のリストを渡します
async for chunk in agent_loop(req.to_messages(), [get_weather, geocode]):
    ...

ツールの登録： agent.py の API エンドポイントで、定義したツール関数のリストを agent_loop に渡します。

# agent.py の FastAPI ルート内

@app.post("/")
async def query(req: QueryRequest) -> QueryResponse:
    # ツール関数のリストを agent_loop に渡します
    tools = [get_weather, geocode]
    async for chunk in agent_loop(req.to_messages(), tools=tools):
        # ...

3. スキルの追加

スキルは、複雑な操作命令やスクリプトを整理するために使用されます。

スキルディレクトリとファイルの作成： skills/ ディレクトリに、新しいスキル用のサブディレクトリ (例： my-skill) を作成します。このディレクトリには、スキルの目的と使用方法をモデルに説明する SKILL.md ファイルを含める必要があります。
```
skills/
  └── my-skill/
      ├── SKILL.md      # 必須： スキル定義ファイル
      └── scripts/      # 任意： このスキルによって実行されるスクリプトを保存
          └── run.py
```

スキル定義ファイルの作成： SKILL.md ファイルには、メタデータと詳細な命令が含まれています。以下に例を示します：

---
name: my-skill
description: ユーザーが特定のタスクを実行する必要がある場合、このスキルを使用します。
---

# マイスキル

## ゴール
スキルが何をするかを 1 文で説明します。

## 命令
詳細な操作命令...

Agent はシステムプロンプトで利用可能なスキルのリストを確認し、組み込みの load_skill_file および execute_script ツールを使用してスキルを利用します。