Skip to content

Commit 7849f17

Browse files
author
AWS
committed
Amazon Bedrock AgentCore Update: Provide support to perform deterministic operations on agent runtime through shell command executions via the new InvokeAgentRuntimeCommand API
1 parent 5381716 commit 7849f17

2 files changed

Lines changed: 293 additions & 7 deletions

File tree

‎.changes/next-release/feature-AmazonBedrockAgentCore-aaebd49.json‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
{
2+
"type": "feature",
3+
"category": "Amazon Bedrock AgentCore",
4+
"contributor": "",
5+
"description": "Provide support to perform deterministic operations on agent runtime through shell command executions via the new InvokeAgentRuntimeCommand API"
6+
}

‎services/bedrockagentcore/src/main/resources/codegen-resources/service-2.json‎

Lines changed: 287 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -389,7 +389,27 @@
389389
{"shape":"ResourceNotFoundException"},
390390
{"shape":"InternalServerException"}
391391
],
392-
"documentation":"<p>Sends a request to an agent or tool hosted in an Amazon Bedrock AgentCore Runtime and receives responses in real-time. </p> <p>To invoke an agent you must specify the AgentCore Runtime ARN and provide a payload containing your request. You can optionally specify a qualifier to target a specific version or endpoint of the agent.</p> <p>This operation supports streaming responses, allowing you to receive partial responses as they become available. We recommend using pagination to ensure that the operation returns quickly and successfully when processing large responses.</p> <p>For example code, see <a href=\"https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-invoke-agent.html\">Invoke an AgentCore Runtime agent</a>. </p> <p>If you're integrating your agent with OAuth, you can't use the Amazon Web Services SDK to call <code>InvokeAgentRuntime</code>. Instead, make a HTTPS request to <code>InvokeAgentRuntime</code>. For an example, see <a href=\"https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-oauth.html\">Authenticate and authorize with Inbound Auth and Outbound Auth</a>.</p> <p>To use this operation, you must have the <code>bedrock-agentcore:InvokeAgentRuntime</code> permission. If you are making a call to <code>InvokeAgentRuntime</code> on behalf of a user ID with the <code>X-Amzn-Bedrock-AgentCore-Runtime-User-Id</code> header, You require permissions to both actions (<code>bedrock-agentcore:InvokeAgentRuntime</code> and <code>bedrock-agentcore:InvokeAgentRuntimeForUser</code>). </p>"
392+
"documentation":"<p>Sends a request to an agent or tool hosted in an Amazon Bedrock AgentCore Runtime and receives responses in real-time. </p> <p>To invoke an agent, you can specify either the AgentCore Runtime ARN or the agent ID with an account ID, and provide a payload containing your request. When you use the agent ID instead of the full ARN, you don't need to URL-encode the identifier. You can optionally specify a qualifier to target a specific endpoint of the agent.</p> <p>This operation supports streaming responses, allowing you to receive partial responses as they become available. We recommend using pagination to ensure that the operation returns quickly and successfully when processing large responses.</p> <p>For example code, see <a href=\"https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-invoke-agent.html\">Invoke an AgentCore Runtime agent</a>. </p> <p>If you're integrating your agent with OAuth, you can't use the Amazon Web Services SDK to call <code>InvokeAgentRuntime</code>. Instead, make a HTTPS request to <code>InvokeAgentRuntime</code>. For an example, see <a href=\"https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-oauth.html\">Authenticate and authorize with Inbound Auth and Outbound Auth</a>.</p> <p>To use this operation, you must have the <code>bedrock-agentcore:InvokeAgentRuntime</code> permission. If you are making a call to <code>InvokeAgentRuntime</code> on behalf of a user ID with the <code>X-Amzn-Bedrock-AgentCore-Runtime-User-Id</code> header, You require permissions to both actions (<code>bedrock-agentcore:InvokeAgentRuntime</code> and <code>bedrock-agentcore:InvokeAgentRuntimeForUser</code>). </p>"
393+
},
394+
"InvokeAgentRuntimeCommand":{
395+
"name":"InvokeAgentRuntimeCommand",
396+
"http":{
397+
"method":"POST",
398+
"requestUri":"/runtimes/{agentRuntimeArn}/commands",
399+
"responseCode":200
400+
},
401+
"input":{"shape":"InvokeAgentRuntimeCommandRequest"},
402+
"output":{"shape":"InvokeAgentRuntimeCommandResponse"},
403+
"errors":[
404+
{"shape":"ServiceQuotaExceededException"},
405+
{"shape":"ValidationException"},
406+
{"shape":"AccessDeniedException"},
407+
{"shape":"RuntimeClientError"},
408+
{"shape":"ThrottlingException"},
409+
{"shape":"ResourceNotFoundException"},
410+
{"shape":"InternalServerException"}
411+
],
412+
"documentation":"<p>Executes a command in a runtime session container. Returns streaming output with contentStart, contentDelta, and contentStop events.</p>"
393413
},
394414
"InvokeCodeInterpreter":{
395415
"name":"InvokeCodeInterpreter",
@@ -1210,6 +1230,13 @@
12101230
"documentation":"<p>Contains output from a code interpreter stream.</p>",
12111231
"eventstream":true
12121232
},
1233+
"CommandExecutionStatus":{
1234+
"type":"string",
1235+
"enum":[
1236+
"COMPLETED",
1237+
"TIMED_OUT"
1238+
]
1239+
},
12131240
"CompleteResourceTokenAuthRequest":{
12141241
"type":"structure",
12151242
"required":[
@@ -1310,6 +1337,43 @@
13101337
"resource_link"
13111338
]
13121339
},
1340+
"ContentDeltaEvent":{
1341+
"type":"structure",
1342+
"members":{
1343+
"stdout":{
1344+
"shape":"String",
1345+
"documentation":"<p>Standard output content</p>"
1346+
},
1347+
"stderr":{
1348+
"shape":"String",
1349+
"documentation":"<p>Standard error content</p>"
1350+
}
1351+
},
1352+
"documentation":"<p>Content event containing stdout or stderr output</p>"
1353+
},
1354+
"ContentStartEvent":{
1355+
"type":"structure",
1356+
"members":{},
1357+
"documentation":"<p>First event indicating command execution has started</p>"
1358+
},
1359+
"ContentStopEvent":{
1360+
"type":"structure",
1361+
"required":[
1362+
"exitCode",
1363+
"status"
1364+
],
1365+
"members":{
1366+
"exitCode":{
1367+
"shape":"Integer",
1368+
"documentation":"<p>Exit code: 0 = success, -1 = platform error, &gt;0 = command error</p>"
1369+
},
1370+
"status":{
1371+
"shape":"CommandExecutionStatus",
1372+
"documentation":"<p>Execution status</p>"
1373+
}
1374+
},
1375+
"documentation":"<p>Final event indicating command execution has completed</p>"
1376+
},
13131377
"ContentTextString":{
13141378
"type":"string",
13151379
"max":100000,
@@ -2386,6 +2450,203 @@
23862450
},
23872451
"exception":true
23882452
},
2453+
"InvokeAgentRuntimeCommandRequest":{
2454+
"type":"structure",
2455+
"required":[
2456+
"agentRuntimeArn",
2457+
"body"
2458+
],
2459+
"members":{
2460+
"contentType":{
2461+
"shape":"MimeType",
2462+
"documentation":"<p>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.</p>",
2463+
"location":"header",
2464+
"locationName":"Content-Type"
2465+
},
2466+
"accept":{
2467+
"shape":"MimeType",
2468+
"documentation":"<p>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.</p>",
2469+
"location":"header",
2470+
"locationName":"Accept"
2471+
},
2472+
"runtimeSessionId":{
2473+
"shape":"SessionType",
2474+
"documentation":"<p>Runtime session identifier</p>",
2475+
"idempotencyToken":true,
2476+
"location":"header",
2477+
"locationName":"X-Amzn-Bedrock-AgentCore-Runtime-Session-Id"
2478+
},
2479+
"traceId":{
2480+
"shape":"InvokeAgentRuntimeCommandRequestTraceIdString",
2481+
"documentation":"<p>The trace identifier for request tracking.</p>",
2482+
"location":"header",
2483+
"locationName":"X-Amzn-Trace-Id"
2484+
},
2485+
"traceParent":{
2486+
"shape":"InvokeAgentRuntimeCommandRequestTraceParentString",
2487+
"documentation":"<p>The parent trace information for distributed tracing.</p>",
2488+
"location":"header",
2489+
"locationName":"traceparent"
2490+
},
2491+
"traceState":{
2492+
"shape":"InvokeAgentRuntimeCommandRequestTraceStateString",
2493+
"documentation":"<p>The trace state information for distributed tracing.</p>",
2494+
"location":"header",
2495+
"locationName":"tracestate"
2496+
},
2497+
"baggage":{
2498+
"shape":"InvokeAgentRuntimeCommandRequestBaggageString",
2499+
"documentation":"<p>Additional context information for distributed tracing.</p>",
2500+
"location":"header",
2501+
"locationName":"baggage"
2502+
},
2503+
"agentRuntimeArn":{
2504+
"shape":"String",
2505+
"documentation":"<p>ARN of the agent runtime</p>",
2506+
"location":"uri",
2507+
"locationName":"agentRuntimeArn"
2508+
},
2509+
"qualifier":{
2510+
"shape":"String",
2511+
"documentation":"<p>Version or alias qualifier</p>",
2512+
"location":"querystring",
2513+
"locationName":"qualifier"
2514+
},
2515+
"accountId":{
2516+
"shape":"InvokeAgentRuntimeCommandRequestAccountIdString",
2517+
"documentation":"<p>Account ID (12 digits)</p>",
2518+
"location":"querystring",
2519+
"locationName":"accountId"
2520+
},
2521+
"body":{
2522+
"shape":"InvokeAgentRuntimeCommandRequestBody",
2523+
"documentation":"<p>Request body containing command and timeout</p>"
2524+
}
2525+
},
2526+
"documentation":"<p>Request for InvokeAgentRuntimeCommand operation</p>",
2527+
"payload":"body"
2528+
},
2529+
"InvokeAgentRuntimeCommandRequestAccountIdString":{
2530+
"type":"string",
2531+
"pattern":"[0-9]{12}"
2532+
},
2533+
"InvokeAgentRuntimeCommandRequestBaggageString":{
2534+
"type":"string",
2535+
"max":8192,
2536+
"min":0
2537+
},
2538+
"InvokeAgentRuntimeCommandRequestBody":{
2539+
"type":"structure",
2540+
"required":["command"],
2541+
"members":{
2542+
"command":{
2543+
"shape":"InvokeAgentRuntimeCommandRequestBodyCommandString",
2544+
"documentation":"<p>The command to execute in the runtime container</p>"
2545+
},
2546+
"timeout":{
2547+
"shape":"Integer",
2548+
"documentation":"<p>Command timeout in seconds (default: 300, min:1, max: 3600)</p>"
2549+
}
2550+
},
2551+
"documentation":"<p>Request body for InvokeAgentRuntimeCommand</p>"
2552+
},
2553+
"InvokeAgentRuntimeCommandRequestBodyCommandString":{
2554+
"type":"string",
2555+
"max":65536,
2556+
"min":1
2557+
},
2558+
"InvokeAgentRuntimeCommandRequestTraceIdString":{
2559+
"type":"string",
2560+
"max":1024,
2561+
"min":0
2562+
},
2563+
"InvokeAgentRuntimeCommandRequestTraceParentString":{
2564+
"type":"string",
2565+
"max":1024,
2566+
"min":0
2567+
},
2568+
"InvokeAgentRuntimeCommandRequestTraceStateString":{
2569+
"type":"string",
2570+
"max":512,
2571+
"min":0
2572+
},
2573+
"InvokeAgentRuntimeCommandResponse":{
2574+
"type":"structure",
2575+
"required":[
2576+
"contentType",
2577+
"stream"
2578+
],
2579+
"members":{
2580+
"runtimeSessionId":{
2581+
"shape":"SessionId",
2582+
"documentation":"<p>Runtime session identifier</p>",
2583+
"location":"header",
2584+
"locationName":"X-Amzn-Bedrock-AgentCore-Runtime-Session-Id"
2585+
},
2586+
"traceId":{
2587+
"shape":"String",
2588+
"documentation":"<p>The trace identifier for request tracking.</p>",
2589+
"location":"header",
2590+
"locationName":"X-Amzn-Trace-Id"
2591+
},
2592+
"traceParent":{
2593+
"shape":"String",
2594+
"documentation":"<p>The parent trace information for distributed tracing.</p>",
2595+
"location":"header",
2596+
"locationName":"traceparent"
2597+
},
2598+
"traceState":{
2599+
"shape":"String",
2600+
"documentation":"<p>The trace state information for distributed tracing.</p>",
2601+
"location":"header",
2602+
"locationName":"tracestate"
2603+
},
2604+
"baggage":{
2605+
"shape":"String",
2606+
"documentation":"<p>Additional context information for distributed tracing.</p>",
2607+
"location":"header",
2608+
"locationName":"baggage"
2609+
},
2610+
"contentType":{
2611+
"shape":"String",
2612+
"documentation":"<p>The MIME type of the response data. This indicates how to interpret the response data. Common values include application/json for JSON data.</p>",
2613+
"location":"header",
2614+
"locationName":"Content-Type"
2615+
},
2616+
"statusCode":{
2617+
"shape":"HttpResponseCode",
2618+
"documentation":"<p>The HTTP status code of the response. A status code of 200 indicates a successful operation. Other status codes indicate various error conditions.</p>",
2619+
"location":"statusCode"
2620+
},
2621+
"stream":{
2622+
"shape":"InvokeAgentRuntimeCommandStreamOutput",
2623+
"documentation":"<p>Streaming output containing command execution events</p>"
2624+
}
2625+
},
2626+
"documentation":"<p>Response for InvokeAgentRuntimeCommand operation</p>",
2627+
"payload":"stream"
2628+
},
2629+
"InvokeAgentRuntimeCommandStreamOutput":{
2630+
"type":"structure",
2631+
"members":{
2632+
"chunk":{
2633+
"shape":"ResponseChunk",
2634+
"documentation":"<p>Response chunk containing command execution events</p>"
2635+
},
2636+
"accessDeniedException":{
2637+
"shape":"AccessDeniedException",
2638+
"documentation":"<p>Exception events for error streaming</p>"
2639+
},
2640+
"internalServerException":{"shape":"InternalServerException"},
2641+
"resourceNotFoundException":{"shape":"ResourceNotFoundException"},
2642+
"serviceQuotaExceededException":{"shape":"ServiceQuotaExceededException"},
2643+
"throttlingException":{"shape":"ThrottlingException"},
2644+
"validationException":{"shape":"ValidationException"},
2645+
"runtimeClientError":{"shape":"RuntimeClientError"}
2646+
},
2647+
"documentation":"<p>Streaming output for InvokeAgentRuntimeCommand operation Delivers typed events: contentStart (first), contentDelta (middle), contentStop (last)</p>",
2648+
"eventstream":true
2649+
},
23892650
"InvokeAgentRuntimeRequest":{
23902651
"type":"structure",
23912652
"required":[
@@ -2456,19 +2717,19 @@
24562717
},
24572718
"agentRuntimeArn":{
24582719
"shape":"String",
2459-
"documentation":"<p>The Amazon Web Services Resource Name (ARN) of the agent runtime to invoke. The ARN uniquely identifies the agent runtime resource in Amazon Bedrock AgentCore.</p>",
2720+
"documentation":"<p>The identifier of the agent runtime to invoke. You can specify either the full Amazon Web Services Resource Name (ARN) or the agent ID. If you use the agent ID, you must also provide the <code>accountId</code> query parameter.</p>",
24602721
"location":"uri",
24612722
"locationName":"agentRuntimeArn"
24622723
},
24632724
"qualifier":{
24642725
"shape":"String",
2465-
"documentation":"<p>The qualifier to use for the agent runtime. This can be a version number or an endpoint name that points to a specific version. If not specified, Amazon Bedrock AgentCore uses the default version of the agent runtime.</p>",
2726+
"documentation":"<p>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.</p>",
24662727
"location":"querystring",
24672728
"locationName":"qualifier"
24682729
},
24692730
"accountId":{
24702731
"shape":"InvokeAgentRuntimeRequestAccountIdString",
2471-
"documentation":"<p>The identifier of the Amazon Web Services account for the agent runtime resource.</p>",
2732+
"documentation":"<p>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 <code>agentRuntimeArn</code>.</p>",
24722733
"location":"querystring",
24732734
"locationName":"accountId"
24742735
},
@@ -3498,6 +3759,25 @@
34983759
"min":1,
34993760
"pattern":"\\w+:(\\/?\\/?)[^\\s]+"
35003761
},
3762+
"ResponseChunk":{
3763+
"type":"structure",
3764+
"members":{
3765+
"contentStart":{
3766+
"shape":"ContentStartEvent",
3767+
"documentation":"<p>First chunk - indicates command execution has started</p>"
3768+
},
3769+
"contentDelta":{
3770+
"shape":"ContentDeltaEvent",
3771+
"documentation":"<p>Middle chunks - stdout/stderr output</p>"
3772+
},
3773+
"contentStop":{
3774+
"shape":"ContentStopEvent",
3775+
"documentation":"<p>Last chunk - indicates command execution has completed</p>"
3776+
}
3777+
},
3778+
"documentation":"<p>Response chunk containing exactly one of: contentStart, contentDelta, or contentStop</p>",
3779+
"event":true
3780+
},
35013781
"ResponseStream":{
35023782
"type":"blob",
35033783
"sensitive":true,
@@ -3897,7 +4177,7 @@
38974177
},
38984178
"sessionTimeoutSeconds":{
38994179
"shape":"BrowserSessionTimeout",
3900-
"documentation":"<p>The time in seconds after which the session automatically terminates if there is no activity. The default value is 3600 seconds (1 hour). The minimum allowed value is 60 seconds, and the maximum allowed value is 28800 seconds (8 hours).</p>"
4180+
"documentation":"<p>The duration in seconds (time-to-live) after which the session automatically terminates, regardless of ongoing activity. Defaults to 3600 seconds (1 hour). Recommended minimum: 60 seconds. Maximum allowed: 28,800 seconds (8 hours).</p>"
39014181
},
39024182
"viewPort":{
39034183
"shape":"ViewPort",
@@ -3986,7 +4266,7 @@
39864266
},
39874267
"sessionTimeoutSeconds":{
39884268
"shape":"CodeInterpreterSessionTimeout",
3989-
"documentation":"<p>The time in seconds after which the session automatically terminates if there is no activity. The default value is 900 seconds (15 minutes). The minimum allowed value is 60 seconds, and the maximum allowed value is 28800 seconds (8 hours).</p>"
4269+
"documentation":"<p>The duration in seconds (time-to-live) after which the session automatically terminates, regardless of ongoing activity. Defaults to 900 seconds (15 minutes). Recommended minimum: 60 seconds. Maximum allowed: 28,800 seconds (8 hours).</p>"
39904270
},
39914271
"clientToken":{
39924272
"shape":"ClientToken",
@@ -4504,7 +4784,7 @@
45044784
"members":{
45054785
"userToken":{
45064786
"shape":"UserTokenType",
4507-
"documentation":"<p>The OAuth2.0 token issued by the user’s identity provider</p>"
4787+
"documentation":"<p>The OAuth2.0 token issued by the user’s identity provider that was used to generate the workload access token</p>"
45084788
},
45094789
"userId":{
45104790
"shape":"UserIdType",

0 commit comments

Comments
 (0)