Interacting with Agents via API

DocsGPT Agents can be accessed programmatically through a dedicated API, allowing you to integrate their specialized capabilities into your own applications, scripts, and workflows. This guide covers the two primary methods for interacting with an agent: the streaming API for real-time responses and the non-streaming API for a single, consolidated answer.

When you use an API key generated for a specific agent, you do not need to pass prompt, tools etc. The agent's configuration (including its prompt, selected tools, and knowledge sources) is already associated with its unique API key.

API Endpoints

• Non-Streaming: http://localhost:7091/api/answer
• Streaming: http://localhost:7091/stream

For more technical details, you can explore the API swagger documentation available for the cloud version or your local instance.

Non-Streaming API (/api/answer)

This is a standard synchronous endpoint. It waits for the agent to fully process the request and returns a single JSON object with the complete answer. This is the simplest method and is ideal for backend processes where a real-time feed is not required.

Request

• Endpoint: /api/answer
• Method: POST
• Payload:
  • question (string, required): The user's query or input for the agent.
  • api_key (string, required): The unique API key for the agent you wish to interact with.
  • history (string, optional): A JSON string representing the conversation history, e.g., [{\"prompt\": \"first question\", \"answer\": \"first answer\"}].

Response

A single JSON object containing:

• answer: The complete, final answer from the agent.
• sources: A list of sources the agent consulted.
• conversation_id: The unique ID for the interaction.

Examples

curl -X POST http://localhost:7091/api/answer \
-H "Content-Type: application/json" \
-d '{
    "question": "your question here",
    "api_key": "your_agent_api_key"
}'

Streaming API (/stream)

The /stream endpoint uses Server-Sent Events (SSE) to push data in real-time. This is ideal for applications where you want to display the response as it's being generated, such as in a live chatbot interface.

Request

• Endpoint: /stream
• Method: POST
• Payload: Same as the non-streaming API.

Response (SSE Stream)

The stream consists of multiple data: events, each containing a JSON object. Your client should listen for these events and process them based on their type.

Event Types:

• answer: A chunk of the agent's final answer.
• source: A document or source used by the agent.
• thought: A reasoning step from the agent (for ReAct agents).
• id: The unique conversation_id for the interaction.
• error: An error message.
• end: A final message indicating the stream has concluded.

Examples

curl -X POST http://localhost:7091/stream \
-H "Content-Type: application/json" \
-H "Accept: text/event-stream" \
-d '{
    "question": "your question here",
    "api_key": "your_agent_api_key"
}'