# Dify (/en/ai/platform/models/llm/dify)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

> Documentation: Conversational AI.
> Documentation version: Preview.
> This document describes only this version. [Version index](/llms/doc-versions-convoai-guides-v2.txt).


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](https://cloud.dify.ai).
   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](https://console.agora.io).
   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.

      ![](https://assets-docs.agora.io/images/conversational-ai/dify-endpoint.png)

## 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](/en/ai/platform/get-started/start-stop-agent#create-an-agent).

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](/en/ai/platform/build/use-your-own-keys).

**Python SDK**

```python
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
)
```

**TypeScript SDK**

```ts
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 */);
```

**Go SDK**

```go
// 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 */ )
```

**REST API**

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:

```json
"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**

**`vendor` (string) required**

Set to `dify`.

**`credential` (object) 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.

**`style` (string) required**

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

**`model` (string) required**

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

**`url` (string) required**

Use the custom endpoint URL from your Dify marketplace integration.

For complete `llm` block options, see [Create an agent](/en/api-reference/api-ref/conversational-ai/platform/create-agent). For advanced configuration options, workflow setup, and detailed parameter descriptions, see the [Agora Conversational AI - Dify Marketplace](https://marketplace.dify.ai/plugins/plutoless/convoai) documentation.