Quick start: create a Flow Agent

Updated at:
Copy as MD

This quickstart shows you how to create and test a Flow Agent on Alibaba Cloud Function Compute. You use the visual flow canvas to drag and drop nodes, connect them into a workflow, and then run a test execution to verify the result.

Important

The low-code Agent creation feature is in maintenance mode and will not be developed further. Do not create new low-code Agents. You can continue to use your existing low-code Agents, and an upgrade plan will be provided later.

Flow Agent capabilities

Function Compute provides a visual flow canvas for building agent workflows through low-code orchestration. The canvas supports multiple node types, including Start, Large Language Model (LLM), MCP Server, and code execution nodes. You connect these nodes to build a complete workflow, and the system converts your canvas configuration into an executable workflow definition. Workflows support two execution modes: conversation mode and workflow mode.

Flow Agents support the following capabilities:

  • Model orchestration: Qwen series models and OpenAI-compatible models.

  • Tool support: Tools built on the OpenAPI specification and the MCP protocol.

  • Agent orchestration: AgentRun agents and built-in function-calling agents.

  • Knowledge base integration: Alibaba Cloud Model Studio knowledge base.

  • Custom code execution: Built-in code execution node and Function Compute nodes.

  • Flow control: Branching, looping, iteration, and parallel execution.

  • Multi-protocol integration: Native, OpenAI-compatible, Dify Workflow, and Dify Chatflow protocols.

  • Version management and canary release: Control the rollout scope during gradual optimization.

Core concepts

Before you create a Flow Agent, review the following concepts. If you are already familiar with them, skip to Prerequisites.

Model

Your Flow Agent can use Qwen and OpenAI-compatible models configured in the AgentRun platform:

  • API-connected models: Third-party LLMs connected through standard APIs.

  • FunModel-hosted models: Self-built or open-source models hosted in AgentRun or Function Compute environments.

  • LiteLLM model administration: Model services connected and administered through LiteLLM.

Agent

Flow Agents support adding agents built in other ways on the AgentRun platform inside a Flow Agent node. For more information, see Create an Agent without code and Create an Agent with code.

Execution modes

Flow Agents support two execution modes:

  • Conversation mode: Supports session variables. You can pass a conversation_id to each workflow execution. Workflows with the same conversation_id share access to session variables. Use this mode when your Flow Agent needs to maintain context across multiple executions.

  • Workflow mode: Does not specify sys.conversation_id during execution. Use this mode when you do not need to share session variables across multiple executions.

Environment variable

Use environment variables to store sensitive information specific to your application, such as API keys and database credentials. You can configure environment variables at the workflow level. Nodes in the workflow can access those variables.

Version and canary release

Flow Agents support version management and canary release. You can create multiple versions for a Flow Agent. Each version includes a set of configurations such as models, prompts, and tools. You can route traffic to a new version at a defined ratio to gradually verify the stability and effectiveness of new configurations.

Prerequisites

  • A model configured on the Model Management page. Configure a Qwen or OpenAI-compatible model.

  • The execution role for your Flow Agent requires the following policies:

    Access policy

    Description

    AliyunFCInvocationAccess

    Required to invoke Function Compute nodes in a workflow.

    AliyunDevsReadOnlyAccess, AliyunFCFunctionAIReadOnlyAccess

    Required to invoke MCP services and tools in a workflow.

    AliyunBailianDataFullAccess

    Required to invoke Model Studio knowledge retrieval in a workflow.

    AliyunAgentRunReadOnlyAccess

    Required to invoke AgentRun agents in a workflow.

    Note

    The following policies are for features not yet supported but may be available in the future: AliyunEventBridgePutEventsPolicy (invoke EventBridge in a workflow) and AliyunFnFFullAccess (invoke other workflows in a workflow).

Step 1: Configure basic information

  1. Log on to the AgentRun console. On the Agent Runtime page, click Create Agent.

  2. Select Create with Flow to open the Flow Agent creation page.

  3. Configure the following parameters:

    Parameter

    Type

    Required

    Default

    Description

    Agent Name

    Text input

    Yes

    agent-flow-{random}

    The name of the Flow Agent. The name can contain letters, digits, and hyphens (-), must start with a letter, and can be up to 63 characters in length.

    Description

    Text area

    No

    Empty

    A brief description of the flow's purpose, features, and use cases. Maximum 1,000 characters.

    Execution role

    Role selector

    Yes

    None

    A RAM role that grants the workflow service permissions to access other Alibaba Cloud services. The role requires the policies listed in Prerequisites. The product code is fnf. If the role is missing required policies, click One-click authorization to grant permissions.

    Access Credentials

    Selector

    Yes

    No credentials

    The inbound access credential for the Flow Agent. You can select No credentials for anonymous access or Use existing credentials to select an existing credential. Using a credential is recommended for security.

    Disable Public Network Access

    Checkbox

    No

    Unchecked

    When selected, the Flow Agent cannot be accessed through the public network. You must access it through a VPC.

    Log Delivery

    Toggle + selectors

    No

    Disabled

    Enable log delivery to send execution logs to Simple Log Service (SLS). When enabled, you must select a Log Project and a Logstore.

    Workspace

    Selector

    Yes

    Current workspace

    The workspace to which the Flow Agent belongs.

  4. Click Next to proceed to the flow canvas.

Step 2: Design the workflow on the canvas

The flow canvas provides a visual editor where you drag and drop nodes to design your workflow.

  1. The canvas includes a default Start node and an End node.

  2. Add nodes between the Start and End nodes. Click the Start node and add nodes in the Next step section of the configuration panel on the right side, or right-click on the canvas and select Add node.

    Add an LLM node (select model qwen3-max) and a Streaming Response node between the Start and End nodes. Connect the nodes in sequence to form a complete workflow.

  3. Click a node to open its configuration panel:

    • For an LLM node: Select a model from the drop-down list (such as qwen3-max). Configure the prompt in the SYSTEM message and configure input parameters in the USER message.

    • For a Streaming Response node: Configure streaming response parameters.

  4. Connect nodes: Ensure that the Start node connects to intermediate nodes and that the intermediate nodes connect to the End node.

  5. Click Create Agent and wait for the creation to complete.

After the Flow Agent is created, a Flow created successfully message appears and the page redirects to the Flow detail page.

Step 3: Test the workflow

After creation, the Flow detail page opens with the following tabs:

Tab

Description

Configuration & Debugging (default)

A visual canvas for editing the workflow. Changes are automatically saved as a draft. Click Save to publish the draft as a new version.

Execution History

View execution records for all workflow runs.

Version and Grayscale

Manage versions and configure canary release with Endpoints.

Integration and Publishing

View API integration code samples and publish the Flow Agent as a chat widget.

Observability

View execution monitoring metrics, LLM call statistics, and tracing information.

You can also perform the following operations on the Flow detail page:

  • Click Edit Configuration to modify basic information such as the description, execution role, and log delivery settings.

  • Click Run to test the workflow.

  • If you have unsaved changes, an orange Pending changes badge appears. Click Discard changes to revert to the last published version.

To test the workflow:

  1. On the Configuration & Debugging tab, click Run to open the execution drawer.

  2. Configure execution parameters. The drawer has two modes depending on the flow definition:

    Standard mode (for flows without visual orchestration annotations):

    Parameter

    Type

    Required

    Description

    Execution Name

    Text input

    No

    A unique name for this execution. Leave empty to auto-generate.

    Input Parameters (JSON)

    JSON editor

    No

    JSON-formatted input parameters. Default: {"key": "hello world"}.

    AIStudio mode (for flows created with the visual canvas):

    Parameter

    Type

    Required

    Description

    Execution Name

    Text input

    No

    A unique name for this execution. Leave empty to auto-generate.

    Session ID (Conversation ID)

    Text input

    No

    Displayed only in Express mode. Used to identify and maintain a conversation session.

    Query

    Text input

    No

    Displayed only in Express mode. The user's query input, such as "Hello, introduce yourself."

    User ID (UID)

    Text input

    No

    Displayed only in Express mode. Used to identify the user.

    Dynamic form fields

    Varies

    Varies

    Additional fields automatically generated from the Start node variables in the flow definition. Supported types: text input, number, paragraph, select, file upload, and multi-file upload.

  3. (Optional) Expand Advanced Options to specify a version or alias for the execution:

    Option

    Description

    Not Specified

    Use the latest version for execution. This is the default.

    Alias

    Select an Endpoint (alias) from the drop-down list.

    Version

    Select a specific published version from the drop-down list.

  4. Click Start Execution and wait for the execution to complete.

    • Standard execution: The execution runs asynchronously. After the execution starts, the page redirects to the execution details page.

    • Express execution: The execution runs synchronously with streaming support. Execution messages are displayed in real time. After completion, the page automatically redirects to the execution details page.

Version management and canary release

You can manage versions and configure canary release on the Version and Grayscale tab of the Flow detail page.

Publish a version

Each time you click Save on the Configuration & Debugging tab, a new version is published. A version is an immutable snapshot that includes the workflow definition, description, execution role, and other configurations. You can publish a new version only when the workflow has changed since the last version.

Create an Endpoint

An Endpoint is a version routing entry that supports traffic allocation and canary release.

  1. On the Version and Grayscale tab, click Create Endpoint.

  2. Configure the following parameters:

    Parameter

    Type

    Required

    Description

    Endpoint Name

    Text input

    Yes

    The name of the Endpoint. Cannot be modified after creation. The reserved name Default cannot be used.

    Description

    Text area

    No

    A brief description of the Endpoint.

    Main Version

    Selector

    Yes

    The primary version that receives the majority of traffic. Select from the published version list.

    Enable Minor Version

    Checkbox

    No

    Enable canary release by routing a portion of traffic to a secondary version.

    Canary Release (version)

    Selector

    Conditional

    Displayed when Enable Minor Version is selected. Select a secondary version. The secondary version cannot be the same as the main version.

    Traffic Allocation

    Number (×2)

    Conditional

    Displayed when Enable Minor Version is selected. The traffic percentage for the main version and the canary version. The two values must sum to 100%. The default canary traffic is 10%.

    Disable Public Network Access

    Checkbox

    No

    When selected, the Endpoint cannot be accessed through the public network.

  3. Click Save Configuration.

Canary release

When you enable a minor version for an Endpoint, traffic is split between the main version and the canary version based on the configured percentage. For example, if you set the canary traffic to 10%, 90% of requests are routed to the main version and 10% to the canary version. You can adjust the traffic allocation at any time by editing the Endpoint configuration.

A visual progress bar shows the traffic distribution: the blue section represents the main version traffic and the orange section represents the canary version traffic.

API integration

You can call your Flow Agent through APIs using multiple protocol types. On the Integration and Publishing tab, view code integration examples.

Supported protocols

Flow Agents support the following protocol types in streaming and non-streaming variants:

Protocol

Type

API path

Native Protocol (Streaming)

Native

/endpoints/{qualifier}/invocations with header x-fnf-param-stream: true

Native Protocol (Non-streaming)

Native

/endpoints/{qualifier}/invocations

OpenAI Streaming

OpenAI-compatible

/endpoints/{qualifier}/invocations/openai/v1/chat/completions

OpenAI Non-Streaming

OpenAI-compatible

/endpoints/{qualifier}/invocations/openai/v1/chat/completions

Dify Streaming Workflow

Dify Workflow

/invocations/dify-workflow/v1/workflows/run

Dify Workflow Non-Streaming

Dify Workflow

/invocations/dify-workflow/v1/workflows/run

Dify Chatflow Streaming

Dify Chatflow

/invocations/dify-chatflow/v1/chat-messages

Dify Chatflow Non-streaming

Dify Chatflow

/invocations/dify-chatflow/v1/chat-messages

Endpoint URL format

The Endpoint invocation URL follows this format:

https://{uid}.{domain}/flows/{flowName}/endpoints/{qualifier}/invocations

Replace {uid} with your Alibaba Cloud account ID, {domain} with the service domain, {flowName} with the name of your Flow Agent, and {qualifier} with the Endpoint name.

Authentication

Endpoint invocations support the following authentication methods: API Key, Basic Auth, JWT/AK_SK (Bearer Token), and custom Header.

Publish as a chat widget

You can publish your Flow Agent as a chat widget to provide a web interface for user interaction.

  1. On the Flow detail page, click the Integration and Publishing tab.

  2. In the integration templates section, select an integration method and a style template:

    • Integration method: Full-screen embed, floating chat window, sidebar, or custom.

    • Style template: Minimalist, Business, Tech, or Warm.

  3. Click Start integration to open the API binding configuration dialog box.

  4. Configure API binding:

    • Select an execution role, such as AliyunAgentRunDefaultRole.

    • Select an Endpoint, such as Default (ACTIVE).

  5. Click Next and wait for the integration resource deployment to complete.

After the deployment is complete, a Deployment completed! message appears. You can find the chat widget URL in the Deployed integration resources section.

View workflow traces

You can view trace information for Flow Agent workflow executions on the Observability tab of the Flow detail page.

The Observability tab provides three monitoring views:

  • Infrastructure monitoring: View statistics such as the number of executions, average and maximum execution duration (milliseconds), execution errors, LLM calls, input tokens, output tokens, success rate, and total node execution duration (milliseconds).

  • LLM monitoring: View monitoring information for LLM calls, including token usage and call latency.

  • Tracing Analysis: View detailed execution trace information. You must enable Tracing Analysis before you can use this feature.

Next steps

After you create and test your Flow Agent, explore the following capabilities: