BedrockAgentCore / Client / invoke_agent_runtime_command

invoke_agent_runtime_command¶

BedrockAgentCore.Client.invoke_agent_runtime_command(**kwargs)¶

Executes a command in a runtime session container and streams the output back to the caller. This operation allows you to run shell commands within the agent runtime environment and receive real-time streaming responses including standard output and standard error.

To invoke a command, you must specify the agent runtime ARN and a runtime session ID. The command execution supports streaming responses, allowing you to receive output as it becomes available through contentStart, contentDelta, and contentStop events.

To use this operation, you must have the bedrock-agentcore:InvokeAgentRuntimeCommand permission.

Request Syntax

response = client.invoke_agent_runtime_command(
    contentType='string',
    accept='string',
    runtimeSessionId='string',
    traceId='string',
    traceParent='string',
    traceState='string',
    baggage='string',
    agentRuntimeArn='string',
    qualifier='string',
    accountId='string',
    body={
        'command': 'string',
        'timeout': 123
    }
)

Parameters:

contentType (string) – The MIME type of the input data in the request payload. This tells the agent runtime how to interpret the payload data. Common values include application/json for JSON data.
accept (string) – The desired MIME type for the response from the agent runtime command. This tells the agent runtime what format to use for the response data. Common values include application/json for JSON data.
runtimeSessionId (string) –
The unique identifier of the runtime session in which to execute the command. This session ID is used to maintain state and context across multiple command invocations.

This field is autopopulated if not provided.
traceId (string) – The trace identifier for request tracking.
traceParent (string) – The parent trace information for distributed tracing.
traceState (string) – The trace state information for distributed tracing.
baggage (string) – Additional context information for distributed tracing.
agentRuntimeArn (string) –
[REQUIRED]

The Amazon Resource Name (ARN) of the agent runtime on which to execute the command. This identifies the specific agent runtime environment where the command will run.
qualifier (string) – The qualifier to use for the agent runtime. This is an endpoint name that points to a specific version. If not specified, Amazon Bedrock AgentCore uses the default endpoint of the agent runtime.
accountId (string) – The identifier of the Amazon Web Services account for the agent runtime resource. This parameter is required when you specify an agent ID instead of the full ARN for agentRuntimeArn.
body (dict) –
[REQUIRED]

The request body containing the command to execute and optional configuration parameters such as timeout settings.
- command (string) – [REQUIRED]
  
  The shell command to execute on the agent runtime. This command is executed in the runtime environment and its output is streamed back to the caller.
- timeout (integer) –
  
  The maximum duration in seconds to wait for the command to complete. If the command execution exceeds this timeout, it will be terminated. Default is 300 seconds. Minimum is 1 second. Maximum is 3600 seconds.

Return type:

dict

Returns:

The response of this operation contains an EventStream member. When iterated the EventStream will yield events based on the structure below, where only one of the top level keys will be present for any given event.

Response Syntax

{
    'runtimeSessionId': 'string',
    'traceId': 'string',
    'traceParent': 'string',
    'traceState': 'string',
    'baggage': 'string',
    'contentType': 'string',
    'statusCode': 123,
    'stream': EventStream({
        'chunk': {
            'contentStart': {},
            'contentDelta': {
                'stdout': 'string',
                'stderr': 'string'
            },
            'contentStop': {
                'exitCode': 123,
                'status': 'COMPLETED'|'TIMED_OUT'
            }
        },
        'accessDeniedException': {
            'message': 'string'
        },
        'internalServerException': {
            'message': 'string'
        },
        'resourceNotFoundException': {
            'message': 'string'
        },
        'serviceQuotaExceededException': {
            'message': 'string'
        },
        'throttlingException': {
            'message': 'string'
        },
        'validationException': {
            'message': 'string',
            'reason': 'CannotParse'|'FieldValidationFailed'|'IdempotentParameterMismatchException'|'EventInOtherSession'|'ResourceConflict',
            'fieldList': [
                {
                    'name': 'string',
                    'message': 'string'
                },
            ]
        },
        'runtimeClientError': {
            'message': 'string'
        }
    })
}

Response Structure

(dict) –

Response for InvokeAgentRuntimeCommand operation.
- runtimeSessionId (string) –
  
  The unique identifier of the runtime session in which the command was executed.
- traceId (string) –
  
  The trace identifier for request tracking.
- traceParent (string) –
  
  The parent trace information for distributed tracing.
- traceState (string) –
  
  The trace state information for distributed tracing.
- baggage (string) –
  
  Additional context information for distributed tracing.
- contentType (string) –
  
  The MIME type of the response data. This indicates how to interpret the response data. Common values include application/json for JSON data.
- statusCode (integer) –
  
  The HTTP status code of the response. A status code of 200 indicates a successful operation. Other status codes indicate various error conditions.
- stream (EventStream) –
  
  The streaming output from the command execution. This stream contains events that provide real-time updates including standard output, standard error, and completion status.
  - chunk (dict) –
    
    A response chunk containing command execution events such as content start, content delta, or content stop events.
    - contentStart (dict) –
      
      An event indicating the start of content streaming from the command execution. This is the first chunk received.
    - contentDelta (dict) –
      
      An event containing incremental output (stdout or stderr) from the command execution. These are the middle chunks.
      - stdout (string) –
        
        The standard output content from the command execution. This field contains the incremental output written to stdout by the executing command.
      - stderr (string) –
        
        The standard error content from the command execution. This field contains the incremental output written to stderr by the executing command.
    - contentStop (dict) –
      
      An event indicating the completion of the command execution, including the exit code and final status. This is the last chunk received.
      - exitCode (integer) –
        
        The exit code returned by the executed command. An exit code of 0 indicates successful execution, -1 indicates a platform error, and values greater than 0 indicate command-specific errors.
      - status (string) –
        
        The final status of the command execution. Valid values are COMPLETED for successful completion or TIMED_OUT if the command exceeded the specified timeout.
  - accessDeniedException (dict) –
    
    Exception events for error streaming.
    - message (string) –
  - internalServerException (dict) –
    
    The exception that occurs when the service encounters an unexpected internal error. This is a temporary condition that will resolve itself with retries. We recommend implementing exponential backoff retry logic in your application.
    - message (string) –
  - resourceNotFoundException (dict) –
    
    The exception that occurs when the specified resource does not exist. This can happen when using an invalid identifier or when trying to access a resource that has been deleted.
    - message (string) –
  - serviceQuotaExceededException (dict) –
    
    The exception that occurs when the request would cause a service quota to be exceeded. Review your service quotas and either reduce your request rate or request a quota increase.
    - message (string) –
  - throttlingException (dict) –
    
    The exception that occurs when the request was denied due to request throttling. This happens when you exceed the allowed request rate for an operation. Reduce the frequency of requests or implement exponential backoff retry logic in your application.
    - message (string) –
  - validationException (dict) –
    
    The exception that occurs when the input fails to satisfy the constraints specified by the service. Check the error message for details about which input parameter is invalid and correct your request.
    - message (string) –
    - reason (string) –
    - fieldList (list) –
      - (dict) –
        
        Stores information about a field passed inside a request that resulted in an exception.
        
        name (string) –
        
        The name of the field.
        
        message (string) –
        
        A message describing why this field failed validation.
  - runtimeClientError (dict) –
    
    The exception that occurs when there is an error in the runtime client. This can happen due to network issues, invalid configuration, or other client-side problems. Check the error message for specific details about the error.
    - message (string) –

Exceptions

BedrockAgentCore.Client.exceptions.ServiceQuotaExceededException
BedrockAgentCore.Client.exceptions.ValidationException
BedrockAgentCore.Client.exceptions.AccessDeniedException
BedrockAgentCore.Client.exceptions.RuntimeClientError
BedrockAgentCore.Client.exceptions.ThrottlingException
BedrockAgentCore.Client.exceptions.ResourceNotFoundException
BedrockAgentCore.Client.exceptions.InternalServerException