Interact with an Agent API Definition

The Interact with an Agent API enables you to create new inputs to an agent to interact with it. This API serves as the primary interface for conversational interactions and represents the core mechanism through which users communicate with AI agents.

When you send an input to an agent, it triggers agent processing, reasoning, tool execution, and response generation within the context of an agent session.

Interact with an Agent Request and Response

To interact with an agent, 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