Skip to main content

API Development Guide

This guide shows you how to develop, upload, and deploy an API service for a full-code application from scratch by using AgentScope-AI.

image

Prerequisites

  1. You need a Python development environment with python >= 3.10.
  2. To upload and deploy your Python package to Alibaba Cloud Model Studio, install the AgentScope-AI dependencies:
pip install agentscope-runtime==1.0.0
pip install "agentscope-runtime[deployment]==1.0.0"

Development specifications

  1. The Python backend application must provide a GET /health endpoint. If this endpoint is not reachable, Model Studio will consider the application startup failed.
@app.get("/health")
def health_check():
    return "OK"
  1. The entry file for the Python backend application must be main.py.
  2. The default path for the chat interface is /process. For protocol details, see the Agent API Protocol Specification.
  3. Reference code package: mcp_server_with_chat.zip.

Application observability

Use the @trace decorator provided by the AgentScope-runtime package to automatically report logs and collect timing metrics. The following example shows a decorator for a function that calls a large language model: 
from agentscope_runtime.engine.tracing import trace, TraceType
@trace(trace_type=TraceType.LLM, trace_name="llm_func")
def llm_func():
  pass
Sample 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 custom log reporting, support for streaming output functions, or setting common log attributes, see the AgentScope-runtime Tracing module.
  • When uploading a pre-built .whl package by using AgentScope-AI, add the --telemetry enable flag to enable Application Observability.
runtime-fc-deploy --deploy-name my-first-full-code-app  --whl-path <PATH_TO_YOUR_NEW_WHL_FILE> --telemetry enable
After the application is running, you can view the collected information on the Alibaba Cloud Model Studio > Application Observability page. The Application Observability page displays a statistical overview at the top, including the number of calls, total LLM tokens, average latency, and average time to first byte. Below this overview is a call records table with details for each call. The columns include node type, name, input, output, call time, latency, token count, and status.

Application upload

  1. Obtain and configure the following environment variables. The example shows the Linux syntax:
    1. Obtain an Alibaba Cloud AccessKey (AK and SK) to authenticate package uploads.
    2. (Optional) Obtain an Alibaba Cloud Model Studio workspace ID. This ID, which starts with llm-, specifies the workspace where the full-code application will be stored. If not set, the default workspace is used.
    3. Set the following environment variables to the values you obtained:
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 Model Studio workspace ID. This workspace will deploy the full-code application. If not set, the default workspace is used.
  1. Use AgentScope-AI to upload the built .whl package. The package is then automatically deployed to Alibaba Cloud Model Studio.
    The --telemetry enable flag enables observability and requires developing your application with the AgentScope Tracing module. 
runtime-fc-deploy --deploy-name "My First Full-Code App"  --whl-path <PATH_TO_YOUR_NEW_WHL_FILE> --telemetry enable
After a successful deployment, the output displays the application name, Model Studio workspace, console URL, 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 Model Studio Full-Code Application
Workspace: llm-<workspace_id>
Deploy Result
Console URL: https://bailian.console.aliyun.com/?tab=app#/app-center
Deploy ID: <deploy_id>
  1. Go to Alibaba Cloud Model Studio > Application Management and wait for the application to be published. After the application is published, you will incur minimal charges based on the deployment duration (less than 0.1 CNY/hour).

Application testing

We recommend that you go to Alibaba Cloud Model Studio > Application Management. On the application details page, you can test the application and view build, deployment, and invocation logs.

Application update

When you need to update a full-code application, use the AgentScope-AI update command to upload the new .whl package. After the package is successfully uploaded, the full-code application is automatically updated and redeployed.
  1. Go to Alibaba Cloud Model Studio > Application Management and copy the application ID.
  2. Run the following command locally to upload the updated local .whl package.
    After the update, the application is rebuilt and redeployed. 
runtime-fc-deploy --update <FULL_CODE_APP_ID> --whl-path <PATH_TO_YOUR_NEW_WHL_FILE>
Update successful. 
% 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/<username>/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=YOUR_ACCESS_KEY_ID&x-oss-signature=YOUR_SIGNATURE
Deploy ID: 44ccb27c-2918-4a64-aa6a-8a0970d88ffb
Resource Name: None
Workspace: llm-enpaqbwxdsmnlfpq
Console Url: https://bailian.console.aliyun.com/?tab=app#/app-center/high-code-detail/d8a48e627a6d49338faef50fdfaf2ef9

FAQ

Least privilege for RAM accounts

To grant a RAM account least privilege to use a full-code application, create a custom 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": "*"
    }
  ]
}

Troubleshooting upload failures

  1. Check that the Alibaba Cloud AK/SK and the Alibaba Cloud Model Studio workspace ID belong to the same Alibaba Cloud account.
  2. Ensure that you have deployed a full-code application at least once from the Model Studio console. This initial deployment guides you through enabling the necessary Alibaba Cloud permissions and resources.
  3. Try using a clean python >= 3.10 environment. For example, create a clean virtual environment using the Python venv command:
    1. Create the environment:
python --version
python -m venv venv
  1. Activate the environment:
# Linux / macOS
source venv/bin/activate
# Windows (CMD)
venv\Scripts\activate.bat
# Windows (PowerShell)
venv\Scripts\Activate.ps1
  1. If you encounter the error "RAM user is not assigned to any workspace in Bailian" during upload, ask the Alibaba Cloud account owner to do the following:
    1. You can use an Alibaba Cloud account to grant the AliyunBailianDataFullAccess permission to a sub-account (RAM user) in the RAM console.
    2. On the Model Studio Account Management page, grant the Agent-Operation permission to the RAM user for a specific workspace.

Deployment stuck or failed

  1. The GET /health endpoint of the Python backend application is unreachable. This causes Model Studio to determine that the startup has failed.
  2. The entry file for the Python backend application must be main.py.
  3. Go to the application details page for your full-code application to view detailed runtime logs.

Preventing build failures from dependency updates

We recommend pinning dependency versions in your requirements.txt file by using == and avoiding range operators like >=. Using >= can cause each build to pull different dependency versions, which can lead to inconsistent application behavior or build failures. Example: 
# Recommended: Pin versions to ensure consistent builds.
flask==3.0.3
dashscope==1.20.14

# Not recommended: Range operators can cause build failures if dependencies update.
flask>=3.0.0
dashscope>=1.20.0
After you finish local debugging, you can run the pip freeze command to export the exact versions from your current environment: 
pip freeze > requirements.txt

TroubleshootingInvalid API-key Providederror

This error indicates that the Model Studio API key is not correctly configured in the environment variables for the full-code application. To learn how to get an API key, see Obtain an API key.
Agent Development
Agent Context
Agent Governance & Evolution
Store
Application Marketplace
Use Cases
Support