Skip to content

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 sessionId value in the request.

  • To activate trace enablement, turn enableTrace to true. 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 endSession to true.

  • In the sessionState object, 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 attribution object contains citations for parts of the response.

  • If you set enableTrace to true in 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 returnControl field.

  • 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 AsyncOutputEventStream for server-to-client streaming.

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

agent_alias_id instance-attribute
agent_alias_id: Required[str]

The alias of the agent to use.

agent_id instance-attribute
agent_id: Required[str]

The unique identifier of the agent to use.

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.

memory_id instance-attribute
memory_id: str | None

The unique identifier of the agent memory.

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
session_id: Required[str]

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.

source_arn instance-attribute
source_arn: str | None

The ARN of the resource making the request.

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

ResponseStream

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
response_metadata: ResponseMetadata = ...

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.

session_id instance-attribute
session_id: str

The unique identifier of the session with the agent.