Skip to content

Runs API

Provides API endpoints to execute the Agentic application within a session.

Execute a Run

Sends input to the Agentic app within a specific session and retrieves the response. This endpoint supports multiple execution modes - synchronous, asynchronous, and streaming.

Method POST
Endpoint /apps/<AppID>/environments/<EnvName>/runs/execute
Content-type application/json
Authorization Header x-api-key: <API-KEY>

Path Parameters

Fields Description
AppID Unique Identifier for the app.
EnvName Name of the environment to be used for the agent.

Request Parameters

Fields Description Mandatory
sessionIdentity An 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:
  1. userReference (highest priority)
  2. sessionReference
  3. sessionIdentity(lowest priority)
    4. Refer to [this](overview.md) for a detailed description.
Yes
input An array of user inputs to the Agentic application. Each object includes:

- type: currently only "text" is supported. - content: the actual user input string.

Yes
debug Controls 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.

No
stream Enable or disable streaming of the response from the agent. This object contains two fields:
  • enable - set it to true to enable the streaming of messages.
  • streamMode - set the type of streaming. 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.

No
isAsync Set this to true for asynchronous execution. Defaults to false for synchronous execution. In case of async operations, a runId is returned, allowing you to check the status later. No
attachments Allows users to associate files with the session. This object takes the following fields:
  • enable: Set to true to attach files to the session
  • includeFiles : List of file IDs to include as contextual information in the session.
  • excludeFiles : 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 is explicitly removed by listing it in excludeFiles. 		No
metadata Allows users to pass metadata information. This data is set to the sessionMeta memory and is available for the duration of the session. No
invoke This field allows direct invocation of a specific agent within the application, bypassing the orchestrator. It is particularly useful when the client knows exactly which agent 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.
  • name: The name of the agent you want to invoke.
Example - To invoke a ‘PolicyFinder’ Agent in the app, use the following. 
  "invoke": {
    "tasks": [
      {
        "type": "agent",
        "name": "PolicyFinder"
      }
    ]
  }
No

Sample Request

{
  "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" 
  },
  "isAsync": false // Setting to false for synchronous execution
}

Response

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

sessionInfo Object containing session metadata such as:

- status: current session state

- conversationState: e.g., COMPLETED

- userReference, sessionReference, userId, sessionId, runId, appId

Sample Response

{
  "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": []
  }
}

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.

{
  "events": [
    {
      "type": "IDP_Redirect",
      "content": {
        "auth_profiles": [
          {
            "url": "https://agent-platform.kore.ai/r/396c63515671634648357955",
            "idpName": "Google",
            "isAuthorized": false,
            "sso_type": "oauth2"
          }
        ]
      }
    }
  ]
}

Execution Modes

Synchronous Execution

  • Waits for the agent to respond. Best for real-time interactions.

  • Key configuration:

     "isAsync": false

Sample Request: 

{
 "sessionIdentity": [
   {
     "type": "sessionReference",
     "value": "s_c234234mf4x"
   }
 ],
 "input": [
   {
     "type": "text",
     "content": "Hi!"
   } 
 ],
 "stream": {
   "enable": false,
   "streamMode": "tokens"
 },
 "isAsync": false
}

Asynchronous Execution

  • Initiates an agent run but returns immediately with a runID, allowing you to check the status later.
  • Key configuration field:"isAsync": true

Example - Sample Request

{
 "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
}

Response

A 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"
}

Streaming Execution

  • Enables streaming of response from the agent. Returns tokens or messages as the agent responds.
  • Key Configuration fields:
  • stream.enable: Set to "true" to enable streaming
  • stream.streamMode:
    • "messages" - Sends complete messages as they're generated
    • "tokens" - Streams final results as tokens.
    • "custom" - For customized streaming behavior

Series of Responses (streamMode: “messages”)

Event 1

{
  "eventIndex": 0,
  "messageId": "msg-d13eab67-6942-488a-9546-49859b41f088",
  "sessionInfo": {
    "status": "busy",
    "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"
  }
}

Event 2

{
  "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
}

Additional Features

Thought Streaming

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. 

{
  "messageId": "msg-123",
  "output": [
    {
      "type": "text",
      "content": "Final answer"
    }
  ],
  "debug": [
    {
      "type": "thought",
      "content": "Analyzing the query...",
    },
    {
      "type": "thought",
      "content": "Processing data...",
    }
  ],
  "sessionInfo": {}
}

Example: Thoughts enabled, streaming enabled

The thoughts and responses are sent back as separate events at each step of the processing.

Initial Event: - provides the message ID and session details. 

{
  "messageId": "msg-123",
  "sessionInfo": { /* Session details */ }
}

Thought Events: Contains the thoughts as part of debug array. 

{
  "messageId": "msg-123",
  "debug": [
    {
      "type": "thought",
      "content": "Going to Agent A",
      "source": "AgentName" // Optional source identifier
    }
  ],
  "sessionInfo": { "runId": "run-123" }
}

Output Token Events (when streamMode = "token") - Contains the output as part of output array. 

{ 
  "messageId": "msg-123",
  "output": [
    {
      "type": "text",
      "content": "Streamed tokens",
    }
  ]
}

Final Event: Contains session details. 

{
  "messageId": "msg-123",
  "sessionInfo": { /* Updated session details */ }
}

Adding Attachments to a session

You can attach a file to a session and use it in the current execution. This is a two-step process:

  1. Upload the file.

    Use the File Upload API to upload the desired files. Uploaded files remain available only for the duration of the session.

  2. Include the File in Execution

    Add 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.

Note

  • 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.
     "exludeFiles": "[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
                          } 
           }
       ]
   }
}

Points to Notes

  1. When implementing thought streaming, ensure proper error handling for cases where the connection might be interrupted.
  2. The source field in debug thoughts indicates the origin of each thought (e.g., agent, orchestrator), helping pinpoint issues during debugging and trace execution flow across components.
  3. 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.
  4. The sessionInfo object contains important tracking information, including the status of the conversation and run identifiers.
  5. For high-frequency thought streams, implement client-side buffering to ensure a smooth user experience and reduce rendering or processing lag.

Find Run Status

Returns the status and response of a run. It is useful for asynchronous runs.

Method POST
Endpoint /apps/<AppID>/environments/<EnvName>/runs/<runId>/status
Content-type application/json
Authorization Header x-api-key: <API-KEY>

Path Parameters

Fields Description
AppID Unique Identifier for the app.
EnvName Name of the environment to be used for the agent.
RunID Unique identifier of the run

Request Parameters

Fields Description
sessionIdentity 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:
  1. userReference (highest priority)
  2. sessionReference
  3. sessionIdentity(lowest priority)
    4. Refer to this for a detailed description.

    This is useful for verifying the context and permissions on the run.

Sample Request

{
 "sessionIdentity": [
  {
     "type": "sessionReference",
     "value": "your-session-reference" // update your value 
   }]
}

Response

Returns the current status and details of the run. The important fields include:

  • run.status: Describes the current status of the run. It can have the following values:
    • success - The run completed successfully without any errors.
    • failed - The run encountered an error and did not complete successfully.
    • Pending - The run has been created but has not started yet.
    • Running - The run is currently in progress.
  • run.kwargs.output: Contains the final result after a successful run.

Sample Response

{
  "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": "chandrima.cherkuthota@kore.com",
          "app_token": "chandrimaRao@2512",
          "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
  }
}

Note

  • 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.