/AWS1/IF_BDZ=>INVOKEAGENT()¶
About InvokeAgent¶
Sends a prompt for the agent to process and respond to. Note the following fields for the request:
-
To continue the same conversation with an agent, use the same
sessionIdvalue in the request. -
To activate trace enablement, turn
enableTracetotrue. Trace enablement helps you follow the agent's reasoning process that led it to the information it processed, the actions it took, and the final result it yielded. For more information, see Trace enablement. -
End a conversation by setting
endSessiontotrue. -
In the
sessionStateobject, you can include attributes for the session or prompt or, if you configured an action group to return control, results from invocation of the action group.
The response contains both chunk and trace attributes.
The final response is returned in the bytes field of the chunk object. The InvokeAgent returns one chunk for the entire interaction.
-
The
attributionobject contains citations for parts of the response. -
If you set
enableTracetotruein the request, you can trace the agent's steps and reasoning process that led it to the response. -
If the action predicted was configured to return control, the response returns parameters for the action, elicited from the user, in the
returnControlfield. -
Errors are also surfaced in the response.
Method Signature¶
METHODS /AWS1/IF_BDZ~INVOKEAGENT
IMPORTING
!IO_SESSIONSTATE TYPE REF TO /AWS1/CL_BDZSESSIONSTATE OPTIONAL
!IV_AGENTID TYPE /AWS1/BDZAGENTID OPTIONAL
!IV_AGENTALIASID TYPE /AWS1/BDZAGENTALIASID OPTIONAL
!IV_SESSIONID TYPE /AWS1/BDZSESSIONID OPTIONAL
!IV_ENDSESSION TYPE /AWS1/BDZBOOLEAN OPTIONAL
!IV_ENABLETRACE TYPE /AWS1/BDZBOOLEAN OPTIONAL
!IV_INPUTTEXT TYPE /AWS1/BDZINPUTTEXT OPTIONAL
!IV_MEMORYID TYPE /AWS1/BDZMEMORYID OPTIONAL
!IO_BEDROCKMODELCONFS TYPE REF TO /AWS1/CL_BDZBEDROCKMODELCONFS OPTIONAL
!IO_STREAMINGCONFIGURATIONS TYPE REF TO /AWS1/CL_BDZSTREAMINGCONFS OPTIONAL
!IO_PROMPTCREATIONCONFS TYPE REF TO /AWS1/CL_BDZPRMPTCREATIONCONFS OPTIONAL
!IV_SOURCEARN TYPE /AWS1/BDZAWSRESOURCEARN OPTIONAL
RETURNING
VALUE(OO_OUTPUT) TYPE REF TO /aws1/cl_bdzinvokeagentrsp
RAISING
/AWS1/CX_BDZACCESSDENIEDEX
/AWS1/CX_BDZBADGATEWAYEX
/AWS1/CX_BDZCONFLICTEXCEPTION
/AWS1/CX_BDZDEPENDENCYFAILEDEX
/AWS1/CX_BDZINTERNALSERVEREX
/AWS1/CX_BDZMODELNOTREADYEX
/AWS1/CX_BDZRESOURCENOTFOUNDEX
/AWS1/CX_BDZSERVICEQUOTAEXCDEX
/AWS1/CX_BDZTHROTTLINGEX
/AWS1/CX_BDZVALIDATIONEX
/AWS1/CX_BDZCLIENTEXC
/AWS1/CX_BDZSERVEREXC
/AWS1/CX_RT_TECHNICAL_GENERIC
/AWS1/CX_RT_SERVICE_GENERIC.
IMPORTING¶
Required arguments:¶
iv_agentid TYPE /AWS1/BDZAGENTID /AWS1/BDZAGENTID¶
The unique identifier of the agent to use.
iv_agentaliasid TYPE /AWS1/BDZAGENTALIASID /AWS1/BDZAGENTALIASID¶
The alias of the agent to use.
iv_sessionid TYPE /AWS1/BDZSESSIONID /AWS1/BDZSESSIONID¶
The unique identifier of the session. Use the same value across requests to continue the same conversation.
Optional arguments:¶
io_sessionstate TYPE REF TO /AWS1/CL_BDZSESSIONSTATE /AWS1/CL_BDZSESSIONSTATE¶
Contains parameters that specify various attributes of the session. For more information, see Control session context.
If you include
returnControlInvocationResultsin thesessionStatefield, theinputTextfield will be ignored.
iv_endsession TYPE /AWS1/BDZBOOLEAN /AWS1/BDZBOOLEAN¶
Specifies whether to end the session with the agent or not.
iv_enabletrace TYPE /AWS1/BDZBOOLEAN /AWS1/BDZBOOLEAN¶
Specifies whether to turn on the trace or not to track the agent's reasoning process. For more information, see Trace enablement.
iv_inputtext TYPE /AWS1/BDZINPUTTEXT /AWS1/BDZINPUTTEXT¶
The prompt text to send the agent.
If you include
returnControlInvocationResultsin thesessionStatefield, theinputTextfield will be ignored.
iv_memoryid TYPE /AWS1/BDZMEMORYID /AWS1/BDZMEMORYID¶
The unique identifier of the agent memory.
io_bedrockmodelconfs TYPE REF TO /AWS1/CL_BDZBEDROCKMODELCONFS /AWS1/CL_BDZBEDROCKMODELCONFS¶
Model performance settings for the request.
io_streamingconfigurations TYPE REF TO /AWS1/CL_BDZSTREAMINGCONFS /AWS1/CL_BDZSTREAMINGCONFS¶
Specifies the configurations for streaming.
To use agent streaming, you need permissions to perform the
bedrock:InvokeModelWithResponseStreamaction.
io_promptcreationconfs TYPE REF TO /AWS1/CL_BDZPRMPTCREATIONCONFS /AWS1/CL_BDZPRMPTCREATIONCONFS¶
Specifies parameters that control how the service populates the agent prompt for an
InvokeAgentrequest. You can control which aspects of previous invocations in the same agent session the service uses to populate the agent prompt. This gives you more granular control over the contextual history that is used to process the current request.
iv_sourcearn TYPE /AWS1/BDZAWSRESOURCEARN /AWS1/BDZAWSRESOURCEARN¶
The ARN of the resource making the request.
RETURNING¶
oo_output TYPE REF TO /aws1/cl_bdzinvokeagentrsp /AWS1/CL_BDZINVOKEAGENTRSP¶
Domain /AWS1/RT_ACCOUNT_ID Primitive Type NUMC
Examples¶
Syntax Example¶
This is an example of the syntax for calling the method. It includes every possible argument and initializes every possible value. The data provided is not necessarily semantically accurate (for example the value "string" may be provided for something that is intended to be an instance ID, or in some cases two arguments may be mutually exclusive). The syntax shows the ABAP syntax for creating the various data structures.
DATA(lo_result) = lo_client->invokeagent(
io_bedrockmodelconfs = new /aws1/cl_bdzbedrockmodelconfs( new /aws1/cl_bdzperformanceconf( |string| ) )
io_promptcreationconfs = new /aws1/cl_bdzprmptcreationconfs(
iv_excludepreviousthinking00 = ABAP_TRUE
iv_previousconversationtur00 = 123
)
io_sessionstate = new /aws1/cl_bdzsessionstate(
io_conversationhistory = new /aws1/cl_bdzconversationhist00(
it_messages = VALUE /aws1/cl_bdzmessage=>tt_messages(
(
new /aws1/cl_bdzmessage(
it_content = VALUE /aws1/cl_bdzcontentblock=>tt_contentblocks(
( new /aws1/cl_bdzcontentblock( |string| ) )
)
iv_role = |string|
)
)
)
)
it_files = VALUE /aws1/cl_bdzinputfile=>tt_inputfiles(
(
new /aws1/cl_bdzinputfile(
io_source = new /aws1/cl_bdzfilesource(
io_bytecontent = new /aws1/cl_bdzbytecontentfile(
iv_data = '5347567362473873563239796247513D'
iv_mediatype = |string|
)
io_s3location = new /aws1/cl_bdzs3objectfile( |string| )
iv_sourcetype = |string|
)
iv_name = |string|
iv_usecase = |string|
)
)
)
it_knowledgebaseconfs = VALUE /aws1/cl_bdzknowledgebaseconf=>tt_knowledgebaseconfigurations(
(
new /aws1/cl_bdzknowledgebaseconf(
io_retrievalconfiguration = new /aws1/cl_bdzknowledgebaseret01(
io_vectorsearchconfiguration = new /aws1/cl_bdzknowledgebasevec00(
io_filter = new /aws1/cl_bdzretrievalfilter(
io_equals = new /aws1/cl_bdzfilterattribute(
io_value = /AWS1/CL_RT_DOCUMENT=>FROM_JSON_STR( |\{"foo":"this is a JSON object..."\}| )
iv_key = |string|
)
io_greaterthan = new /aws1/cl_bdzfilterattribute(
io_value = /AWS1/CL_RT_DOCUMENT=>FROM_JSON_STR( |\{"foo":"this is a JSON object..."\}| )
iv_key = |string|
)
io_greaterthanorequals = new /aws1/cl_bdzfilterattribute(
io_value = /AWS1/CL_RT_DOCUMENT=>FROM_JSON_STR( |\{"foo":"this is a JSON object..."\}| )
iv_key = |string|
)
io_in = new /aws1/cl_bdzfilterattribute(
io_value = /AWS1/CL_RT_DOCUMENT=>FROM_JSON_STR( |\{"foo":"this is a JSON object..."\}| )
iv_key = |string|
)
io_lessthan = new /aws1/cl_bdzfilterattribute(
io_value = /AWS1/CL_RT_DOCUMENT=>FROM_JSON_STR( |\{"foo":"this is a JSON object..."\}| )
iv_key = |string|
)
io_lessthanorequals = new /aws1/cl_bdzfilterattribute(
io_value = /AWS1/CL_RT_DOCUMENT=>FROM_JSON_STR( |\{"foo":"this is a JSON object..."\}| )
iv_key = |string|
)
io_listcontains = new /aws1/cl_bdzfilterattribute(
io_value = /AWS1/CL_RT_DOCUMENT=>FROM_JSON_STR( |\{"foo":"this is a JSON object..."\}| )
iv_key = |string|
)
io_notequals = new /aws1/cl_bdzfilterattribute(
io_value = /AWS1/CL_RT_DOCUMENT=>FROM_JSON_STR( |\{"foo":"this is a JSON object..."\}| )
iv_key = |string|
)
io_notin = new /aws1/cl_bdzfilterattribute(
io_value = /AWS1/CL_RT_DOCUMENT=>FROM_JSON_STR( |\{"foo":"this is a JSON object..."\}| )
iv_key = |string|
)
io_startswith = new /aws1/cl_bdzfilterattribute(
io_value = /AWS1/CL_RT_DOCUMENT=>FROM_JSON_STR( |\{"foo":"this is a JSON object..."\}| )
iv_key = |string|
)
io_stringcontains = new /aws1/cl_bdzfilterattribute(
io_value = /AWS1/CL_RT_DOCUMENT=>FROM_JSON_STR( |\{"foo":"this is a JSON object..."\}| )
iv_key = |string|
)
it_andall = VALUE /aws1/cl_bdzretrievalfilter=>tt_retrievalfilterlist(
(
new /aws1/cl_bdzretrievalfilter(
io_equals = new /aws1/cl_bdzfilterattribute(
io_value = /AWS1/CL_RT_DOCUMENT=>FROM_JSON_STR( |\{"foo":"this is a JSON object..."\}| )
iv_key = |string|
)
io_greaterthan = new /aws1/cl_bdzfilterattribute(
io_value = /AWS1/CL_RT_DOCUMENT=>FROM_JSON_STR( |\{"foo":"this is a JSON object..."\}| )
iv_key = |string|
)
io_greaterthanorequals = new /aws1/cl_bdzfilterattribute(
io_value = /AWS1/CL_RT_DOCUMENT=>FROM_JSON_STR( |\{"foo":"this is a JSON object..."\}| )
iv_key = |string|
)
io_in = new /aws1/cl_bdzfilterattribute(
io_value = /AWS1/CL_RT_DOCUMENT=>FROM_JSON_STR( |\{"foo":"this is a JSON object..."\}| )
iv_key = |string|
)
io_lessthan = new /aws1/cl_bdzfilterattribute(
io_value = /AWS1/CL_RT_DOCUMENT=>FROM_JSON_STR( |\{"foo":"this is a JSON object..."\}| )
iv_key = |string|
)
io_lessthanorequals = new /aws1/cl_bdzfilterattribute(
io_value = /AWS1/CL_RT_DOCUMENT=>FROM_JSON_STR( |\{"foo":"this is a JSON object..."\}| )
iv_key = |string|
)
io_listcontains = new /aws1/cl_bdzfilterattribute(
io_value = /AWS1/CL_RT_DOCUMENT=>FROM_JSON_STR( |\{"foo":"this is a JSON object..."\}| )
iv_key = |string|
)
io_notequals = new /aws1/cl_bdzfilterattribute(
io_value = /AWS1/CL_RT_DOCUMENT=>FROM_JSON_STR( |\{"foo":"this is a JSON object..."\}| )
iv_key = |string|
)
io_notin = new /aws1/cl_bdzfilterattribute(
io_value = /AWS1/CL_RT_DOCUMENT=>FROM_JSON_STR( |\{"foo":"this is a JSON object..."\}| )
iv_key = |string|
)
io_startswith = new /aws1/cl_bdzfilterattribute(
io_value = /AWS1/CL_RT_DOCUMENT=>FROM_JSON_STR( |\{"foo":"this is a JSON object..."\}| )
iv_key = |string|
)
io_stringcontains = new /aws1/cl_bdzfilterattribute(
io_value = /AWS1/CL_RT_DOCUMENT=>FROM_JSON_STR( |\{"foo":"this is a JSON object..."\}| )
iv_key = |string|
)
it_orall = VALUE /aws1/cl_bdzretrievalfilter=>tt_retrievalfilterlist(
)
)
)
)
it_orall = VALUE /aws1/cl_bdzretrievalfilter=>tt_retrievalfilterlist(
(
new /aws1/cl_bdzretrievalfilter(
io_equals = new /aws1/cl_bdzfilterattribute(
io_value = /AWS1/CL_RT_DOCUMENT=>FROM_JSON_STR( |\{"foo":"this is a JSON object..."\}| )
iv_key = |string|
)
io_greaterthan = new /aws1/cl_bdzfilterattribute(
io_value = /AWS1/CL_RT_DOCUMENT=>FROM_JSON_STR( |\{"foo":"this is a JSON object..."\}| )
iv_key = |string|
)
io_greaterthanorequals = new /aws1/cl_bdzfilterattribute(
io_value = /AWS1/CL_RT_DOCUMENT=>FROM_JSON_STR( |\{"foo":"this is a JSON object..."\}| )
iv_key = |string|
)
io_in = new /aws1/cl_bdzfilterattribute(
io_value = /AWS1/CL_RT_DOCUMENT=>FROM_JSON_STR( |\{"foo":"this is a JSON object..."\}| )
iv_key = |string|
)
io_lessthan = new /aws1/cl_bdzfilterattribute(
io_value = /AWS1/CL_RT_DOCUMENT=>FROM_JSON_STR( |\{"foo":"this is a JSON object..."\}| )
iv_key = |string|
)
io_lessthanorequals = new /aws1/cl_bdzfilterattribute(
io_value = /AWS1/CL_RT_DOCUMENT=>FROM_JSON_STR( |\{"foo":"this is a JSON object..."\}| )
iv_key = |string|
)
io_listcontains = new /aws1/cl_bdzfilterattribute(
io_value = /AWS1/CL_RT_DOCUMENT=>FROM_JSON_STR( |\{"foo":"this is a JSON object..."\}| )
iv_key = |string|
)
io_notequals = new /aws1/cl_bdzfilterattribute(
io_value = /AWS1/CL_RT_DOCUMENT=>FROM_JSON_STR( |\{"foo":"this is a JSON object..."\}| )
iv_key = |string|
)
io_notin = new /aws1/cl_bdzfilterattribute(
io_value = /AWS1/CL_RT_DOCUMENT=>FROM_JSON_STR( |\{"foo":"this is a JSON object..."\}| )
iv_key = |string|
)
io_startswith = new /aws1/cl_bdzfilterattribute(
io_value = /AWS1/CL_RT_DOCUMENT=>FROM_JSON_STR( |\{"foo":"this is a JSON object..."\}| )
iv_key = |string|
)
io_stringcontains = new /aws1/cl_bdzfilterattribute(
io_value = /AWS1/CL_RT_DOCUMENT=>FROM_JSON_STR( |\{"foo":"this is a JSON object..."\}| )
iv_key = |string|
)
it_andall = VALUE /aws1/cl_bdzretrievalfilter=>tt_retrievalfilterlist(
)
)
)
)
)
io_implicitfilterconf = new /aws1/cl_bdzimplicitfilterconf(
it_metadataattributes = VALUE /aws1/cl_bdzmetadataattrschema=>tt_metadataattributeschemalist(
(
new /aws1/cl_bdzmetadataattrschema(
iv_description = |string|
iv_key = |string|
iv_type = |string|
)
)
)
iv_modelarn = |string|
)
io_rerankingconfiguration = new /aws1/cl_bdzvectorsrchrerank00(
io_bedrockrerankingconf = new /aws1/cl_bdzvectorsrchbedroc00(
io_metadataconfiguration = new /aws1/cl_bdzmetconfforrerank00(
io_selectivemodeconf = new /aws1/cl_bdzrerankingmetseli00(
it_fieldstoexclude = VALUE /aws1/cl_bdzfieldforreranking=>tt_fieldsforreranking(
( new /aws1/cl_bdzfieldforreranking( |string| ) )
)
it_fieldstoinclude = VALUE /aws1/cl_bdzfieldforreranking=>tt_fieldsforreranking(
( new /aws1/cl_bdzfieldforreranking( |string| ) )
)
)
iv_selectionmode = |string|
)
io_modelconfiguration = new /aws1/cl_bdzvectorsrchbedroc01(
it_addlmodelrequestfields = VALUE /aws1/cl_rt_document=>tt_map(
(
VALUE /aws1/cl_rt_document=>ts_document_maprow(
value = /AWS1/CL_RT_DOCUMENT=>FROM_JSON_STR( |\{"foo":"this is a JSON object..."\}| )
key = |string|
)
)
)
iv_modelarn = |string|
)
iv_numberofrerankedresults = 123
)
iv_type = |string|
)
iv_numberofresults = 123
iv_overridesearchtype = |string|
)
)
iv_knowledgebaseid = |string|
)
)
)
it_promptsessionattributes = VALUE /aws1/cl_bdzpromptsessattrsm00=>tt_promptsessionattributesmap(
(
VALUE /aws1/cl_bdzpromptsessattrsm00=>ts_promptsessattrsmap_maprow(
value = new /aws1/cl_bdzpromptsessattrsm00( |string| )
key = |string|
)
)
)
it_returncontrolinvcresults = VALUE /aws1/cl_bdzinvcresultmember=>tt_returncontrolinvcresults(
(
new /aws1/cl_bdzinvcresultmember(
io_apiresult = new /aws1/cl_bdzapiresult(
it_responsebody = VALUE /aws1/cl_bdzcontentbody=>tt_responsebody(
(
VALUE /aws1/cl_bdzcontentbody=>ts_responsebody_maprow(
key = |string|
value = new /aws1/cl_bdzcontentbody(
it_images = VALUE /aws1/cl_bdzimageinput=>tt_imageinputs(
(
new /aws1/cl_bdzimageinput(
io_source = new /aws1/cl_bdzimageinputsource( '5347567362473873563239796247513D' )
iv_format = |string|
)
)
)
iv_body = |string|
)
)
)
)
iv_actiongroup = |string|
iv_agentid = |string|
iv_apipath = |string|
iv_confirmationstate = |string|
iv_httpmethod = |string|
iv_httpstatuscode = 123
iv_responsestate = |string|
)
io_functionresult = new /aws1/cl_bdzfunctionresult(
it_responsebody = VALUE /aws1/cl_bdzcontentbody=>tt_responsebody(
(
VALUE /aws1/cl_bdzcontentbody=>ts_responsebody_maprow(
key = |string|
value = new /aws1/cl_bdzcontentbody(
it_images = VALUE /aws1/cl_bdzimageinput=>tt_imageinputs(
(
new /aws1/cl_bdzimageinput(
io_source = new /aws1/cl_bdzimageinputsource( '5347567362473873563239796247513D' )
iv_format = |string|
)
)
)
iv_body = |string|
)
)
)
)
iv_actiongroup = |string|
iv_agentid = |string|
iv_confirmationstate = |string|
iv_function = |string|
iv_responsestate = |string|
)
)
)
)
it_sessionattributes = VALUE /aws1/cl_bdzsessionattrsmap_w=>tt_sessionattributesmap(
(
VALUE /aws1/cl_bdzsessionattrsmap_w=>ts_sessionattributesmap_maprow(
key = |string|
value = new /aws1/cl_bdzsessionattrsmap_w( |string| )
)
)
)
iv_invocationid = |string|
)
io_streamingconfigurations = new /aws1/cl_bdzstreamingconfs(
iv_applyguardrailinterval = 123
iv_streamfinalresponse = ABAP_TRUE
)
iv_agentaliasid = |string|
iv_agentid = |string|
iv_enabletrace = ABAP_TRUE
iv_endsession = ABAP_TRUE
iv_inputtext = |string|
iv_memoryid = |string|
iv_sessionid = |string|
iv_sourcearn = |string|
).
This is an example of reading all possible response values
lo_result = lo_result.
IF lo_result IS NOT INITIAL.
TRY.
WHILE lo_result->get_completion( )->/aws1/if_rt_stream_reader~data_available( ) = ABAP_TRUE.
lo_event = lo_result->get_completion( )->READ( ).
IF lo_event->get_chunk( ) IS NOT INITIAL.
" process this kind of event
ELSEIF lo_event->get_trace( ) IS NOT INITIAL.
" process this kind of event
ELSEIF lo_event->get_returncontrol( ) IS NOT INITIAL.
" process this kind of event
ELSEIF lo_event->get_files( ) IS NOT INITIAL.
" process this kind of event
ENDIF.
ENDWHILE.
CATCH /aws1/cx_bdzaccessdeniedex.
" handle error in stream
CATCH /aws1/cx_bdzinternalserverex.
" handle error in stream
CATCH /aws1/cx_bdzmodelnotreadyex.
" handle error in stream
CATCH /aws1/cx_bdzvalidationex.
" handle error in stream
CATCH /aws1/cx_bdzthrottlingex.
" handle error in stream
CATCH /aws1/cx_bdzdependencyfailedex.
" handle error in stream
CATCH /aws1/cx_bdzbadgatewayex.
" handle error in stream
CATCH /aws1/cx_bdzresourcenotfoundex.
" handle error in stream
CATCH /aws1/cx_bdzservicequotaexcdex.
" handle error in stream
CATCH /aws1/cx_bdzconflictexception.
" handle error in stream
ENDTRY.
lv_mimetype = lo_result->get_contenttype( ).
lv_sessionid = lo_result->get_sessionid( ).
lv_memoryid = lo_result->get_memoryid( ).
ENDIF.