Sends input to the Agentic app within a specific session and retrieves the response. This endpoint supports multiple execution modes - synchronous, asynchronous, and streaming.
sessionIdentity- RequiredAn array of objects, each with a type and value, used to identify or create sessions and manage user session mappings. The three supported identifier types are: The objects can be of three types:
sessionIdentity(highest priority)
sessionReference
userReference(lowest priority)
Learn More.input- RequiredAn array of user inputs to the Agentic application. This field can be used to pass the user query or the tool details when a tool is invoked directly.When passing the user input, provide the following fields.
type: Set this to “text”.
content: the actual user input string
When using this API to invoke a tool directly, use the following to pass the tool’s details.
type: Set this to “tool_input”.
content: Use this object to pass the tool parameters.
debug- OptionalControls debug info in the response, useful for troubleshooting, understanding agent behavior, and inspecting intermediate reasoning or function execution. The debug objects contain the following fields:
Enable - set this to true to enable debug information in the response.
debugMode - this can take the following values:
function-call - Includes details about the function(s) triggered by the agent
thoughts - Provides internal reasoning traces of the agent.
all - Includes both function-call and thoughts
Currently, only thoughts are supported.*
stream- OptionalEnable or disable streaming of the agent’s response. This object contains two fields:
enable - set it to true to enable message streaming.
streamMode - set the streaming type. It can take the following values:
tokens: The response is sent token by token as the agent generates it.
messages: Each complete thought or output message is sent as a separate event as soon as it’s available.
custom: Allows for custom streaming behavior
If debug mode is enabled and set to thoughts, irrespective of streamMode, thoughts are always sent as complete messages.isAsync- OptionalIndicates whether the API should execute asynchronously.
false (default): Executes synchronously and returns the result immediately.
true: Executes asynchronously. If the callbackURL is provided, the response is shared on the URL else this API returns a runId that can be used to retrieve the status or result later.
callbackUrl- OptionalThe endpoint to which the asynchronous response should be sent. Must be a valid, publicly accessible URL.
If provided, the Platform makes an HTTP POST request to the callbackURL with the result payload after the processing is complete.
If omitted in an async request, you must use the runId to fetch the result manually.
callbackToken- OptionalAn authentication token included when sending the asynchronous response to the specified callbackUrl. This ensures secure delivery of results to the given endpoint.If callbackToken is provided, it’s included in the HTTP request headers to the callbackURL using the standard Bearer token authentication format:
`Authorization: Bearer <callbackToken>`
attachments- OptionalAllows users to associate files with the session. This object takes the following fields:
enable (String): Set to “true” to attach files to the session
includeFiles (Array): List of file IDs to include as contextual information in the session.
excludeFiles (Array): List of file IDs to exclude from the session.
Once a file is added to the includeFiles list, it remains associated with the session for its duration unless it’s explicitly removed by listing it in excludeFiles.metadata- OptionalAllows users to pass metadata information. This data is stored in sessionMeta and remains available for the duration of the session.invoke- OptionalThis field allows direct invocation of a specific agent or tool within the application, bypassing the orchestrator. It is particularly useful when the client knows exactly which agent or tool should handle the request.The invoke field accepts an array of task objects. Each task object must include:
type:
Set this to “agent” to specify the task as an agent invocation.
Set this to “tool” for invoking a specific tool.
name: The name of the agent or tool you want to invoke.
When the type is set to agent, provide the following additional fields.
toolType: This field is used only for tools. It can take one of the following values - workflow, code or mcp.
agentName : Name of the agent with which the tool is associated.
Example - To invoke a ‘PolicyFinder’ Agent in the app, use the following.
Example: To directly invoke the leaveBalanceById tool in a specific agent, set the invoke field as shown below. Additionally, send the tool’s input parameters in the input field.
The first agent/tool in the tasks array is used for handling the query. If more than one agent/tool is given in this array, the first one is used, and the others are ignored.
source- OptionalIdentifies the system from which the API request is initiated. This field enables better analytics, monitoring, and observability by indicating what triggered the agentic app execution. This field is available as a filter in the session logs.If not provided, the Platform automatically assigns the default value.Recommended Values:
AP: This is the default value. Used when the source field is not explicitly passed.
{ "sessionIdentity": [ { "type": "sessionReference",//Mandatory for associating the Session "value": "s-a302e3c6-308b-4a0a-9a5f-a01a5846fae1" //update Your value }, { "type": "userReference", // Mandatory for associating with the user "value": "usr_1a2b3c4d5e" //update your value } ], "input": [ { "type": "text", "content": "Order me a thick crust medium-sized pizza with extra cheese " // Change the content as required } ], "debug": { "enable": false // Setting to false for no debug response. }, "stream": { "enable": false, // Setting to false for non-streaming response. "streamMode": "tokens" }, "metadata": { // "userProfile": { //custom data "userId": "user123", "preferences": {...} }, "chatHistory": [...], "sourceSystem": "MyApp" }, "isAsync": false // Setting to false for synchronous execution}
Returns the agent’s response to the query along with the session details.
Field
Description
messageId
Unique identifier for the response message
output
Array of agent responses. Each object includes: - type: “text” - content: agent’s response
Artifacts
Array of responses from the tools in the order of execution. For example, if tool 1 was executed followed by tool 2, artifacts[0] will contain the response from tool 1 and artifacts[1] will contain the response from tool 2. Note that the response from a tool is updated in this array only if the ‘Include tool response in artifacts’ flag is enabled in the corresponding tool. Learn More.
sessionInfo
Object containing session metadata such as: - status: current session state - conversationState: for example, COMPLETED - userReference, sessionReference, userId, sessionId, runId, appId
{ "messageId": "msg-915be88a-0fe3-401a-856c-8aec9fa5f641", "output": [ { "type": "text", "content": "Could you please specify the exact crust type you would like for your thick crust pizza?" } ], "sessionInfo": { "status": "idle", "userReference": "u-1", "sessionReference": "s-1", "userId": "u-2e4cbb36-c9a0-52df-8800-b1ab60e137f2", "sessionId": "s-262c98f8-3543-4f1c-a4e7-d96219f10bdc", "runId": "r-ebe5eec7-f12f-467d-b0f8-32e1ef16008d", "appId": "aa-2d38a297-6c74-4ec4-bf72-3b3ee5d326f2", "attachments": [] }}
If debug is enabled, the response has additional information as shown below.
{ "messageId": "msg-ae69b37d-b699-4b2c-b2a6-643778d93607", "output": [ { "type": "text", "content": "Could you please specify the exact crust type you would like for your thick crust pizza?" } ], "debug": [ { "type": "thought", "content": "The user wants to order a pizza with specific customization, including size, crust type, and additional toppings.", "source": "Orchestrator" }, { "type": "thought", "content": "The user has requested a thick crust medium-sized pizza with extra cheese, and I need to place the order and calculate the billing.", "source": "Orchestrator" } ], "sessionInfo": { "status": "idle", "userReference": "u-1", "sessionReference": "s-2", "userId": "u-2e4cbb36-c9a0-52df-8800-b1ab60e137f2", "sessionId": "s-58787f2d-47f9-4ac4-a0d6-422a51e24d65", "runId": "r-78498c8a-da68-4864-b2c6-7301de50507d", "appId": "aa-2d38a297-6c74-4ec4-bf72-3b3ee5d326f2", "attachments": [] }}
Sample Response when OAuth authorization is pending
Note: If any tool used by an agent requires OAuth authorization, the API response for the initial request (when a new session starts) will include a special event of type IDP_Redirect. This event contains a URL that the user must visit to complete the authorization. If the required authorization is not completed, the associated tools will return an error upon invocation.
callbackUrl(optional): The endpoint to which the response must be sent.
callbackToken(optional): Auth token to be passed for authentication on the callbackUrl.
Initiates an agent run.
If callbackUrl is provided, the response is sent to that endpoint upon completion. The Platform makes an HTTP POST request to the callbackURL with the result payload.
If callbackUrl is not provided, the API responds immediately with a runID, which can be used later to query the execution status and response.
If callbackToken is provided, it is included in the HTTP request headers to the callbackURL using the standard Bearer token authentication format:Authorization: Bearer <callbackToken>
Example - Sample Request without Callback URL
{ "sessionIdentity": [ { "type": "sessionReference", "value": "xxxx" } ], "input": [ { "type": "text", "content": "Place an order for a thin crust pizza with bell peppers." } ], "stream": { "enable": false, "streamMode": "tokens" }, "isAsync": true}
ResponseA runId is returned in response. Use this ID to check the status of the run. Refer to the Run Status API to learn more.
{"status": "processing","runId": "r-e4c42e99-39ce-44d6-8ab3-0a3de20c432f","message": "Request is being processed asynchronously"}
Example - Sample Request with Callback URL
{ "sessionIdentity": [ { "type": "sessionReference", "value": "xxxx" } ], "input": [ { "type": "text", "content": "Place an order for a thin crust pizza with bell peppers." } ], "stream": { "enable": false, "streamMode": "tokens" }, "isAsync": true, "callbackUrl": "https://example.org/api/response", "callbackToken": "my-token"}
{ "eventIndex": 1, "messageId": "msg-4b0305d3-de5b-44a2-8ff9-126412ca70de", "output": [ { "type": "text", "content": "Your thick crust medium-sized pizza with extra cheese has been successfully ordered. The total cost for this pizza is $5. If there's anything else you'd like to add or inquire about, please let me know!" } ], "sessionInfo": { "runId": "r-e4c8d69e-faa6-48dd-a306-c5c2b2c624e9" }}
Event 3
{ "eventIndex": 2, "messageId": "msg-1521e406-4abe-4038-abaa-bf54992f22f6", "sessionInfo": { "status": "idle", "userReference": "u-1", "sessionReference": "s-1", "userId": "u-2e4cbb36-c9a0-52df-8800-b1ab60e137f2", "sessionId": "s-262c98f8-3543-4f1c-a4e7-d96219f10bdc", "runId": "r-e4c8d69e-faa6-48dd-a306-c5c2b2c624e9", "appId": "aa-2d38a297-6c74-4ec4-bf72-3b3ee5d326f2", "output": [ { "type": "text", "content": "Your thick crust medium-sized pizza with extra cheese has been successfully ordered. The total cost for this pizza is $5. If there's anything else you'd like to add or inquire about, please let me know!" } ] }, "isLastEvent": true}
Thought Streaming allows the agent to return the intermediate reasoning steps (called “thoughts”) while it’s working and not just the final answer. This helps with transparency and debugging.Thought Streaming can be enabled with the help of debug and streaming config fields.Key Configurations:
"debug": { "enable": true, "debugMode": "thoughts" // Used to get thoughts in the response. }
debugMode
Streaming Enabled?
Behavior
thoughts
No
Thoughts are received as part of the response as an array.
thoughts
Yes
The thoughts and responses are sent back as separate events
Example - Thoughts enabled, streaming disabled.Different reasoning thoughts are part of an array, debug, in the response. Thoughts can be identified by the type fields of the object as shown below.
Example: Thoughts enabled, streaming enabledThe thoughts and responses are sent back as separate events at each step of the processing.Initial Event: - provides the message ID and session details.
You can attach a file to a session and use it in the current execution. This is a two-step process:
Upload the file.Use the File Upload API to upload the desired files. Uploaded files remain available only for the duration of the session.
Include the File in ExecutionAdd the file details while invoking the execute API in the attachments field. You can use the include and exclude arrays to specify the list of files to be added to the current run of the execute API.
Files are not automatically included in the current execution after upload. They must be explicitly listed in the includeFiles array.
The isActive field in the response indicates whether a file was used in the current run:
true → File was included in the execution.
false → File was excluded.
Once a file is added to the includeFiles list, it remains associated with the session for its duration unless it is explicitly removed by listing it in excludeFiles.
Sample Request
{ "sessionIdentity": [ { "type": "sessionReference", "value": "your-session-reference" } ], "input": [ { "type": "text", "content": "your text here" } ], "debug": { "enable": "false" }, "stream": { "enable": "false", "streamMode": "tokens" }, "Attachments": { "enable": true, "includeFiles": "[f-123]", //Array of fileId's to include in the session. "excludeFiles": "[f-456]" //Array of fileId's to exclude from session. } "isAsync": false}
Sample Response
{ "messageId": "msg-04662062-9f63-4854-9b1d-16a9a97b2db6", "output": [ { "type": "text", "content": "Your Response" } ], "sessionInfo": { "status": "idle", "conversationState": "COMPLETED", "userReference": "your-user-reference", "sessionReference": "your-session-reference", "userId": "your-user-id", "sessionId": "current-session-id", "runId": "run-id", "appId": "your-app-id" "attachments": [ { "fileId": "f-123", "isActive": true, "fileName": "file1.pdf", "mimetype": "application/pdf" }, { "fileId": "f-456", "isActive": false, "fileName": "file2.pdf", "mimetype": "application/pdf", "Metadata": { "tokens": 8192, "error": "The combined file content exceeds 80% of the token limit allowed by the {your-llm-model} model (max {maxTokens} tokens)" //Error if file extracted text exceeds the max token } } ] }}
When implementing thought streaming, ensure proper error handling for cases where the connection might be interrupted.
The source field in debug thoughts indicates the origin of each thought (for example, agent, orchestrator), helping pinpoint issues during debugging and trace execution flow across components.
When using streamMode: “tokens”, be aware that only the final output content will be streamed token by token, while debug thoughts will still come as complete messages.
The sessionInfo object contains important tracking information, including the status of the conversation and run identifiers.
For high-frequency thought streams, implement client-side buffering to ensure a smooth user experience and reduce rendering or processing lag.
This is an array of objects with a type and value used to identify or create sessions and manage user session mappings. The three supported identifier types are: The objects can be of three types:
{ "run": { "_id": "r-e4c42e99-39ce-44d6-8ab3-0a3de20c432f", "sessionId": "s-a0e95d6c-c806-4577-bf37-154b026edacf", "status": "success", "metadata": { "isInternalCall": false, "runtimeContext": { "userId": "u-2e4cbb36-c9a0-52df-8800-b1ab60e137f2", "userReference": "u-1", "sessionId": "s-a0e95d6c-c806-4577-bf37-154b026edacf", "sessionReference": "s-3", "accountId": "67bd783757932e0013cad873", "envId": "env-960dca42-9a4a-42f1-9ba9-dc35539c3965", "appId": "aa-2d38a297-6c74-4ec4-bf72-3b3ee5d326f2", "appvId": "av-a0493ab3-91f7-4e12-8c61-be647d282290", "streamId": "st-769dd97d-f973-5f61-be10-d9e4a788e5c6", "asyncConfig": { "isAsync": true, "noTimeout": false, "post_url": "https://example.org/posturl", "app_token": "xxxxxxxx", "asyncTimeout": 180, "isInternalCall": false } } }, "kwargs": { "input": [ { "type": "text", "content": "Order me a thick crust medium-sized pizza with extra cheese " } ], "debug": { "debugMode": "thoughts", "enable": true }, "stream": { "streamMode": "messages", "enable": false }, "output": [ { "type": "text", "content": "To complete your order for a medium-sized thick crust pizza with extra cheese, please let us know if you'd like any additional toppings and your preferred payment method." } ] }, "multitaskStrategy": "reject", "createdAt": "2025-05-16T07:02:34.847Z", "updatedAt": "2025-05-16T07:02:42.263Z", "__v": 0 }}
Check the output only if the status is ‘success’. The output field may contain error details if the status field is otherwise. If status is “pending” or “running”, poll again after a suitable delay.
