API Reference

Version 2.0

Blocking Continue Session

POST/api/v2/aipAgents/agents/{agentRid}/sessions/{sessionRid}/blockingContinue

Warning

This endpoint is in preview and may be modified or removed at any time. To use this endpoint, add preview=true to the request query parameters.

Continue a conversation session with an Agent, or add the first exchange to a session after creation. Adds a new exchange to the session with the provided inputs, and generates a response from the Agent. Blocks on returning the result of the added exchange until the response is fully generated. Streamed responses are also supported; see streamingContinue for details. Concurrent requests to continue the same session are not supported. Clients should wait to receive a response before sending the next message.

Third-party applications using this endpoint via OAuth2 must request the following operation scope: api:aip-agents-write.

Path parameters

agentRid

string

An RID identifying an AIP Agent created in AIP Agent Studio.

sessionRid

string

The Resource Identifier (RID) of the conversation session.

Query parameters

preview

boolean

optional

Enables the use of preview functionality.

Request body

BlockingContinueSessionRequest

object

Hide child attributes

userInput

object

The user message for the Agent to respond to.

Show child attributes

parameterInputs

map<ParameterId, ParameterValue>

optional

Any supplied values for application variables to pass to the Agent for the exchange.

Show child attributes

contextsOverride

list<InputContext>

optional

If set, automatic context retrieval is skipped and the list of specified context is provided to the Agent instead. If omitted, relevant context for the user message is automatically retrieved and included in the prompt, based on data sources configured on the Agent for the session.

Show child attributes

Response body

SessionExchangeResult

object

The result of the added exchange for the session.

Hide child attributes

agentMarkdownResponse

string

The final text response generated by the Agent. Responses are formatted using markdown.

parameterUpdates

map<ParameterId, ParameterValueUpdate>

optional

Any updates to application variable values which were generated by the Agent for this exchange. Updates can only be generated for application variables configured with READ_WRITE access on the Agent in AIP Agent Studio.

Show child attributes

totalTokensUsed

integer

optional

Total tokens used to compute the result. Omitted if token usage information is not supported by the model used for the session.

interruptedOutput

boolean

True if the exchange was canceled. In that case, the response (if any) was provided by the client as part of the cancellation request rather than by the Agent.

Examples

Request

Copied!

curl -X POST \
	-H "Content-type: application/json" \
	-H "Authorization: Bearer $TOKEN" \
	"https://$HOSTNAME/api/v2/aipAgents/agents/ri.aip-agents..agent.732cd5b4-7ca7-4219-aabb-6e976faf63b1/sessions/ri.aip-agents..session.292db3b2-b653-4de6-971c-7e97a7b881d6/blockingContinue?preview=true" \
	-d '{"userInput":{"text":"What is the status of my order?"},"parameterInputs":{"currentCustomerOrders":{"type":"objectSet","ontology":"example-ontology","objectSet":{"type":"filter","objectSet":{"type":"base","objectType":"customerOrder"},"where":{"type":"eq","field":"customerId","value":"123abc"}}}}}'

Response

Copied!

{
  "totalTokensUsed": 6448,
  "agentMarkdownResponse": "The status of your order is **In Transit**.",
  "interruptedOutput": false
}

Error responses

Error Name
`ContextSizeExceededLimit`	Error Code	`INVALID_ARGUMENT`
	Status Code	400
	Description	Failed to generate a response for a session because the context size of the LLM has been exceeded. Clients should either retry with a shorter message or create a new session and try re-sending the message.
	Parameters	`agentRid, sessionRid, details`
`AgentIterationsExceededLimit`	Error Code	`INVALID_ARGUMENT`
	Status Code	400
	Description	The Agent was unable to produce an answer in the set number of maximum iterations. This can happen if the Agent gets confused or stuck in a loop, or if the query is too complex. Try a different query or review the Agent configuration in AIP Agent Studio.
	Parameters	`agentRid, sessionRid, details`
`SessionExecutionFailed`	Error Code	`INTERNAL`
	Status Code	500
	Description	Failed to generate a response for a session due to an unexpected error.
	Parameters	`agentRid, sessionRid, message, details`
`RateLimitExceeded`	Error Code	`CUSTOM_CLIENT`
	Status Code	400
	Description	Failed to generate a response as the model rate limits were exceeded. Clients should wait and retry.
	Parameters	`agentRid, sessionRid, details`
`InvalidParameter`	Error Code	`INVALID_ARGUMENT`
	Status Code	400
	Description	The provided application variable is not valid for the Agent for this session. Check the available application variables for the Agent under the `parameters` property, and version through the API with `getAgent`, or in AIP Agent Studio. The Agent version used for the session can be checked through the API with `getSession`.
	Parameters	`agentRid, sessionRid, parameter`
`InvalidParameterType`	Error Code	`INVALID_ARGUMENT`
	Status Code	400
	Description	The provided value does not match the expected type for the application variable configured on the Agent for this session. Check the available application variables for the Agent under the `parameters` property, and version through the API with `getAgent`, or in AIP Agent Studio. The Agent version used for the session can be checked through the API with `getSession`.
	Parameters	`agentRid, sessionRid, parameter, expectedType, receivedType`
`ObjectTypeIdsNotFound`	Error Code	`NOT_FOUND`
	Status Code	404
	Description	Some object types are configured for use by the Agent but could not be found. The object types either do not exist or the client token does not have access. Object types can be checked by listing available object types through the API, or searching in [Ontology Manager](/docs/foundry/ontology-manager/overview/).
	Parameters	`agentRid, sessionRid, objectTypeIds`
`ObjectTypeRidsNotFound`	Error Code	`NOT_FOUND`
	Status Code	404
	Description	Some object types are configured for use by the Agent but could not be found. The object types either do not exist or the client token does not have access. Object types can be checked by listing available object types through the API, or searching in [Ontology Manager](/docs/foundry/ontology-manager/overview/).
	Parameters	`agentRid, sessionRid, objectTypeRids`
`FunctionLocatorNotFound`	Error Code	`NOT_FOUND`
	Status Code	404
	Description	The specified function locator is configured for use by the Agent but could not be found. The function type or version may not exist or the client token does not have access.
	Parameters	`agentRid, sessionRid, functionRid, functionVersion`
`BlockingContinueSessionPermissionDenied`	Error Code	`PERMISSION_DENIED`
	Status Code	403
	Description	Could not blockingContinue the Session.
	Parameters	`agentRid, sessionRid`

See Errors for a general overview of errors in the platform.