Looking for the previous docs site? Visit the legacy docs homepage. (opens in a new tab)
Agora Docs

Dify

Updated

Use Dify as the LLM in a Conversational AI Platform agent.

Preview documentation

You're reading the Conversational AI Platform (Preview) docs. Switch to Main.

Dify is an open-source LLM application development platform that provides a unified API for multiple LLM providers with workflow orchestration and advanced features.

Set up Dify

To integrate Dify with Agora Conversational AI, install the plugin, configure your Agora project, and create an endpoint:

  1. Install the Dify plugin

    1. Log in to the Dify Console.
    2. Click on Plugins in the top navigation bar to open the Marketplace.
    3. Search for the Agora Conversational AI plugin.
    4. Click Install to install the plugin.
    5. After installation, confirm that the plugin status is Active in the Installed Plugins list.

  2. Configure the Agora Console

    1. Log in to the Agora Console.
    2. Create a new project or select an existing one.
    3. Enable the Conversational AI feature within the selected project.
    4. Record the following information for later use:
      • App ID (unique project identifier)
      • Certificate (optional, if enabled for enhanced security)
    5. Navigate to the RESTful API page and generate a Customer ID and Customer Secret (required for HTTP Basic Authentication).

  3. Create an Endpoint in Dify

    1. In the Dify console's left-hand navigation panel, click on the Agora Conversational AI plugin you just installed.
    2. Click Create a new API endpoint to open the configuration page.
    3. Fill in the following details:
      • App ID (copied from the Agora Console)
      • Customer ID and Customer Secret (copied from the Agora Console)
      • TTS (Text-to-Speech) configuration (e.g., Azure or ElevenLabs)

  4. Save and note the endpoint details

    1. Save the endpoint configuration. Dify generates an Endpoint URL.

    2. Note down this Dify Endpoint URL and Dify endpoint API key for use in the llm configuration.

Sample configuration

The following example shows how to configure Dify as the agent's LLM when you create or update an agent. For a complete example, see Create an agent and start a session.

Dify supports BYOK only. It isn't available in managed mode. Store your Dify endpoint API key in a secret set, and refer to it from the agent. For details, see Use your own provider keys.

from agora_agent import Agent, Dify, secret_ref

# client is your configured Agora client
agent = (
    Agent(client=client)
    .with_stt(...)  # configure your ASR vendor
    .with_llm(
        Dify(
            api_key=secret_ref("support_prod", "dify"),
            vendor="dify",
            url="https://xxxxxx.ai-plugin.io/convoai/dify-completion",
            model="default",
            max_history=32,
            failure_message="Hold on a moment.",
            system_messages=[
                {"role": "system", "content": "You are a friendly support agent for Acme. Keep your answers short."}
            ],
        )
    )
    .with_tts(...)  # configure your TTS vendor
)
import { Agent, Dify, secretRef } from 'agora-agents';

// client is your configured Agora client
const agent = new Agent({ client })
  .withStt(/* configure your ASR vendor */)
  .withLlm(
    new Dify({
      apiKey: secretRef('support_prod', 'dify'),
      vendor: 'dify',
      url: 'https://xxxxxx.ai-plugin.io/convoai/dify-completion',
      model: 'default',
      maxHistory: 32,
      failureMessage: 'Hold on a moment.',
      systemMessages: [
        { role: 'system', content: 'You are a friendly support agent for Acme. Keep your answers short.' },
      ],
    }),
  )
  .withTts(/* configure your TTS vendor */);
// client is your configured Agora client
maxHistory := 32
agent := agentkit.NewAgent(client).
	WithStt( /* configure your ASR vendor */ ).
	WithLlm(vendors.NewDify(vendors.DifyOptions{
		APIKey:         agentkit.SecretRef("support_prod", "dify"),
		Vendor:         "dify",
		URL:            "https://xxxxxx.ai-plugin.io/convoai/dify-completion",
		Model:          "default",
		MaxHistory:     &maxHistory,
		FailureMessage: "Hold on a moment.",
		SystemMessages: []map[string]interface{}{
			{"role": "system", "content": "You are a friendly support agent for Acme. Keep your answers short."},
		},
	})).
	WithTts( /* configure your TTS vendor */ )

Set credential.mode to byok and credential.fields.api_key to a reference to the key. In the following example, the key is stored as dify in the support_prod set:

"llm": {
  "credential": {
    "mode": "byok",
    "fields": {
      "api_key": "$secrets.support_prod.dify"
    }
  },
  "vendor": "dify",
  "style": "dify",
  "model": "default",
  "url": "https://xxxxxx.ai-plugin.io/convoai/dify-completion",
  "max_history": 32,
  "failure_message": "Hold on a moment."
}

Set the system prompt and the greeting with the agent's instructions and greeting, not in the llm block.

Key parameters

The llm block takes the following fields. In the SDKs, the LLM class sets them from its options. Use the Dify class. The SDK sets the style to dify.

llm
vendorstring
required

Set to dify.

credentialobject
required

Set mode to byok and fields.api_key to a $secrets.<set>.<key> reference to the same API key configured in your Dify endpoint setup.

stylestring
required

Set to dify to use Dify's message format and workflow processing.

modelstring
required

Set to default to use the model configured in your Dify application.

urlstring
required

Use the custom endpoint URL from your Dify marketplace integration.

For complete llm block options, see Create an agent. For advanced configuration options, workflow setup, and detailed parameter descriptions, see the Agora Conversational AI - Dify Marketplace documentation.

Contact Us

+1 (408) 879-5885

2804 Mission College Blvd.Santa Clara, CA, USA 95054

AgoraCopyright © 2026 AgoraAll rights reserved