Create Agent Event API Definition

The Create Agent Event API enables you to initiate new interactions within agent sessions by submitting user input messages that trigger agent processing, reasoning, tool execution, and response generation. This API serves as the primary interface for conversational interactions and represents the core mechanism through which users communicate with AI agents.

Organizations use this API to power customer support chat interfaces, internal business process interactions, technical assistance conversations, and any application where users need to engage in meaningful dialogue with intelligent agents that can reason, access tools, and provide contextual responses.

Create Agent Event Request and Response

To create an agent event, send a POST request to /v2/agents/{agent_key}/sessions/{session_key}/events. You specify the following parameters:

• agent_key (string, required): Agent identifier in the URL path following pattern [0-9a-zA-Z_-]+$
• session_key (string, required): Session identifier in the URL path following pattern [0-9a-zA-Z_-]+$
• Request body parameters:
  • type (string, required): Event type (must be input_message)
  • messages (array, required): List of input message objects
    • type (string, required): Message type (must be text)
    • content (string, required): Text content of the user input
  • stream_response (boolean, optional): Enable streaming response delivery via Server-Sent Events (defaults to false)

The response format depends on the stream_response parameter:

• When false: Returns an AgentResponse with complete list of events
• When true: Returns Server-Sent Events stream with individual AgentStreamedResponse events

Example Request

EXAMPLE REQUESTjson

1

Example Response (Non-streaming)

EXAMPLE RESPONSEjson

1

Example Streaming Response

EXAMPLE STREAMING RESPONSEbash

1

Event Types

The following event types may appear in responses:

• input_message: User input message
• thinking: Agent reasoning/chain-of-thought
• tool_input: Tool execution request
• tool_output: Tool execution result
• agent_output: Final agent response
• context_limit_exceeded: Token limit exceeded notification

For streaming responses, additional event types include:

• streaming_thinking: Progressive thinking content
• streaming_thinking_end: End of thinking stream
• streaming_agent_output: Progressive agent output
• streaming_agent_output_end: End of output stream
• error: Stream error
• end: Stream completion

Error Responses

The API returns standard HTTP error codes with detailed error information:

HTTP Code	Error Code	Description
400	invalid_request	Missing required fields or malformed request structure
400	invalid_message_content	Message content is empty or exceeds length limit
401	unauthorized	Invalid or missing API key
403	forbidden	Insufficient permissions for creating events in this session
404	agent_not_found	Agent with the specified key does not exist
404	session_not_found	Session with the specified key does not exist
429	rate_limit_exceeded	Event creation rate limit exceeded
500	agent_processing_failed	Internal error during agent processing