Lack of documentation on how to use API-Based variables in Orchestrator agent instruction

[akkaz]

Self Checks

• [X] I have searched for existing issues search for existing issues, including closed ones.
• [X] I confirm that I am using English to submit report (我已阅读并同意 Language Policy).
• [X] 请务必使用英文提交 Issue，否则会被关闭。谢谢！:）
• [X] Please do not modify this template :) and fill in all the required fields.

Provide a description of requested docs changes

While the documentation for creating API-based variables is clear API-based docs, the guidance on how to effectively use these variables within agent conversations is lacking. We are able to create API-based variables successfully, but we counter difficulties when trying to access and consume them as API-base variable in input variable for agent instruction.

In our scenario we want to use the API-based variable in the Orchestrator agent instruction. We are at the point that we can insert the variable as instruction, but we don't know how to use the API we just created to fetch our instructions outside dify.

[dosubot[bot]]

Hey @akkaz! I'm here to help you with any bugs, questions, or contributions you have. Let's tackle this together!

To effectively use API-based variables within Orchestrator agent instructions to fetch instructions outside Dify, follow these steps:

1. Prepare the API and API Key: Ensure you have an API and an API Key for authentication.

2. Add API Extension Configuration:

   • Go to the settings interface in Dify.
   • Add the API extension configuration by entering the name, API endpoint, and API Key.

3. Add the API-based Extension:

   • On the prompt orchestration page, click the "+ Add" button next to "Tools."
   • In the "Add Tool" dialog box, fill in the name and variable name (in English) and select the API-based extension added in the previous step.

4. Assemble the Queried Data into the Prompt:

   • Use the variable name to reference the API-based extension in your prompt.
   • For example, to query today's weather in London, you can add a location variable with the value "London" and combine it with the external data tool's extension variable name weather_data.

Here is an example of how to set up and use the API-based variable:

# Example Setup

1. **Add API-based Extension**:
   - Name: Weather Inquiry
   - API Endpoint: `https://api.weather.com/v3/wx/conditions/current`
   - API Key: `your_api_key`

2. **Add Tool in Prompt Orchestration**:
   - Name: Weather Tool
   - Variable Name: `weather_data`
   - Select the "Weather Inquiry" API-based extension.

3. **Use in Prompt**:
   ```markdown
   To get the current weather in London, use the following prompt:

   What is the weather like in {{location}} today?

• Set location to "London".
• The system will call the API and inject the returned data into the prompt.

4. Debug Output:
   • The debug output will show the real-time data returned by the API, such as:

     The weather in London today is {{weather_data}}.

By following these steps, you can effectively use API-based variables to fetch and incorporate external data into your Orchestrator agent instructions ^{[1][2][3][4][5]}.

To continue talking to Dosu, mention @dosu.

[crazywoola]

Please refer these 2 docs as well. https://docs.dify.ai/guides/extension/api-based-extension/cloudflare-workers https://github.com/crazywoola/dify-extensions-worker

Here is the result of the API Based variables.

It's used in basic agent originally to give the bot ability to interact with other services, and it will be called every time you talk to the bot, vise versa, the agent will choose tools it needs to answer the questions accordingly.

In you case you should let the api return the prompt.

[crazywoola]

I think there might be a bug as well https://github.com/langgenius/dify/issues/5734

[crazywoola]

See this image above, my api endpoint getQuotes support getting a variable called count, if you would like to add this parameter to that endpoint, just add another textbox to hold this parameter like I do in this image. This depends how you code you api extension.

For example, if you would like to use different prompt by different platform(facebook, x, instagram)

You just need to pass theplatform to the api endpoint, and it will be injected in the system prompt. FYI, it will send both inputs and query to the endpoint.

{
  query: 'user's questions',
  inputs: {  platform: ''facebook'  }
}

[akkaz]

After more than a month of working without issues, I’ve recently encountered some problems.

It seems that the API-based Variable has stopped functioning as expected in the last few days. Unfortunately, I'm unable to pinpoint exactly when this issue started, though it might have occurred around the update to version 0.7 or shortly after.

I’ve verified that the endpoint is correct and accessible through Insomnia, where everything works as expected. However, according to the Cloudflare logs, it appears that Dify isn't even attempting to reach the endpoint.

[akkaz]

@crazywoola sorry for tagging you again, but i think that new version (0.7) bug this feature.

[aiwinapp]

@crazywoola sorry for me to, but in new version Dify isn't even attempting to reach the endpoint.