Building Custom AI Agents in Tongyi Qianwen: A Step-by-Step Guide to Instructions, Knowledge Bases, and Tool Plugins

Knowledge workers and cross-functional teams frequently encounter an efficiency bottleneck when using general-purpose artificial intelligence assistants: every new session requires pasting lengthy background prompts, tone guidelines, and corporate rules, only for the model to generate generic responses or hallucinate facts because it cannot access private internal files.

Tongyi Qianwen (powered by Alibaba Cloud's Qwen model ecosystem) addresses this problem directly through its custom agent architecture. By configuring three essential building blocks—system instructions, private knowledge bases (Retrieval-Augmented Generation, or RAG), and tool plugins—professionals can transform a generic conversational model into a persistent, domain-specific digital teammate.

Whether built through Tongyi Qianwen's web productivity interface or scaled via Alibaba Cloud Model Studio (Bailian), a well-designed custom agent retains memory of organizational requirements, grounds its answers in verified enterprise documents, and takes direct actions using live external tools.

The Three Core Pillars of a Tongyi Qianwen Custom Agent

A custom agent is more than a saved prompt; it is an integrated system where reasoning, proprietary memory, and dynamic actions work together seamlessly.

+-------------------------------------------------------------------+
|                     User Query / Task Trigger                    |
+---------------------------------+---------------------------------+
                                  |
                                  v
+-------------------------------------------------------------------+
|                  Tongyi Qianwen Agent Core (Qwen)                 |
|                                                                   |
|  +--------------------+  +--------------------+  +--------------+  |
|  | System Instruction |  | Knowledge Base RAG |  | Tool Plugins |  |
|  | Persona & Rules    |  | Private Docs & Data|  | APIs & Search|  |
|  +--------------------+  +--------------------+  +--------------+  |
+---------------------------------+---------------------------------+
                                  |
                                  v
+-------------------------------------------------------------------+
|           Grounded, Formatted, and Actionable Output             |
+-------------------------------------------------------------------+

1. System Instructions: The Behavioral Foundation

The system instruction (or system prompt) dictates identity, tone, task boundaries, and execution rules. Without clear instructions, models default to generic conversational patterns.

A production-ready instruction must specify:

• Role and Persona: Define the agent's professional background, perspective, and intended user audience.
• Workflow Steps: Clarify the sequence the agent must follow when processing requests (for instance, analyze intent first, query documentation second, and synthesize results last).
• Negative Constraints & Guardrails: Establish what the agent must not do, such as speculating on undisclosed financials or adopting an informal tone.
• Output Specifications: Specify formats such as Markdown tables, bulleted executive briefs, or structured checklists.

2. Knowledge Bases: Private Document Retrieval via RAG

Large language models possess broad public knowledge but have no visibility into private product roadmaps, vendor contracts, or internal standard operating procedures (SOPs).

Attaching a knowledge base leverages Retrieval-Augmented Generation (RAG):

• When a user asks a question, the platform splits documents into semantic chunks and creates vector embeddings.
• The retrieval engine identifies the most relevant text passages matching the user query.
• The agent injects these passages into its working context and synthesizes an answer grounded strictly in your proprietary files, reducing hallucinations to near zero.

3. Tool Plugins: Giving the Agent Hands and Eyes

While text models reason and write, plugins enable interaction with external systems:

• Platform Utilities: Native web search retrieves real-time market data; code execution sandboxes calculate complex formulas and process tabular datasets; and image generation engines produce visual mockups.
• Custom APIs & OpenAPI Extensions: By connecting REST endpoints, an agent can query CRM records, update project tracking boards, or pull live inventory counts.
• Model Context Protocol (MCP) Services: Standardized integrations allow agents to interact with secure data servers and developer environments.

Architectural Comparison: General Chat vs. Custom Agent

Step-by-Step Guide: Creating a Custom Agent

Step 1: Initialize the Agent and Select the Foundation Model

1. Access the agent creation interface via Tongyi Qianwen or the Alibaba Cloud Model Studio application management dashboard.
2. Click Create Agent (or Create Application).
3. Set your agent identity:
   • Name: Choose a functional title (such as IT Support Analyst or SaaS RFP Specialist).
   • Description: Provide a summary so teammates understand its purpose.
   • Avatar: Select an icon reflecting the agent's function.
4. Choose the Model Engine:
   • Qwen-Max: Recommended for complex multi-step reasoning, intricate tool orchestration, and high-stakes document synthesis.
   • Qwen-Plus: An ideal balance of latency and cost efficiency for daily corporate office drafting, customer service, and standard FAQ lookups.
   • Qwen-Long: Optimized for processing massive context windows and scanning through extensive documentation archives.

Step 2: Formulate Production-Grade System Instructions

In the system prompt editor, avoid single-sentence requests. Use a structured template that clarifies the agent's operational logic:

# Role
You are the Senior Technical Sales Enablement Assistant for our cloud solutions division. Your primary goal is to help our enterprise sales representatives prepare accurate, technically sound RFP responses.

# Capabilities & Tools
1. You have direct access to our verified Product Whitepapers and Security Compliance Knowledge Base.
2. You can invoke Web Search to confirm public competitor specifications when requested.

# Operating Rules
- Source Grounding: Always query the Knowledge Base before answering product capability questions. Cite the document title and section when referencing specifications.
- Strict Honesty: If a requested feature or compliance certification is not explicitly documented in the knowledge base, state clearly: "This capability is not documented in our verified internal repository." Do not guess or extrapolate.
- Tone: Professional, precise, and concise. Avoid conversational filler.
- Output Format: Provide answers in structured bullet points, followed by a summary comparison table when comparing multiple product tiers.

Step 3: Configure and Attach Private Knowledge Bases

1. Navigate to the Knowledge Base section within the agent configuration console.
2. Select Add Knowledge Base and upload your private operational files. Tongyi supports formats including .pdf, .docx, .txt, .md, and .csv.
3. Configure indexing and parsing settings:
   • Chunking Strategy: Choose standard semantic chunking for narrative guides and whitepapers. For structured data like product tables or FAQs, ensure distinct delimiters.
   • Retrieval Threshold: Adjust the similarity score threshold and top-k recall parameter to ensure only relevant document chunks enter the prompt window.
4. Set explicit instructions in your prompt dictating how the agent handles retrieved knowledge (e.g., instructing it to cite document titles or quote exact figures).

Step 4: Configure Native Plugins and Custom Tool APIs

1. Under the Tools & Plugins configuration tab, enable native capabilities required for the agent's workflow:
   • Web Search: Essential for queries involving dynamic market indices, software version changes, or competitor releases.
   • Code Interpreter (Python Sandbox): Necessary if the agent needs to parse uploaded spreadsheets, perform financial calculations, or generate statistical charts.
2. Add Custom API Plugins (Optional):
   • Click Create Custom Plugin or Add Tool.
   • Input your service endpoint URL and authentication method (e.g., Bearer Token or Header API Key).
   • Define tool metadata: provide a clear, semantic description of the API's purpose and parameter schemas. The Qwen model uses these descriptions to determine when and how to execute function calls.
   • Run a test call in the configuration console to verify that returned JSON payloads match the expected schema.

Step 5: Test and Debug in the Interactive Playground

Before publishing, evaluate the agent using the side-by-side preview panel:

• Test Knowledge Retrieval: Submit edge-case questions covered in your documents to ensure the agent retrieves the correct excerpt rather than generic web knowledge.
• Test Boundary Guardrails: Inquire about unsupported features or unverified data to confirm the agent politely declines instead of hallucinating.
• Inspect Tool Invocations: Ask a query requiring calculation or live search to verify that the tool call triggers correctly and parses external data properly.

Step 6: Publish, Share, and Maintain

1. Click Publish.
2. Determine sharing permissions:
   • Private: Visible only to the creator for personal productivity.
   • Team / Organization Workspace: Shared across team members within your organization.
   • Public / Shared Link: Accessible via a web link for external stakeholders.
3. For programmatic and omnichannel deployment, use the generated App ID and DashScope SDK to embed the agent into enterprise communication tools (such as DingTalk), intranet portals, or customer-facing web widgets.

Three Real-World Workplace Agent Blueprints

Blueprint 1: Enterprise RFP & Compliance Reviewer

• Target Audience: B2B sales engineers and bid managers.
• Instruction Focus: Fact-checking vendor requirements against security specifications; strictly flagging gaps.
• Knowledge Base: SOC2 reports, ISO27001 certifications, corporate data security policies, and standard SLA agreements.
• Plugins: Code Interpreter (for calculating uptime guarantees and cost calculations).
• Key Output: Verification tables indicating compliance status (Compliant, Partially Compliant, Non-Compliant) with document page citations.

Blueprint 2: Financial Operations Analyst

• Target Audience: Finance managers, controllers, and department leads.
• Instruction Focus: Extracting key ledger trends, evaluating expense anomalies, and creating executive summaries.
• Knowledge Base: Internal travel & expense policies, departmental budget sheets, and fiscal year guidelines.
• Plugins: Code Interpreter (for executing Python scripts on uploaded transaction CSVs) and Web Search (for live currency exchange rates).
• Key Output: Variance analyses highlighting discrepancies between budgeted figures and actual expenditures.

Blueprint 3: Brand Marketing & Campaign Strategist

• Target Audience: Content creators, product marketers, and social media managers.
• Instruction Focus: Drafting product announcements, press briefs, and customer success stories adhering to brand voice.
• Knowledge Base: Brand style guides, product positioning matrices, and historical customer case studies.
• Plugins: Web Search (for tracking trending industry hashtags and recent competitor launches) and Wanx Image Generation (for visual concept mockups).
• Key Output: Multi-channel content packages (blog outline, LinkedIn post, newsletter snippet) aligned with brand messaging.

Best Practices and Common Pitfalls

1. Clean Your Documents Before Uploading: Raw PDF scans with messy OCR, complex merged tables, or watermarked headers degrade semantic chunking. Convert tabular data into clean Markdown tables or CSVs to ensure high retrieval fidelity.
2. Avoid Vague Tool Descriptions: When defining custom API plugins, provide explicit natural language descriptions for every parameter. If an API expects an ISO date format (YYYY-MM-DD), state it directly in the parameter description so the model passes valid payloads.
3. Establish Clear Fallback Behaviors: Always instruct the agent what to do when information cannot be found. A response stating "I cannot find documentation regarding this policy in our database" is far more valuable in an enterprise context than an eloquent hallucination.
4. Implement Continuous Knowledge Lifecycle Management: Outdated documents lead to outdated answers. Assign an owner to refresh files within the agent's knowledge base whenever product pricing, policies, or workflows are updated.

References

• 千问-阿里 AI 助手
• 通义实验室
• Qwen offers comprehensive functionality spanning chatbot, image and video understanding, image generation, document processing, web search integration, tool utilization, and artifacts.
• GitHub - QwenLM/Qwen-Agent: Agent framework and applications built upon Qwen>=3.0, featuring Function Calling, MCP, Code Interpreter, RAG, Chrome extension, etc.