Bedrock Agent Runtime  >  Operations  >  invoke_agent

invoke_agent

Operation

invoke_agent async

invoke_agent(input: InvokeAgentInput, plugins: list[Plugin] | None = None) -> OutputEventStream[ResponseStream, InvokeAgentOutput]

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
input	InvokeAgentInput	An instance of InvokeAgentInput.	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[ResponseStream, InvokeAgentOutput]	An OutputEventStream for server-to-client streaming.

Input

InvokeAgentInput dataclass

Dataclass for InvokeAgentInput structure.

Attributes

agent_alias_id class-attribute instance-attribute

agent_alias_id: str | None = None

The alias of the agent to use.

agent_id class-attribute instance-attribute

agent_id: str | None = None

The unique identifier of the agent to use.

bedrock_model_configurations class-attribute instance-attribute

bedrock_model_configurations: BedrockModelConfigurations | None = None

Model performance settings for the request.

enable_trace class-attribute instance-attribute

enable_trace: bool | None = 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 = None

Specifies whether to end the session with the agent or not.

input_text class-attribute instance-attribute

input_text: str | None = field(repr=False, default=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 = None

The unique identifier of the agent memory.

prompt_creation_configurations class-attribute instance-attribute

prompt_creation_configurations: PromptCreationConfigurations | None = 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 = 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 = 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 = None

The ARN of the resource making the request.

streaming_configurations class-attribute instance-attribute

streaming_configurations: StreamingConfigurations | None = 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 OutputEventStream for server-to-client streaming.

Event Stream Structure

Output Event Type

ResponseStream

Initial Response Structure

InvokeAgentOutput dataclass

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 = None

The unique identifier of the agent memory.

session_id instance-attribute

session_id: str

The unique identifier of the session with the agent.