Skip to main content
高代码应用

API Development Guide

This document explains how to develop, upload, and deploy high-code application APIs from scratch using AgentScope-AI.

Environment Setup

The Python development environment requires python >= 3.10. To upload and deploy Python code to Alibaba Cloud Bailian and install the required AgentScope-AI dependencies for uploading code packages to Alibaba Cloud Bailian: 
pip install agentscope-runtime==1.0.0
pip install "agentscope-runtime[deployment]==1.0.0"

Development Guidelines

The Python backend program must expose a GET /health endpoint. If this endpoint is unreachable, Bailian will consider the service startup as failed. 
@app.get("/health")
def health_check():
  return "OK"
The entry file of the Python backend program must be named main.py. The default path for the chat interface is /process. Refer to the Agent API Protocol Specification for protocol details. Reference implementation package: mcp_server_with_chat.zip.

Application Observability Integration

By using the @trace decorator provided by the agentscope-runtime package, logs are automatically reported and execution durations are measured. Example decorator for LLM function calls: 
from agentscope_runtime.engine.tracing import trace, TraceType
@trace(trace_type=TraceType.LLM, trace_name="llm_func")
def llm_func():
    pass
Example output: 
{"time": "2025-08-13 11:23:41.808", "step": "llm_func_start", "model": "", "user_id": "", "code": "", "message": "", "task_id": "", "request_id": "", "context": {}, "interval": {"type": "llm_func_start", "cost": 0}, "ds_service_id": "test_id", "ds_service_name": "test_name"}
{"time": "2025-08-13 11:23:41.808", "step": "llm_func_end", "model": "", "user_id": "", "code": "", "message": "", "task_id": "", "request_id": "", "context": {}, "interval": {"type": "llm_func_end", "cost": "0.000"}, "ds_service_id": "test_id", "ds_service_name": "test_name"}
For advanced features such as custom log reporting, streaming-output function support, or setting common log attributes, refer to the Tracing module in AgentScope-runtime. When uploading a pre-built .whl package using AgentScope-AI, add the --telemetry enable flag to activate observability. 
runtime-fc-deploy --deploy-name My First High-Code App --whl-path <PATH_TO_YOUR_NEW_WHL_FILE> --telemetry enable
After deployment, visit the Alibaba Cloud Bailian Application Observability page to view collected telemetry data. At the top of the Application Observability page, summary metrics are displayed — including total invocation count, total LLM tokens consumed, average latency, and average time-to-first-byte. Below, a detailed invocation table lists columns such as node type, name, input, output, invocation time, latency, token count, and status — enabling inspection of each invocation’s details and runtime state.

Application Upload

Obtain and configure the following environment variables (Linux example shown):
  • Obtain your Alibaba Cloud AccessKey (AK and SK) for authentication during package upload.
  • (Optional) Obtain your Alibaba Cloud Bailian Workspace ID (starts with llm-) to specify the Bailian workspace where the high-code application will be deployed. If not set, the default workspace is used.
Configure these values as environment variables: 
export ALIBABA_CLOUD_ACCESS_KEY_ID=LTAI************            # Replace with your Alibaba Cloud AccessKey (AK)
export ALIBABA_CLOUD_ACCESS_KEY_SECRET=****************        # Replace with your Alibaba Cloud SecretKey (SK)
export MODELSTUDIO_WORKSPACE_ID=llm-****************           # Optional: replace with your Bailian workspace ID; if unset, default workspace is used
Use AgentScope-AI to upload your built .whl package and automatically deploy it to Alibaba Cloud Bailian. The --telemetry enable flag enables observability capabilities and must be used alongside AgentScope’s Tracing module during application development. 
runtime-fc-deploy --deploy-name My First High-Code App --whl-path <PATH_TO_YOUR_NEW_WHL_FILE> --telemetry enable
Upon successful deployment, the following information is printed: application name, Bailian workspace, console URL for accessing the application, and application ID. 
Built wheel at: /Users/<username>/Desktop/workspace/develop/.agentscope_runtime_builds/build-<build_id>/dist/agentdev_starter_36a13f34-0.1.17
Artifact URL: https://tmp-code-deploy-<workspace>.oss-cn-hangzhou.aliyuncs.com/agentdev_starter_36a13f34-0.1.1758618690-py3-none-any.whl?x-oss-expires=...
Resource Name: My First Bailian High-Code App
Workspace: llm-<workspace_id>
Deploy Result
Console URL: https://agent.console.aliyun.com/flow-agent/app-center
Deploy ID: <deploy_id>
Navigate to Alibaba Cloud Bailian → Application Management, and wait for the application to be published. Once published, minimal usage fees apply (less than ¥0.1/hour), depending on deployment duration.

Application Testing

We recommend navigating to Alibaba Cloud Bailian → Application Management, then testing your application and reviewing build, deployment, and invocation logs on the application detail page.

Application Updates

When updating a high-code application, use the AgentScope-AI update command to re-upload the .whl package. Upon successful upload, the application is automatically updated and redeployed. Go to Alibaba Cloud Bailian → Application Management, and copy the application ID. Locally, run the following command to upload your updated local .whl package: After the update, the application is rebuilt and redeployed. 
runtime-fc-deploy --update <HIGH_CODE_APP_ID> --whl-path <PATH_TO_YOUR_NEW_WHL_FILE>
Update success example: 
% runtime-fc-deploy --update d8a48e627a6d49338faef50fdfaf2ef9 --whl-path ./agentdev_starter_e61c4e2f-0.1.0-py3-none-any.whl
INFO:agentscope_runtime.engine.deployers.modelstudio_deployer:Uploading wheel to OSS and generating presigned URL
INFO:agentscope_runtime.engine.deployers.modelstudio_deployer:Triggering ModelStudio Full-Code deploy for None
Built wheel at: /Users/lekayef/Desktop/test/agentdev_starter_e61c4e2f-0.1.0-py3-none-any.whl
Artifact URL: https://tmp-code-deploy-llm-enpaqbwxdsmnlfpq.oss-cn-hangzhou.aliyuncs.com/agentdev_starter_e61c4e2f-0.1.0-py3-none-any.whl?x-oss-signature-version=OSS4-HMAC-SHA256&x-oss-date=20250922T085339Z&x-oss-expires=10799&x-oss-credential=Lxxx%2Fcn-hangzhou%2Foss%2Faliyun_v4_request&x-oss-signature=bcc5a28772d234790619a2b3da22a9a8f4e6f179e36d6f1e7cecaaa026463d45
Deploy ID: 44ccb27c-2918-4a64-aa6a-8a0970d88ffb
Resource Name: None
Workspace: llm-enpaqbwxdsmnlfpq
Console Url: https://pre-bailian.console.aliyun.com/?tab=app#/app-center/high-code-detail/d8a48e627a6d49338faef50fdfaf2ef9

Frequently Asked Questions

Minimal RAM Account Permissions

To grant minimal permissions to a RAM account for high-code application usage, create a custom permission policy based on the following rules: 
{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "sfm:ApplyTempStorageLease",
        "fc:ListTriggers",
        "fc:GetFunction",
        "fc:GetFunctionCode",
        "fc:UpdateFunction",
        "log:GetProject",
        "log:GetLogStore",
        "log:GetIndex"
      ],
      "Resource": "*"
    }
  ]
}

How to Troubleshoot Upload Failures?

  • Verify that your Alibaba Cloud AK/SK and Bailian Workspace ID belong to the same Alibaba Cloud account.
  • Ensure you have previously deployed a high-code application via the Bailian console — doing so guides you through enabling required Alibaba Cloud permissions and resources.
  • Try using a clean python >= 3.10 environment — e.g., create an isolated virtual environment using Python’s venv: Create environment: 
    python --version
python -m venv venv
    Activate environment: 
    # Linux / macOS
source venv/bin/activate
# Windows (CMD)
venv\Scripts\activate.bat
# Windows (PowerShell)
venv\Scripts\Activate.ps1
  • If upload fails with error "RAM user is not assigned to any workspace in Bailian", contact the Alibaba Cloud root account owner to perform the following:
    • In the RAM console, assign the AliyunBailianDataFullAccess permission to the RAM user (sub-account).
    • In the Bailian account management page, grant the RAM user Agent – Operation permissions for the specific workspace.

Why Does the Console Show “Deploying…” Indefinitely (>5 Minutes) or Report Deployment Failure?

  • The GET /health endpoint of your Python backend is unreachable, causing Bailian to treat startup as failed.
  • The Python backend entry file is not named main.py.
You can inspect detailed runtime logs on the high-code application detail page.

How to Avoid Build Failures Caused by Dependency Updates?

In requirements.txt, use == to pin dependency versions — avoid range constraints like >=, which may pull inconsistent versions across builds and cause behavioral drift or failures. Examples: 
# Recommended: pinned versions ensure consistent builds
flask==3.0.3
dashscope==1.20.14

# Not recommended: range constraints risk breaking builds due to dependency updates
flask>=3.0.0
dashscope>=1.20.0
After local debugging succeeds, use pip freeze to export exact versions currently installed: 
pip freeze > requirements.txt

Why Does the API Return “Invalid API-key Provided”?

This indicates the Bailian API Key is not correctly configured in your high-code application’s environment variables. For instructions on obtaining the API Key, see: [Obtain API Key].
Overview
Getting Started
Applications
Prompt
Plugins
Task Center
Components
Invocation
Permissions
Changelog