快速開始：建立代碼型應用 - Platform For AI

LangStudio 代碼模式允許使用 Python 代碼構建 Agent 應用，支援在雲上完成建立、調試到部署的全流程。本文將在5分鐘內完成一個支援工具調用/Skills/流式輸出的 Agent 應用的建立和部署。

步驟一：建立應用並綁定運行時

首先，您需要建立一個應用，並為其準備一個用於開發調試的運行時環境。

登入PAI 控制台，在頁面上方選擇目標地區，如華東1（杭州）。
在左側導覽列選擇模型应用 > 大模型应用开发（LangStudio），並進入目標工作空間。
在应用頁簽，單擊新建应用，在下拉式清單中選擇代码模式。
在新建应用頁面，配置以下參數：
- 新建方式：選擇从模板新建，並選擇LLM Basic 模板。
- 名称：為應用命名。例如，智能問答Agent。
- 选择运行时：運行時是執行和調試工作流程所需的計算環境，是進行後續調試的必要步驟。
  - 已有運行時：從下拉式清單中選擇一個。
  - 無可用運行時：單擊新建运行时，使用預設配置建立一個。運行時僅用於開發調試階段，與最終部署的服務無關。
  一個運行時可以同時被多個應用使用。
- 工作路径：此路徑（一個 OSS Bucket 路徑）用於存放工作流程的配置、日誌和調試過程中產生的臨時檔案。選擇運行時後，會自動載入運行時的工作路徑。
- 描述（可選）：填寫應用的用途說明。
單擊确定。系統將自動跳轉到開發頁面。

步驟二：理解專案模板並配置環境變數

專案模板說明

LLM Basic 模板提供了一個基礎的 Agent 專案結構，協助您快速開始。

project/
├── agent.py          # 入口檔案：定義 FastAPI app 和 API 介面
├── agent_loop.py     # 核心邏輯：處理 LLM 調用、工具執行迴圈
├── agui.py           # AG-UI Protocol 事件流轉換
├── skills.py         # 技能系統：發現、載入和執行技能
├── skills/           # 技能目錄
│   ├── get-current-time/
│   └── create-plan/
├── requirements.txt  # Python 依賴
├── .env              # 環境變數檔案（需手動建立）
└── README.md         # 詳細文檔

agent.py 是預設的入口檔案，必須提供一個全域的 FastAPI 對象，命名為 app。LangStudio服務會自動識別並載入 app 對象來啟動服務。
可通過README.md瞭解模板樣本，進行修改和擴充。

配置環境變數

專案使用阿里雲百鍊提供的模型服務，需通過環境變數提供API-KEY。

在專案根目錄建立 .env 檔案：

DASHSCOPE_API_KEY=your-api-key-here

運行時啟動時會自動載入 .env 檔案中的環境變數。

步驟三：調試 Agent

啟動調試環境：在開發頁面右上方單擊運行按鈕，系統將啟動運行時環境並載入您的代碼。啟動成功後，頁面右側將彈出調試面板。

API調試

在API调试頁簽，可以直接測試應用的 API。

選擇要測試的介面，如 POST /。
填寫請求參數並發送。

樣本請求：

{
  "question": "北京今天的天氣如何？"
}

預期響應：

{
  "answer": "北京今天天氣晴朗，氣溫在 10°C 到 20°C 之間。"
}

對話面板調試

平台提供了可視化的對話面板，支援多輪會話：

切換到对话頁面。
直接輸入問題進行對話
即時查看 Agent 的響應。

對話面板使用 AG-UI Protocol，需要服務支援 /ag-ui 介面。

查看鏈路追蹤

無論使用哪種調試方式，平台都會自動記錄鏈路追蹤資訊：

請求耗時：各階段耗時統計
LLM 調用詳情：模型參數、Token 用量
工具調用記錄：調用的工具及返回結果
錯誤資訊：出錯時的詳細堆棧

查看日誌

當代碼出現異常時，可在運行頁面查看 Worker 日誌進行問題排查。

步驟四：部署服務

完成開發和調試後，您可以將應用部署為穩定、可擴充的線上服務。

在開發頁面右上方，單擊部署。
在彈出的配置頁面中，配置部署的資源、服務名稱、VPC等資訊。這本質上是將您的 FastAPI 應用程式打包成一個 PAI-EAS 線上服務。
重要
由於應用中阿里雲百鍊大模型服務需要通過公網訪問，而 EAS 服務預設不具備公網訪問能力。因此，在部署時，必須為服務配置一個可訪問公網的 VPC 和交換器（通常需要關聯 NAT Gateway），否則服務將調用失敗。參見EAS訪問公網或內網資源。
在跳轉的部署流程頁面，檢查部署內容符合預期後，單擊提交部署。
等待部署完成後（此過程可能需要5-10分鐘），單擊右上方跳转到 EAS，進入 EAS 服務詳情頁。
在概览頁簽，單擊基本信息地區的查看调用信息可擷取訪問地址和認證 Token。

普通請求樣本：

# 請將<EAS_ENDPOINT> 和 <EAS_TOKEN> 替換為您的服務地址和認證Token
curl -X POST '<EAS_ENDPOINT>' \
  -H 'Authorization: Bearer <EAS_TOKEN>' \
  -H "Content-Type: application/json" \
  -d '{"question": "北京今天的天氣如何？"}'

通過服務詳情頁提供的監控與鏈路追蹤功能，可以即時查看服務的效能指標和所有請求的詳細鏈路。

步驟五：自訂你的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 函數。

函數名會作為工具名暴露給模型
參數類型標註會自動產生工具 schema
支援 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）

技能用於組織複雜的操作指令和指令碼。

建立技能目錄和檔案：在 skills/ 目錄下為您的新技能建立一個子目錄，例如 my-skill。在該目錄中，必須包含一個 SKILL.md 檔案，用於向模型描述該技能的用途和使用方法。
```
skills/
  └── my-skill/
      ├── SKILL.md      # 必需：技能定義檔案
      └── scripts/      # 可選：存放該技能要執行的指令碼
          └── run.py
```

編寫技能定義檔案：SKILL.md 包含中繼資料和詳細說明。樣本如下：

---
name: my-skill
description: 當使用者需要執行某個特定任務時使用該技能。
---

# My Skill

## 目標
用一句話描述技能要做什麼。

## 使用說明
詳細的操作指令...

Agent 會在系統提示詞中看到可用技能列表，並通過內建工具 load_skill_file 和 execute_script 來使用技能。