> ## Documentation Index
> Fetch the complete documentation index at: https://enterprise-docs.dify.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent API

> API for Agent apps, covering streaming chat messages, conversation management, file uploads, and app configuration

> [!NOTE]
>
> Agent here means the new Agent app type (`agent` mode). The Legacy Agent app (`agent-chat`) is covered on [Chatbot and Legacy Agent](https://enterprise-docs.dify.ai/en/3.13.x/develop/api/guides/chat.md).

[Agent apps](https://enterprise-docs.dify.ai/en/3.13.x/use/build/new-agent/overview.md) run in `agent` mode: you send a message, stream the reply as it generates, and keep multi-turn context in conversations.

The model reasons and calls tools autonomously, and the stream shows that work: the reply text streams incrementally as `agent_message` events, with `agent_thought` events carrying each reasoning step and tool call alongside.

The turn closes with a single `message` event carrying the complete answer, then `message_end`. Render the `agent_message` deltas live and treat the closing `message` as the final answer rather than appending it.

Each `agent_thought` event carries the step's `thought`, the `tool` it called with its `tool_input`, and the tool's `observation`. The full stream shape is on [Send Chat Message](https://enterprise-docs.dify.ai/en/3.13.x/develop/api/chat-messages/send-chat-message.md).

> [!NOTE]
>
> Authentication, the base URL, and the `user` field that scopes end-user data are covered in [Get Started](https://enterprise-docs.dify.ai/en/3.13.x/develop/api/guides/get-started.md) and [End User Identity](https://enterprise-docs.dify.ai/en/3.13.x/develop/api/guides/end-user-identity.md).

## Send Messages and Stream Replies

* **[Send Chat Message](https://enterprise-docs.dify.ai/en/3.13.x/develop/api/chat-messages/send-chat-message.md)**: send a query to your Agent app. Streaming mode only; blocking mode returns a 400 `bad_request` error.

  Reply text streams as `agent_message` deltas, batched at roughly half-second intervals rather than token by token.

  The closing `message_end` event reports token usage. It never includes knowledge-retrieval citations (`retriever_resources`).

  Two limits end a run early, and either one closes the stream with the `agent_run_limit_exceeded` error code:

  * **Time**: a run is stopped after 1 hour by default.

    For longer runs, raise `APP_MAX_EXECUTION_TIME`, `WORKFLOW_MAX_EXECUTION_TIME`, and `DIFY_AGENT_RUN_TIMEOUT_SECONDS` above the duration you need. See [Environment Variables](https://enterprise-docs.dify.ai/en/3.13.x/deploy/advanced-configuration/environment-variables.md) for details.
  * **Model requests**: each run is capped at 500.

* **[Stop Chat Message Generation](https://enterprise-docs.dify.ai/en/3.13.x/develop/api/chat-messages/stop-chat-message-generation.md)**: interrupt a streaming reply before it finishes.

* **[Get Next Suggested Questions](https://enterprise-docs.dify.ai/en/3.13.x/develop/api/chat-messages/get-next-suggested-questions.md)**: propose follow-up questions after a reply completes, based on the conversation so far.

## Manage Conversations

* **[List Conversations](https://enterprise-docs.dify.ai/en/3.13.x/develop/api/conversations/list-conversations.md)**: the current user's conversations, ordered by most recent activity.
* **[List Conversation Messages](https://enterprise-docs.dify.ai/en/3.13.x/develop/api/conversations/list-conversation-messages.md)**: one conversation's message history, for a scrolling chat UI. Each message's `agent_thoughts` array carries the reasoning steps for that turn.
* **[Rename Conversation](https://enterprise-docs.dify.ai/en/3.13.x/develop/api/conversations/rename-conversation.md)**: set a conversation's name, or have one generated from its content.
* **[Delete Conversation](https://enterprise-docs.dify.ai/en/3.13.x/develop/api/conversations/delete-conversation.md)**: remove a conversation and its messages.

## Upload Files

* **[Upload File](https://enterprise-docs.dify.ai/en/3.13.x/develop/api/files/upload-file.md)**: upload an image, document, audio, or video file, scoped to the uploading end user.

  Files passed to [Send Chat Message](https://enterprise-docs.dify.ai/en/3.13.x/develop/api/chat-messages/send-chat-message.md) are surfaced to the agent as downloadable references it can fetch and inspect in its sandbox.

* **[Get End User Info](https://enterprise-docs.dify.ai/en/3.13.x/develop/api/end-users/get-end-user-info.md)**: look up an end user's details from an end-user ID, such as the `created_by` in the Upload File response.

## Transcribe and Synthesize Speech

* **[Convert Audio to Text](https://enterprise-docs.dify.ai/en/3.13.x/develop/api/audio/convert-audio-to-text.md)**: transcribe an uploaded audio file (MP3, M4A, WAV, AMR, or MPGA, up to 30 MB) so end users can speak their input instead of typing it.
* **[Convert Text to Audio](https://enterprise-docs.dify.ai/en/3.13.x/develop/api/audio/convert-text-to-audio.md)**: synthesize a reply back into speech.

## Retrieve App Info and Settings

* **[Get App Info](https://enterprise-docs.dify.ai/en/3.13.x/develop/api/applications/get-app-info.md)**: the app's name, description, tags, and mode.
* **[Get App Parameters](https://enterprise-docs.dify.ai/en/3.13.x/develop/api/applications/get-app-parameters.md)**: the fields your calls send in `inputs` (names, types, defaults) plus the app's feature switches—the basis for building requests or a client UI.
* **[Get App Meta](https://enterprise-docs.dify.ai/en/3.13.x/develop/api/applications/get-app-meta.md)**: app metadata; the `tool_icons` map is empty for Agent apps.
* **[Get App WebApp Settings](https://enterprise-docs.dify.ai/en/3.13.x/develop/api/applications/get-app-webapp-settings.md)**: the web app's site configuration, theme, and customization options.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.