Streaming

The Agent Execution endpoint allows streaming via Server-Sent Events (SSE) to deliver real-time updates. The API responds with Content-Type: text/event-stream and sends continuous JSON events containing progress updates, task information, and content fragments.

To enable streaming, you must use API version v2 and explicitly set the stream parameter to true:

curl -X POST \
  -L "https://api.serenitystar.ai/api/v2/agent/my-agent/execute" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your-api-key-here" \
  -d '[
    {
        "key": "message",
        "value": "<YOUR MESSAGE>"
    },
    {
        "key": "stream",
        "value": true
    }
]'

Response Format

When streaming is enabled, the response will have:

• Content-Type: text/event-stream
• Body: Server-sent events with JSON chunks

Here's an example of a streaming response where the Agent executed the "SearchTechNewsByTag" skill and then answered:

event: start 
data: {"type":"start","start_time_utc":"2025-08-28T19:57:35.6516358Z"} 

event: task_start 
data: {"type":"task_start","task":"Loading configuration","task_key":"configuration_load","start_time_utc":"2025-08-28T19:57:35.6516405Z"} 

event: task_stop 
data: {"type":"task_stop","task":"Loading configuration","task_key":"configuration_load","start_time_utc":"2025-08-28T19:57:35.6516405Z","end_time_utc":"2025-08-28T19:57:35.6554294Z","duration":"00:00:00.0037889"} 

event: task_start 
data: {"type":"task_start","task":"Validating configuration","task_key":"configuration_validate","start_time_utc":"2025-08-28T19:57:35.6578095Z"} 

event: task_stop 
data: {"type":"task_stop","task":"Validating configuration","task_key":"configuration_validate","start_time_utc":"2025-08-28T19:57:35.6578095Z","end_time_utc":"2025-08-28T19:57:35.6745935Z","duration":"00:00:00.0167840"} 

event: task_start 
data: {"type":"task_start","task":"Loading plugins","task_key":"skills_load","start_time_utc":"2025-08-28T19:57:35.6750565Z"} 

event: task_stop 
data: {"type":"task_stop","task":"Loading plugins","task_key":"skills_load","start_time_utc":"2025-08-28T19:57:35.6750565Z","end_time_utc":"2025-08-28T19:57:35.6786154Z","duration":"00:00:00.0035589"} 

event: task_start 
data: {"type":"task_start","task":"Calculating remaining token budget","task_key":"context_token_budget_calculate","start_time_utc":"2025-08-28T19:57:35.6787358Z"} 

event: task_stop 
data: {"type":"task_stop","task":"Calculating remaining token budget","task_key":"context_token_budget_calculate","start_time_utc":"2025-08-28T19:57:35.6787358Z","end_time_utc":"2025-08-28T19:57:35.6789525Z","duration":"00:00:00.0002167"} 

event: task_start 
data: {"type":"task_start","task":"Appending context","task_key":"context_append","start_time_utc":"2025-08-28T19:57:35.6790014Z"} 

event: task_stop 
data: {"type":"task_stop","task":"Appending context","task_key":"context_append","start_time_utc":"2025-08-28T19:57:35.6790014Z","end_time_utc":"2025-08-28T19:57:35.6790892Z","duration":"00:00:00.0000878"} 

event: task_start 
data: {"type":"task_start","task":"Getting AI response","task_key":"llm_response","start_time_utc":"2025-08-28T19:57:35.6791352Z"} 

event: task_start 
data: {"type":"task_start","task":"Executing Skill: SearchTechNewsByTag","task_key":"skills_SearchTechNewsByTag_execute","start_time_utc":"2025-08-28T19:57:37.5648748Z"} 

event: task_stop 
data: {"type":"task_stop","task":"Executing Skill: SearchTechNewsByTag","task_key":"skills_SearchTechNewsByTag_execute","start_time_utc":"2025-08-28T19:57:37.5648748Z","end_time_utc":"2025-08-28T19:57:37.5878491Z","duration":"00:00:00.0229743"} 

event: content 
data: {"type":"content","text":"##"} 

event: content 
data: {"type":"content","text":" AI"} 

event: content 
data: {"type":"content","text":" News"} 

event: content 
data: {"type":"content","text":" Titles"} 

event: content 
data: {"type":"content","text":" from"} 

event: content 
data: {"type":"content","text":" the"} 

event: content 
data: {"type":"content","text":" Past"} 

event: content 
data: {"type":"content","text":" Day"} 

event: content 
data: {"type":"content","text":"\n\n"} 

// ... More content events until the answer is complete

event: task_stop 
data: {"type":"task_stop","task":"Getting AI response","task_key":"llm_response","start_time_utc":"2025-08-28T19:57:35.6791352Z","end_time_utc":"2025-08-28T19:57:43.7378139Z","duration":"00:00:08.0586787"} 

event: task_start 
data: {"type":"task_start","task":"Calculating prices","task_key":"agent_instance_fares_create","start_time_utc":"2025-08-28T19:57:43.7380517Z"} 

event: task_stop 
data: {"type":"task_stop","task":"Calculating prices","task_key":"agent_instance_fares_create","start_time_utc":"2025-08-28T19:57:43.7380517Z","end_time_utc":"2025-08-28T19:57:43.7564954Z","duration":"00:00:00.0184437"} 

event: task_start 
data: {"type":"task_start","task":"Updating chat","task_key":"agent_instance_update","start_time_utc":"2025-08-28T19:57:43.7565907Z"} 

event: task_stop 
data: {"type":"task_stop","task":"Updating chat","task_key":"agent_instance_update","start_time_utc":"2025-08-28T19:57:43.7565907Z","end_time_utc":"2025-08-28T19:57:43.7643612Z","duration":"00:00:00.0077705"} 

event: stop 
data: {"type":"stop","stop_time_utc":"2025-08-28T19:57:43.8178096Z","result":{"content":"## AI News Titles from the Past Day\n\n...","completion_usage":{"completion_tokens":256,"prompt_tokens":15497,"total_tokens":15753},"cost":{"completion":0.000512,"prompt":0.015497,"total":0.016009,"currency":"EUR"},"action_results":{},"time_to_first_token":3340,"instance_id":"49b0b3cc-614a-442c-9475-22f39e005ca3","executor_task_logs":[{"key":"configuration_load","description":"Loading configuration","duration":3,"success":true},{"key":"configuration_validate","description":"Validating configuration","duration":16,"success":true},{"key":"skills_load","description":"Loading plugins","duration":3,"success":true},{"key":"context_token_budget_calculate","description":"Calculating remaining token budget","duration":0,"success":true},{"key":"context_append","description":"Appending context","duration":0,"success":true},{"key":"llm_response","description":"Getting AI response","duration":8058,"success":true},{"key":"skills_SearchTechNewsByTag_execute","description":"Executing Skill: SearchTechNewsByTag","duration":22,"success":true},{"key":"agent_instance_fares_create","description":"Calculating prices","duration":18,"success":true},{"key":"agent_instance_update","description":"Updating chat","duration":7,"success":true}]}} 

Event Types

The stream contains different message types that provide real-time execution information:

start

• Purpose: Indicates the beginning of agent execution
• Frequency: Always the first message
• Contains: Execution start timestamp

content

• Purpose: Contains chunks of the agent's response
• Frequency: Multiple messages per execution
• Contains: Text content from the agent

task_start / task_stop

• Purpose: Tracks internal agent tasks (validations, skill invocations, knowledge searches, etc.)
• Frequency: Varies based on agent complexity
• Contains: Task details, timestamps, and duration

Example:

event: task_start 
data: {"type":"task_start","task":"Appending context","task_key":"context_append","start_time_utc":"2025-08-28T19:57:35.6790014Z"} 

event: task_stop 
data: {"type":"task_stop","task":"Appending context","task_key":"context_append","start_time_utc":"2025-08-28T19:57:35.6790014Z","end_time_utc":"2025-08-28T19:57:35.6790892Z","duration":"00:00:00.0000878"} 

Here are all the task types currently defined:

• configuration_load: Loads the agent configuration.
• configuration_validate: Validates the agent configuration and input parameters.
• request_validate: Validates the AI Proxy agent request format.
• context_append: Appends the context to the LLM request including knowledge sections and chat history.
• context_token_budget_calculate: Calculates the token budget for knowledge, volatile knowledge, and chat history.
• context_knowledge_search: Searches the agent's knowledge base for relevant sections
• context_ai_powered_knowledge_search_prepare: Prepares the AI Powered knowledge search.
• context_volatileknowledge_search: Searches the conversation's volatile knowledge base for relevant sections.
• sensitive_data_system_definition_obfuscate: Obfuscates sensitive data in system definitions.
• sensitive_data_user_input_obfuscate: Obfuscates sensitive data in user input.
• agent_instance_create: Creates a new agent instance.
• agent_instance_update: Updates an existing agent instance.
• agent_instance_fares_create: Create the fare related to the agent instance.
• safety_metacontrol_execute: Executes the metacontrol module.
• safety_alinia_execute: Executes Alinia Moderations.
• safety_input_moderate: Moderates user input for safety.
• skills_load: Loads the agent's skills.
• skills_{skill_code}_execute: Executes the skill with the specified code.
• skills_{skill_code}_execute_from_cache: Uses the cached version of the skill's result.
• skills_emulator_execute: Executes the skills emulator.
• output_format_validate: Validates the output format to verify its a valid JSON.
• llm_response: Invokes the LLM for a response.

stop

• Purpose: Indicates successful completion
• Frequency: Final message on success
• Contains: Execution results and stop timestamp

error

• Purpose: Reports execution errors that occur during streaming
• Frequency: Final message on failure
• Contains: Error details and status codes

ping

• Purpose: Keeps the connection alive
• Frequency: Periodic
• Action: Can be safely ignored

Error Handling

Pre-Stream Errors (400 Bad Request)

Validation errors that occur before streaming starts return:

• Content-Type: application/json
• Status Code: 400
• Common Causes:
  • Incorrect input parameters
  • Quota limits reached
  • Invalid request format

Example:

{
    "errors": {
        "message_required": "The parameter 'Message' is required."
    },
    "message": "A validation error occurred during the agent execution",
    "statusCode": 400
}

Stream Errors

Errors that occur during execution are sent as error message types and may happen when:

• Internal agent tasks fail
• LLM vendor API is unavailable
• Vendor-side validation errors occur

Example:

event: task_start 
data: { "type": "error", "status": 400, "message": "The vendor failed with a client validation error (Code 0065)", "errors": { "vendor_error": "Incorrect API key provided" } }

Rate Limit Errors (429 Too Many Requests)

When rate limits are exceeded:

• Content-Type: text/plain
• Status Code: 429
• Body: Plain text with rate limit details
• Example: "API calls quota exceeded! maximum admitted 1000 per 1m."