From SDK to CLI: Making Sense of Bedrock Namespaces and Avoiding Cloud Shell Pitfalls

In this era of AI-driven SDLC, Amazon Bedrock has rapidly become the go-to platform for AWS builders to experiment and deploy intelligent applications with LLM models at scale. As the ecosystem evolves, so do the tools, namespaces, CLIs, and SDKs that support it. In Principle, AWS traditionally groups service operations into a single namespace, hundreds of operations neatly packaged under it.

aws ec2 …
aws s3 …
aws iam …

But when you step into the world of Amazon Bedrock, the simplicity disappears. Developers working with AWS Bedrock Service today must navigate several moving parts to establish the tech stack.

aws bedrock
aws bedrock-runtime
aws bedrock-agent
aws bedrock-agent-runtime
and the newer aws bedrock-agentcore toolkit.

AWS VPC doesn’t even have its own namespace; it piggybacks on EC2

I am writing this blog with an aim to demystify these namespaces, draw parallel comparisons between other namespaces, and finally highlight a subtle but frustrating limitation: AWS Cloud Shell cannot currently use all the latest Bedrock CLI namespaces, even though they work perfectly fine on a local machine

AWS Namespaces:

AWS offers hundreds of services, each with multiple features, distinct API families, different operational lifecycles and sub-services or components within the same service domain. To access them via API calls, AWS provides Command Line Interface(CLI) utility and Software Development Kits(SDK’s). To avoid a monolithic structure of API calls, AWS organizes them into namespaces. They provide clear separation of responsibility, organized service level boundaries, handlers via IAM policies, allowing independent release cycles. Individual CLI calls are made of below format.

aws 'service' 'operation'

Older AWS services like EC2, S3, DynamoDB have flat, single namespaces. Those services were simpler when first launched. It was kept very straight forward with a dedicated namespace, dozens of operations wrapped around them.

For EC2:

aws ec2 describe-instances
aws ec2 create-route
aws ec2 modify-volume

import boto3
ec2 = boto3.client('ec2')
response = ec2.describe_instances()
print(response)

One namespace covers everything:
Compute, networking attributes, metadata, EBS associations, placement groups — everything.

Amazon Bedrock, by contrast, works differently because it contains distinct execution layers.

Bedrock Namespaces:

With the pace of AI platform developments, Namespace belonging to Bedrock are categorized to enable them to evolve independently:

bedrock (control plane) changes infrequently
bedrock-runtime updates faster due to new model releases
bedrock-agent-runtime changes frequently due to new agent features

Bedrock Namespaces → decoupled evolution + backward compatibility.

If everything was under one namespace, a small change would require a full service redeployment. Let’s have a look at every layer of Bedrock.

Layer 1 — bedrock:

aws bedrock

import boto3
client = boto3.client('bedrock')

This layer provides API operations for creating, managing, fine-turning, and evaluating Amazon Bedrock models.

It provides handlers for

• Model listing
• Model customization jobs
• Provisioned throughput
• Automated Reasoning
• Creating Guardrails

‘aws bedrock’ namespace focusses on LLM governance and acts as a control plane for Bedrock service

Layer 2 — bedrock-runtime:

aws bedrock-runtime

import boto3
client = boto3.client('bedrock-runtime')

This layer provides API operations for running inference using Amazon Bedrock models

It provides handlers to

• Invoke models (Claude, LLama, Amazon Nova, etc.)
• Generate embeddings
• Streaming or normal inference
• Manage invocation parameters
• Apply Guardrails

‘aws bedrock-runtime’ namespace focusses on model interactions with input prompts. Provides necessary components to generate Inference

Layer 3 — bedrock-agent

aws bedrock-agent

import boto3
client = boto3.client('bedrock-agent')

This layer provides API operations for creating and managing Amazon Bedrock agents.

It provides handlers for

• Creating agent
• Attaching knowledge bases
• Deploying agent alias

‘aws bedrock-agent’ namespace focusses on creation and preparation of Agents. this is one of the most frequently used feature

Layer 4— bedrock-agent-runtime

aws bedrock-agent-runtime

import boto3
client = boto3.client('bedrock-agent-runtime')

This layer provides API operations related to model invocation and querying of knowledge bases.

It provides handlers to

• Invoke the deployed agent alias
• Maintain user sessions
• Provide multi-turn conversational memory

‘aws bedrock-agent-runtime’ namespace focusses on leveraging the agents that was already deployed.

Layer 5— bedrock-agentcore

aws bedrock-agentcore

import boto3
client = boto3.client('bedrock-agentcore')

This layer provides API operations related to Local or remote execution of the new AgentCore engine.

It provides handlers to

• Invoke agent locally
• Manage agent runtime sessions
• Test tools locally

‘aws bedrock-agentcore’ namespace focusses on developer based agentic framework providing greater flexibility for custom API integrations

Key Takeaways on Bedrock Namespaces:

1. Calling an LLM ≠ running an agent with tools and memory.
2. Runtimes require separate scaling and identity paths. Foundation model inference runs on FM Runtime. Agent execution runs on Agent Runtime.
3. Permissions differ for each Bedrock actions. Bundling these under one namespace is logically impossible to establish least privilege access(bedrock:InvokeModel,bedrock:InvokeAgent,bedrock:Retrieve,bedrock:InvokeAgentRuntime)
4. If your agents are created using Bedrock console, use aws bedrock-agent-runtime invoke-agent ...
5. If your agents are deployed using latest Bedrock Agentcore features, consider aws bedrock-agentcore invoke-agent-runtime ... for invoking them.

AWS Cloud Shell limitations

When provisioning and experimenting with Bedrock Agents, developers working with SDK should be seamless. On the other hand, if we try to invoke CLI commands for executions from Terminal in a local machine, it works perfectly fine. Real pain point is on using AWS CloudShell for executing CLI calls.

It is because, Cloud Shell currently ships with a slightly older version of AWS CLI. In other words, velocity of update for SDK is at far higher speed.

aws bedrock-agent-runtime invoke-agent ...

Only to receive:

aws: [ERROR]: argument operation: Found invalid choice 'invoke-agent'

This happens because:

1. Your local machine may have a newer CLI that includes all Bedrock namespaces
2. CloudShell cannot be upgraded by the user to the most recent one
3. CloudShell CLI version lags behind new Bedrock service releases

Thus, CloudShell currently cannot invoke Bedrock Agents(at times) using native AWS CLI

Developers eventually discover that:

• Boto3 works (because Python packages can be installed)
• AWS CLI commands for new namespaces/features do not

This is a key nuance that surprises many, but helps to save peace of mind instead of striving to fix the CloudShell errors.

Note: Bedrock SDK’s also goes for a frequent updates. Kindly check for the API syntax before starting a new project.

Conclusion

With various namespaces that we discussed above and with pace of AI developments, Amazon Bedrock is maturing into a multi-layered AI platform. With that evolution comes a CLI ecosystem that reflects the separation of concerns across model inference, agent orchestration, and runtime execution.

For developers, understanding these namespaces — and the limitations of CloudShell — is critical for building and invoking Bedrock agents reliably.