converse_stream¶
Operation¶
async
¶
converse_stream(input: ConverseStreamInput, plugins: list[Plugin] | None = None) -> OutputEventStream[ConverseStreamOutput, ConverseStreamOperationOutput]
Sends messages to the specified Amazon Bedrock model and returns the
response in a stream. ConverseStream provides a consistent API that
works with all Amazon Bedrock models that support messages. This allows
you to write code once and use it with different models. Should a model
have unique inference parameters, you can also pass those unique
parameters to the model.
To find out if a model supports streaming, call
GetFoundationModel
and check the responseStreamingSupported field in the response.
Note
The CLI doesn't support streaming operations in Amazon Bedrock,
including ConverseStream.
Amazon Bedrock doesn't store any text, images, or documents that you provide as content. The data is only used to generate the response.
You can submit a prompt by including it in the messages field,
specifying the modelId of a foundation model or inference profile to
run inference on it, and including any other fields that are relevant to
your use case.
You can also submit a prompt from Prompt management by specifying the
ARN of the prompt version and including a map of variables to values in
the promptVariables field. You can append more messages to the prompt
by using the messages field. If you use a prompt from Prompt
management, you can't include the following fields in the request:
additionalModelRequestFields, inferenceConfig, system, or
toolConfig. Instead, these fields must be defined through Prompt
management. For more information, see Use a prompt from Prompt
management.
For information about the Converse API, see Use the Converse API in the Amazon Bedrock User Guide. To use a guardrail, see Use a guardrail with the Converse API in the Amazon Bedrock User Guide. To use a tool with a model, see Tool use (Function calling) in the Amazon Bedrock User Guide
For example code, see Conversation streaming example in the Amazon Bedrock User Guide.
This operation requires permission for the
bedrock:InvokeModelWithResponseStream action.
Warning
To deny all inference access to resources that you specify in the
modelId field, you need to deny access to the bedrock:InvokeModel and
bedrock:InvokeModelWithResponseStream actions. Doing this also denies
access to the resource through the base inference actions
(InvokeModel
and
InvokeModelWithResponseStream).
For more information see Deny access for inference on specific
models.
For troubleshooting some of the common errors you might encounter when
using the ConverseStream API, see Troubleshooting Amazon Bedrock API
Error
Codes
in the Amazon Bedrock User Guide
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
input
|
ConverseStreamInput
|
An instance of |
required |
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
|
Returns:
| Type | Description |
|---|---|
OutputEventStream[ConverseStreamOutput, ConverseStreamOperationOutput]
|
An |
Input¶
dataclass
¶
Dataclass for ConverseStreamInput structure.
Attributes¶
class-attribute
instance-attribute
¶
additional_model_request_fields: Document | None = None
Additional inference parameters that the model supports, beyond the base
set of inference parameters that Converse and ConverseStream support
in the inferenceConfig field. For more information, see Model
parameters.
class-attribute
instance-attribute
¶
additional_model_response_field_paths: list[str] | None = None
Additional model parameters field paths to return in the response.
Converse and ConverseStream return the requested fields as a JSON
Pointer object in the additionalModelResponseFields field. The
following is example JSON for additionalModelResponseFieldPaths.
[ "/stop_sequence" ]
For information about the JSON Pointer syntax, see the Internet Engineering Task Force (IETF) documentation.
Converse and ConverseStream reject an empty JSON Pointer or
incorrectly structured JSON Pointer with a 400 error code. if the JSON
Pointer is valid, but the requested field is not in the model response,
it is ignored by Converse.
class-attribute
instance-attribute
¶
guardrail_config: GuardrailStreamConfiguration | None = None
Configuration information for a guardrail that you want to use in the
request. If you include guardContent blocks in the content field in
the messages field, the guardrail operates only on those messages. If
you include no guardContent blocks, the guardrail operates on all
messages in the request body and in any included prompt resource.
class-attribute
instance-attribute
¶
inference_config: InferenceConfiguration | None = None
Inference parameters to pass to the model. Converse and
ConverseStream support a base set of inference parameters. If you need
to pass additional parameters that the model supports, use the
additionalModelRequestFields request field.
class-attribute
instance-attribute
¶
messages: list[Message] | None = None
The messages that you want to send to the model.
class-attribute
instance-attribute
¶
model_id: str | None = None
Specifies the model or throughput with which to run inference, or the prompt resource to use in inference. The value depends on the resource that you use:
-
If you use a base model, specify the model ID or its ARN. For a list of model IDs for base models, see Amazon Bedrock base model IDs (on-demand throughput) in the Amazon Bedrock User Guide.
-
If you use an inference profile, specify the inference profile ID or its ARN. For a list of inference profile IDs, see Supported Regions and models for cross-region inference in the Amazon Bedrock User Guide.
-
If you use a provisioned model, specify the ARN of the Provisioned Throughput. For more information, see Run inference using a Provisioned Throughput in the Amazon Bedrock User Guide.
-
If you use a custom model, first purchase Provisioned Throughput for it. Then specify the ARN of the resulting provisioned model. For more information, see Use a custom model in Amazon Bedrock in the Amazon Bedrock User Guide.
-
To include a prompt that was defined in Prompt management, specify the ARN of the prompt version to use.
The Converse API doesn't support imported models.
class-attribute
instance-attribute
¶
output_config: OutputConfig | None = None
Output configuration for a model response.
class-attribute
instance-attribute
¶
performance_config: PerformanceConfiguration | None = None
Model performance settings for the request.
class-attribute
instance-attribute
¶
prompt_variables: dict[str, PromptVariableValues] | None = field(repr=False, default=None)
Contains a map of variables in a prompt from Prompt management to
objects containing the values to fill in for them when running model
invocation. This field is ignored if you don't specify a prompt
resource in the modelId field.
class-attribute
instance-attribute
¶
request_metadata: dict[str, str] | None = field(repr=False, default=None)
Key-value pairs that you can use to filter invocation logs.
class-attribute
instance-attribute
¶
service_tier: ServiceTier | None = None
Specifies the processing tier configuration used for serving the request.
class-attribute
instance-attribute
¶
system: list[SystemContentBlock] | None = None
A prompt that provides instructions or context to the model about the task it should perform, or the persona it should adopt during the conversation.
class-attribute
instance-attribute
¶
tool_config: ToolConfiguration | None = None
Configuration information for the tools that the model can use when generating a response.
For information about models that support streaming tool use, see Supported models and model features.
Output¶
This operation returns an OutputEventStream for server-to-client streaming.
Event Stream Structure¶
Output Event Type¶
Initial Response Structure¶
dataclass
¶
Dataclass for ConverseStreamOperationOutput structure.