invokeAgentRuntimeCommand method

Future<InvokeAgentRuntimeCommandResponse> invokeAgentRuntimeCommand({ required String agentRuntimeArn, required InvokeAgentRuntimeCommandRequestBody body, String? accept, String? accountId, String? baggage, String? contentType, String? qualifier, String? runtimeSessionId, String? traceId, String? traceParent, String? traceState, })

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.

May throw AccessDeniedException. May throw InternalServerException. May throw ResourceNotFoundException. May throw RuntimeClientError. May throw ServiceQuotaExceededException. May throw ThrottlingException. May throw ValidationException.

Parameter agentRuntimeArn : 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.

Parameter body : The request body containing the command to execute and optional configuration parameters such as timeout settings.

Parameter accept : 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.

Parameter accountId : 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.

Parameter baggage : Additional context information for distributed tracing.

Parameter contentType : 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.

Parameter qualifier : 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.

Parameter runtimeSessionId : 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.

Parameter traceId : The trace identifier for request tracking.

Parameter traceParent : The parent trace information for distributed tracing.

Parameter traceState : The trace state information for distributed tracing.

Implementation

Future<InvokeAgentRuntimeCommandResponse> invokeAgentRuntimeCommand({
  required String agentRuntimeArn,
  required InvokeAgentRuntimeCommandRequestBody body,
  String? accept,
  String? accountId,
  String? baggage,
  String? contentType,
  String? qualifier,
  String? runtimeSessionId,
  String? traceId,
  String? traceParent,
  String? traceState,
}) async {
  final headers = <String, String>{
    if (accept != null) 'Accept': accept.toString(),
    if (baggage != null) 'baggage': baggage.toString(),
    if (contentType != null) 'Content-Type': contentType.toString(),
    if (runtimeSessionId != null)
      'X-Amzn-Bedrock-AgentCore-Runtime-Session-Id':
          runtimeSessionId.toString(),
    if (traceId != null) 'X-Amzn-Trace-Id': traceId.toString(),
    if (traceParent != null) 'traceparent': traceParent.toString(),
    if (traceState != null) 'tracestate': traceState.toString(),
  };
  final $query = <String, List<String>>{
    if (accountId != null) 'accountId': [accountId],
    if (qualifier != null) 'qualifier': [qualifier],
  };
  final response = await _protocol.sendRaw(
    payload: body,
    method: 'POST',
    requestUri: '/runtimes/${Uri.encodeComponent(agentRuntimeArn)}/commands',
    queryParams: $query,
    headers: headers,
    exceptionFnMap: _exceptionFns,
  );
  final $json = await _s.jsonFromResponse(response);
  return InvokeAgentRuntimeCommandResponse(
    stream: InvokeAgentRuntimeCommandStreamOutput.fromJson($json),
    contentType:
        _s.extractHeaderStringValue(response.headers, 'Content-Type')!,
    baggage: _s.extractHeaderStringValue(response.headers, 'baggage'),
    runtimeSessionId: _s.extractHeaderStringValue(
        response.headers, 'X-Amzn-Bedrock-AgentCore-Runtime-Session-Id'),
    traceId: _s.extractHeaderStringValue(response.headers, 'X-Amzn-Trace-Id'),
    traceParent: _s.extractHeaderStringValue(response.headers, 'traceparent'),
    traceState: _s.extractHeaderStringValue(response.headers, 'tracestate'),
    statusCode: response.statusCode,
  );
}