invoke_agent¶
Operation¶
Async only
This operation uses an event stream, so only the asynchronous client supports it.
invoke_agent
async
¶
invoke_agent(request: InvokeAgentInput | InvokeAgentInputDict | None = None, /, *, plugins: list[Plugin] | None = None, **kwargs: Unpack[InvokeAgentInputDict]) -> AsyncOutputEventStream[ResponseStream, InvokeAgentOutput]
Note
Amazon Bedrock Agents (now Amazon Bedrock Agents Classic) is no longer open to new customers. For capabilities similar to Bedrock Agents Classic, explore Amazon Bedrock AgentCore. Existing customers can continue to use the service as normal. For more information, see Amazon Bedrock Agents Classic availability change.
Note:
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.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
request
|
InvokeAgentInput | InvokeAgentInputDict | None
|
The input as a model or dictionary. Pass this or keyword arguments, not both. |
None
|
plugins
|
list[Plugin] | None
|
A list of callables that modify the configuration dynamically. Changes made by these plugins only apply for the duration of the operation execution and will not affect any other operation invocations. |
None
|
**kwargs
|
Unpack[InvokeAgentInputDict]
|
The input fields as keyword arguments. |
{}
|
Returns:
| Type | Description |
|---|---|
AsyncOutputEventStream[ResponseStream, InvokeAgentOutput]
|
An |
Input¶
Pass the input as keyword arguments, a positional dictionary, or a positional model object. Pass plugins separately as a keyword argument.
InvokeAgentInputDict
¶
Bases: TypedDict
Dictionary form of InvokeAgentInput.
Attributes¶
bedrock_model_configurations
instance-attribute
¶
bedrock_model_configurations: BedrockModelConfigurations | BedrockModelConfigurationsDict | None
Model performance settings for the request.
enable_trace
instance-attribute
¶
enable_trace: bool | None
Specifies whether to turn on the trace or not to track the agent's reasoning process. For more information, see Trace enablement.
end_session
instance-attribute
¶
end_session: bool | None
Specifies whether to end the session with the agent or not.
input_text
instance-attribute
¶
input_text: str | None
The prompt text to send the agent.
Note
If you include returnControlInvocationResults in the sessionState
field, the inputText field will be ignored.
prompt_creation_configurations
instance-attribute
¶
prompt_creation_configurations: PromptCreationConfigurations | PromptCreationConfigurationsDict | None
Specifies parameters that control how the service populates the agent
prompt for an InvokeAgent request. 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.
session_id
instance-attribute
¶
The unique identifier of the session. Use the same value across requests to continue the same conversation.
session_state
instance-attribute
¶
session_state: SessionState | SessionStateDict | None
Contains parameters that specify various attributes of the session. For more information, see Control session context.
Note
If you include returnControlInvocationResults in the sessionState
field, the inputText field will be ignored.
streaming_configurations
instance-attribute
¶
streaming_configurations: StreamingConfigurations | StreamingConfigurationsDict | None
Specifies the configurations for streaming.
Note
To use agent streaming, you need permissions to perform the
bedrock:InvokeModelWithResponseStream action.
InvokeAgentInput
dataclass
¶
Bases: _SerdeShape
Dataclass for InvokeAgentInput structure.
Attributes¶
agent_alias_id
class-attribute
instance-attribute
¶
agent_alias_id: str | None = ...
The alias of the agent to use.
agent_id
class-attribute
instance-attribute
¶
agent_id: str | None = ...
The unique identifier of the agent to use.
bedrock_model_configurations
class-attribute
instance-attribute
¶
bedrock_model_configurations: BedrockModelConfigurations | None = ...
Model performance settings for the request.
enable_trace
class-attribute
instance-attribute
¶
enable_trace: bool | None = ...
Specifies whether to turn on the trace or not to track the agent's reasoning process. For more information, see Trace enablement.
end_session
class-attribute
instance-attribute
¶
end_session: bool | None = ...
Specifies whether to end the session with the agent or not.
input_text
class-attribute
instance-attribute
¶
input_text: str | None = ...
The prompt text to send the agent.
Note
If you include returnControlInvocationResults in the sessionState
field, the inputText field will be ignored.
memory_id
class-attribute
instance-attribute
¶
memory_id: str | None = ...
The unique identifier of the agent memory.
prompt_creation_configurations
class-attribute
instance-attribute
¶
prompt_creation_configurations: PromptCreationConfigurations | None = ...
Specifies parameters that control how the service populates the agent
prompt for an InvokeAgent request. 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.
session_id
class-attribute
instance-attribute
¶
session_id: str | None = ...
The unique identifier of the session. Use the same value across requests to continue the same conversation.
session_state
class-attribute
instance-attribute
¶
session_state: SessionState | None = ...
Contains parameters that specify various attributes of the session. For more information, see Control session context.
Note
If you include returnControlInvocationResults in the sessionState
field, the inputText field will be ignored.
source_arn
class-attribute
instance-attribute
¶
source_arn: str | None = ...
The ARN of the resource making the request.
streaming_configurations
class-attribute
instance-attribute
¶
streaming_configurations: StreamingConfigurations | None = ...
Specifies the configurations for streaming.
Note
To use agent streaming, you need permissions to perform the
bedrock:InvokeModelWithResponseStream action.
Output¶
This operation returns an AsyncOutputEventStream for server-to-client streaming.
Event Stream Structure¶
Output Event Type¶
Initial Response Structure¶
InvokeAgentOutput
dataclass
¶
Bases: _SerdeShape
Dataclass for InvokeAgentOutput structure.
Attributes¶
content_type
instance-attribute
¶
content_type: str
The MIME type of the input data in the request. The default value is
application/json.
memory_id
class-attribute
instance-attribute
¶
memory_id: str | None = ...
The unique identifier of the agent memory.
response_metadata
class-attribute
instance-attribute
¶
Metadata about the response that produced this output. Use this to recover the request identifiers a service's support team needs in order to investigate a call. Members of the metadata are individually optional.