Best Practices

​

Project Structure

• The entry file must be named main.py.
• A GET /health endpoint must be provided. When using AgentScope Runtime, this endpoint is automatically registered—you do not need to implement it manually.
• The default conversation endpoint path is /process, conforming to the Agent API Protocol specification.
• In requirements.txt, dependencies must be pinned using == (e.g., dashscope==1.20.14). Avoid version ranges like >=, as they cause inconsistent dependency resolution across builds—potentially leading to build failures or runtime inconsistencies. After local debugging succeeds, run pip freeze > requirements.txt to export exact versions.

​

Recommended Development Workflow

1. Start from a template: When creating an application in the console, select an appropriate template (e.g., Basic Chat Agent, Tool-Calling Agent, or Deep Research Agent) to quickly obtain a runnable base project.
2. Local development & debugging: Download the template code locally, install dependencies per the README included in the package, then run and debug locally:
   Copy

   pip install -r requirements.txt
   python main.py  # Starts locally on port 8080 by default
   
3. Add tools: In the console’s Tools page, add required tools (e.g., Knowledge Base, MCP services), retrieve environment variables, and implement tool-calling logic in your code.
4. Build and deploy: Package your project as a .whl file and deploy it:
   Copy

   runtime-fc-deploy --deploy-name My Application --whl-path ./dist/my_app-0.1.0-py3-none-any.whl --telemetry enable
   
5. Console testing: After successful deployment:
   • Use the API Test Mode (right panel) to verify endpoints.
   • Use the Text Chat Experience Mode (right panel) to validate multi-turn dialogue behavior and tool invocation.
6. Iterate and optimize: Adjust code based on test results and rapidly update deployment using:
   Copy

   runtime-fc-deploy --update
   

​

Tool Selection Guide

​

MCP Tool Development Best Practices

​

✅ Precise tool descriptions

# Good — Enables accurate LLM decision-making
@mcp.tool(
    name="search_product_docs",
    description="Search technical documentation and operation guides in the product knowledge base. Ideal for answering questions about features, configuration, and troubleshooting."
)

# Poor — Too vague for reliable tool routing
@mcp.tool(
    name="search",
    description="A search tool"
)

​

✅ Complete parameter documentation

async def search(
    query: Annotated[str, Field(description="Natural-language search query")],
    top_k: Annotated[int, Field(description="Number of results to return (1–20); default: 5")] = 5,
    category: Annotated[str, Field(description="Document category filter: 'all', 'api', 'guide', or 'faq'; default: 'all'")] = "all"
) -> str:

​

✅ Return structured, LLM-friendly output

async def search(query, top_k=5):
    results = await do_search(query, top_k)
    formatted = []
    for i, r in enumerate(results, 1):
        formatted.append(f"[{i}] {r.title}\n    Summary: {r.summary}\n    Source: {r.source}")
    return "\n\n".join(formatted) if formatted else "No relevant results found."

​

✅ Friendly error handling

async def query_data(query):
    try:
        result = await connector.query(query)
        return str(result)
    except ConnectionError:
        return "Service is temporarily unavailable. Please try again later."
    except ValueError as e:
        return f"Invalid query parameter: {e}. Please check input format."

​

Testing & Debugging

​

Debugging tips:

• Check runtime logs in the Logs tab of the Deployment page to diagnose tool call failures.
• Monitor call count, error rate, and response time in the Application Observability page to identify bottlenecks.
• Click Copy cURL Command to generate and run curl commands directly in your terminal.
• Enable Application Observability, and use the @trace decorator to track LLM latency and tool execution chains.

​

Production Deployment

1. Configure API Gateway: Create an API Gateway instance in the Gateway page. Set up a custom domain and routing rules to expose your service under a stable URL. ⚠️ Important: Your application’s deployment region must match the gateway’s region—otherwise routing will fail.
2. Enable Token Authentication: In gateway settings, turn on Token-based auth to ensure only authorized requests access your API.
3. Disable public test domain access: In the Triggers section of the Deployment page, toggle Disable Public Access to restrict traffic exclusively to your gateway domain.
4. Adjust resource specs: Scale vCPU, memory, and minimum instance count based on expected traffic. Set min instances ≥ 1 to avoid cold-start latency (~10–30 sec). For high-performance, stateful, or long-running tasks, consider Kubernetes (ACK) deployment—see Deployment Options.
5. Enable Application Observability: Activate observability and instrument your code with @trace to continuously monitor quality and performance.

​

Frontend Integration

​

Performance Optimization Tips

• Use streaming responses: The Agent API Protocol supports Server-Sent Events (SSE) natively. Return results via async yield so users see output incrementally—greatly improving perceived responsiveness.
• Set minimum instances wisely: In production, set min instances ≥ 1 to eliminate cold-start delays. Note: Minimum instances incur continuous cost.
• Parallelize independent tool calls: When multiple unrelated tools are needed, use asyncio.gather() to execute them concurrently—reducing total latency.
• Cache frequent queries: In-memory cache static or infrequently updated results (e.g., knowledge base lookups, external API responses) to reduce redundant network calls.