Calling Bedrock from C#
Call a Bedrock model from .NET 10 with the Converse API, stream the answer, handle throttling and guardrail outcomes, and grant a role only the model permissions it needs.
Assumes: .NET 10 LTS · AWS SDK for .NET v4 (AWSSDK.BedrockRuntime 4.1.0.2, AWSSDK.Extensions.Bedrock.MEAI 4.0.101.8) · Microsoft.Extensions.AI.Abstractions 10.11.0 · AWS CLI v2 · Region us-east-1. Verified against official sources on 2026-11-18.
Learning objectives
By the end of this lesson you can:
- Send a Converse request from C# with a system prompt, an inference configuration and a model or inference-profile ID, using role or SSO credentials and no keys in code.
- Read the response correctly: text blocks, stop reason, token usage and latency, and treat a guardrail intervention or a token cap as a distinct outcome.
- Stream an answer with
ConverseStream. - Configure retries and timeouts, and map Bedrock exceptions to friendly application errors.
- Write an IAM policy that allows one model through one inference profile and nothing else.
- Put your Bedrock call behind an interface so tests need no AWS account and the provider can be swapped.
Prerequisites
- Amazon Bedrock basics: endpoints, model IDs, inference profiles and model access.
- AWS SDK for .NET v4 in depth and AWS clients and dependency injection.
- Tools: .NET 10 SDK, AWS CLI v2 and the
learn-sandboxSSO profile (for the optional real call). The unit tests need no account.
Why this matters in banking
A new developer calls a model in a loop, catches every exception with catch (Exception), prints the raw model text into a web page, and logs the full prompt "for debugging". Within a week: throttling errors flood the support channel, a blocked answer is shown to a colleague as if it were real, and customer names sit in application logs. This lesson is the difference between a demo and a service you would let a risk team look at: bounded cost, explicit outcomes, least privilege, and no personal data in logs.
The idea in plain language
The Converse API is Bedrock's chat-style request. You send a list of messages (who said what), optional system instructions and a few settings. You get back one assistant message plus facts about how it ended. The same request shape works across providers, so changing a model changes one string.
Analogy: Converse is a standard envelope. The address on the front (model ID) changes, but the way you fold the letter (messages, system prompt, settings) stays the same. The reply envelope always carries a delivery slip (stop reason, token counts, latency) that you must read before trusting the letter.
Two facts shape every design:
- The API is stateless. The model remembers nothing between calls. To continue a conversation you resend the earlier messages. That is why long chats cost more each turn.
- The answer is not the whole story. The stop reason tells you whether the model finished (
end_turn), ran out of room (max_tokens), stopped on a stop sequence, wanted to call a tool (tool_use) or was cut off by a guardrail (guardrail_intervened). Code that ignores it will show a truncated or blocked reply as a normal answer.
What problem the AWS service solves
Calling a model by hand with raw HTTP means signing requests (SigV4), building provider-specific JSON and parsing provider-specific replies. The AWS SDK for .NET v4 signs for you, uses your credential chain, retries safely and gives typed classes for the Converse request and response. Converse removes the per-provider JSON.
Honest limits:
- Not every feature is in Converse. Embeddings need
InvokeModelwith a model-specific body (see Knowledge Bases and RAG). Some model-specific options travel in a catch-all field, so test each model. - Token counting before the call is not available for every model. For the Claude 5.5 models, the model cards list
Count tokensas not supported onbedrock-runtime. Estimate, then measure from theusageblock. - Newer models can return more than text. The Claude 5.5 cards describe adaptive thinking that is on by default for Sonnet 5.5 and cannot be switched off (
thinking.type: "disabled"is not supported). Converse can return reasoning blocks alongside text, so read text blocks only.
Microsoft / Azure comparison
| You know (Microsoft/Azure) | AWS equivalent | What's different |
|---|---|---|
ChatClient.CompleteChatAsync (Azure.AI.OpenAI) | ConverseAsync | Model is a per-call string, not a deployment you created |
ChatCompletionOptions { MaxOutputTokenCount, Temperature } | InferenceConfiguration { MaxTokens, Temperature } | Same ideas, different names |
Azure.Identity DefaultAzureCredential | SDK credential chain (SSO profile locally, IAM role in AWS) | No API keys in code or config |
Microsoft.Extensions.AI IChatClient | Same interface via AWSSDK.Extensions.Bedrock.MEAI | Swap Bedrock for a local model without touching business code |
ResponseFormat / content filter results | StopReason and the guardrail trace | You check guardrail_intervened yourself |
| Polly retry policies | SDK retry mode (Standard) | The SDK already retries throttles with backoff; do not stack another loop blindly |
Architecture
Security-boundary view: the redactor and the classification step are your code and therefore your controls. The guardrail runs inside Bedrock on your behalf. The audit log records token counts and redaction kinds, not prompt text.
Step-by-step implementation
Add the packages
dotnet add package AWSSDK.BedrockRuntime --version 4.1.0.2
# Optional: the IChatClient adapter so you can swap providers
dotnet add package AWSSDK.Extensions.Bedrock.MEAI --version 4.0.101.8
dotnet add package Microsoft.Extensions.AI.Abstractions --version 10.11.0Sign in and choose a model
aws sso login --profile learn-sandbox
export AWS_PROFILE=learn-sandbox
export BEDROCK_MODEL_ID=us.anthropic.claude-haiku-5-5 # ⚠ VERIFY on the model cardMake one Converse call
Use the complete example below. Run it and read the printed stop reason and token counts.
Add streaming, then error handling
Streaming improves perceived speed for chat. Error handling turns SDK exceptions into messages a colleague can act on.
Wrap it behind an interface
The lab's IPolicyAssistant hides Bedrock so tests run offline. Move the code into that shape before it spreads through your application.
AWS Console instructions
You can try the same request without code: Console → Amazon Bedrock → Playgrounds → Chat, pick the model and send a question. Use View API request (or the equivalent button in the playground) to see the JSON that matches your C# request ⚠ VERIFY the button name, the console changes often.
For IAM: Console → IAM → Policies → Create policy → JSON, paste the least-privilege policy below, then attach it to the application role, not to your own user.
AWS CLI
# The CLI equivalent of the C# call: useful for proving permissions before writing code.
aws bedrock-runtime converse \
--model-id us.anthropic.claude-haiku-5-5 \
--system '[{"text":"You are a concise assistant for Harbourline Bank staff."}]' \
--messages '[{"role":"user","content":[{"text":"In one sentence, what is an IBAN?"}]}]' \
--inference-config '{"maxTokens":200,"temperature":0.2}' \
--profile learn-sandbox --region us-east-1 \
--query "{text:output.message.content[0].text,stop:stopReason,usage:usage}"Infrastructure as Code
Grant an application role permission to call exactly one model through exactly one inference profile, and to apply one guardrail. A geo inference profile also needs permission on the foundation-model ARN in each destination Region it can route to.
using Amazon.CDK.AWS.IAM;
namespace Harbourline.GenAi.Infra;
public static class BedrockInvokePolicy
{
// Destination Regions of the US geo profile, as listed on the model card for us-east-1 (2026-11-18).
private static readonly string[] DestinationRegions = ["us-east-1", "us-east-2", "us-west-2"];
public static PolicyStatement[] For(string accountId, string guardrailId)
{
var invoke = new PolicyStatement(new PolicyStatementProps
{
Sid = "InvokeOneModelThroughOneProfile",
Effect = Effect.ALLOW,
Actions = ["bedrock:InvokeModel", "bedrock:InvokeModelWithResponseStream"],
Resources = new[]
{
$"arn:aws:bedrock:us-east-1:{accountId}:inference-profile/us.anthropic.claude-haiku-5-5",
}
.Concat(DestinationRegions.Select(r => $"arn:aws:bedrock:{r}::foundation-model/anthropic.claude-haiku-5-5"))
.ToArray(),
});
var guardrail = new PolicyStatement(new PolicyStatementProps
{
Sid = "ApplyOnlyOurGuardrail",
Effect = Effect.ALLOW,
Actions = ["bedrock:ApplyGuardrail"],
Resources = [$"arn:aws:bedrock:us-east-1:{accountId}:guardrail/{guardrailId}"],
});
return [invoke, guardrail];
}
}The same policy as plain JSON lives in infra/iam-policy.json in the lab. Exact IAM requirements for Converse with an inference profile and a guardrail evolve, so confirm them in the Bedrock IAM documentation and with IAM Access Analyzer before production (⚠ VERIFY). A useful extra guard is the bedrock:InferenceProfileArn condition key to force callers to use the profile ⚠ VERIFY.
Complete code
One call, read correctly
using Amazon;
using Amazon.BedrockRuntime;
using Amazon.BedrockRuntime.Model;
using Amazon.Runtime;
var modelId = Environment.GetEnvironmentVariable("BEDROCK_MODEL_ID") ?? "us.anthropic.claude-haiku-5-5";
// Explicit Region and retry behaviour. Credentials come from the default chain (AWS_PROFILE=learn-sandbox).
var config = new AmazonBedrockRuntimeConfig
{
RegionEndpoint = RegionEndpoint.USEast1,
RetryMode = RequestRetryMode.Standard,
MaxErrorRetry = 3,
Timeout = TimeSpan.FromSeconds(60),
};
using var client = new AmazonBedrockRuntimeClient(config);
var request = new ConverseRequest
{
ModelId = modelId,
System = [new SystemContentBlock { Text = "You are a concise assistant for Harbourline Bank staff. Use only fictional data." }],
Messages =
[
new Message
{
Role = ConversationRole.User,
Content = [new ContentBlock { Text = "In one sentence, what is an IBAN?" }],
},
],
InferenceConfig = new InferenceConfiguration { MaxTokens = 200, Temperature = 0.2f },
};
try
{
var response = await client.ConverseAsync(request);
// Keep only text blocks: newer models can also return reasoning blocks that are not meant for users.
var text = string.Concat(response.Output.Message.Content.Where(b => b.Text is not null).Select(b => b.Text));
Console.WriteLine(text);
Console.WriteLine($"stop={response.StopReason.Value} in={response.Usage.InputTokens} out={response.Usage.OutputTokens} ms={response.Metrics.LatencyMs}");
}
catch (ThrottlingException)
{
Console.Error.WriteLine("Throttled after the SDK's retries. Back off or request a higher quota.");
}
catch (AccessDeniedException ex)
{
Console.Error.WriteLine($"Access denied: check IAM, the model ID and Marketplace access. {ex.Message}");
}
// Streaming: print text as it arrives.
var stream = await client.ConverseStreamAsync(new ConverseStreamRequest
{
ModelId = modelId,
Messages = request.Messages,
InferenceConfig = request.InferenceConfig,
});
await foreach (var evt in stream.Stream)
{
if (evt is ContentBlockDeltaEvent { Delta.Text: { Length: > 0 } piece })
{
Console.Write(piece);
}
}
Console.WriteLine();Dependency injection and a provider-neutral interface
using Amazon;
using Amazon.BedrockRuntime;
using Amazon.Runtime;
using Microsoft.Extensions.AI;
using Microsoft.Extensions.DependencyInjection;
namespace Harbourline.GenAi;
public static class ServiceRegistration
{
public static IServiceCollection AddBedrockChat(this IServiceCollection services, string modelId)
{
// One long-lived client per process: it is thread safe and owns an HTTP connection pool.
services.AddSingleton<IAmazonBedrockRuntime>(_ => new AmazonBedrockRuntimeClient(new AmazonBedrockRuntimeConfig
{
RegionEndpoint = RegionEndpoint.USEast1,
RetryMode = RequestRetryMode.Standard,
MaxErrorRetry = 3,
Timeout = TimeSpan.FromSeconds(60),
}));
// The IChatClient adapter (AWSSDK.Extensions.Bedrock.MEAI): business code depends on IChatClient only.
services.AddSingleton<IChatClient>(sp => sp.GetRequiredService<IAmazonBedrockRuntime>().AsIChatClient(modelId));
return services;
}
}The tested production-shaped version of all of this, with redaction, guardrail, outcome classification, streaming and cost estimation, is in Lab 16.1 under labs/m16-policy-assistant/. Its BedrockPolicyAssistant is the class to read after this lesson.
Code explained line by line
RequestRetryMode.StandardandMaxErrorRetry = 3configure the SDK's built-in retry with backoff for throttling and transient server errors. This is why catchingThrottlingExceptionafter the call means the retries already failed.Timeout = TimeSpan.FromSeconds(60)bounds how long one call may take. Model calls can be slow for long outputs, so choose a value from measurements, not hope.System = [new SystemContentBlock { Text = ... }]carries the standing instructions. System text is separate from user messages, which helps you keep user input out of your instruction block.Messagesholds the conversation. EachMessagehas aRoleand a list ofContentBlocks. A block can be text, a guarded block for guardrails, an image or a tool result.InferenceConfigurationsetsMaxTokens(an upper bound on the answer, and so on cost) andTemperature. Keep temperature low for policy questions.response.Output.Message.Content.Where(b => b.Text is not null)filters to text only. Reasoning content would otherwise be concatenated into the user-visible answer.response.StopReason.Valueis a string such asend_turn,max_tokensorguardrail_intervened. The lab turns it into an enum so callers must handle each case.response.Usageandresponse.Metricsgive you token counts and latency: log these, never the prompt.ConverseStreamAsyncreturns an event stream. Pattern matchingContentBlockDeltaEvent { Delta.Text: { Length: > 0 } piece }prints each text fragment as it arrives.AsIChatClient(modelId)adapts the Bedrock client toIChatClient, so code that depends only onIChatClientcan later run against a local model.
Streaming with a guardrail
With a guardrail and streaming, you choose how checks interleave with output. In synchronous stream processing mode the guardrail evaluates each chunk before it reaches you, which delays the first token but never shows unchecked text. In asynchronous mode text streams first and is checked after, which feels faster but can show text that is later flagged. For a bank, start with synchronous. The lab's StreamAsync sets StreamProcessingMode = Sync.
Security considerations
⚠ Learning shortcut — not for production
The lab calls the model with your own SSO identity and an optional guardrail ID from an environment variable. A production service runs under a dedicated IAM role with the policy above, reads configuration from a managed store, calls through a VPC endpoint, and sends audit events to a protected log. Never use long-lived access keys, and never paste a Bedrock API key into a repository.
- Least privilege: one model, one profile, one guardrail, as in the policy above. Avoid
bedrock:*. - No prompts in logs. Log request ID, token counts, latency, outcome and the kinds of data redacted. If you must log prompts to debug, do it in a non-production account with fictional data.
- Treat output as untrusted. Encode before rendering. Never run model output as code or build SQL from it.
- Fail closed. If the guardrail call fails, return an error. Do not silently retry without the guardrail.
- Token cap is a cost control and a safety control. Set
MaxTokensdeliberately; it also limits how much an injected instruction can make the model write. - Secrets: nothing in the prompt should be a secret. Use Secrets Manager for anything the app itself needs.
Banking use case
An internal tool lets a mortgage adviser paste a customer's email and asks for a two-line summary. The flow redacts names, emails, IBANs and card numbers before calling the model. The model response is shown with a banner "Draft, check before use". The audit log stores the user ID, correlation ID, the redaction kinds, token counts and outcome. The summary never leaves the adviser's screen, and nothing is written to the customer's record without the adviser pressing a button. All data in your lab is fictional.
Common mistakes
- Treating the first content block as the answer. The first block can be a reasoning block. Filter for text.
- Ignoring
stopReason. A truncated or blocked reply looks like a normal answer. Branch on it. - A retry loop around
ConverseAsyncin addition to the SDK's retries. Stacked retries multiply load during an outage. Configure the SDK once. - Creating a new client per request. This wastes connections and slows calls. Register one singleton.
- Putting user text inside the system prompt. Keep roles separate so user text cannot masquerade as instructions.
- Logging full prompts and responses. That turns your log store into a copy of customer data.
- Hard-coding the model ID. Models retire. Read it from configuration and write a model-change runbook.
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
AccessDeniedException | IAM missing bedrock:InvokeModel on the profile or a destination model ARN; first-use subscription incomplete | Compare with the policy above; wait a couple of minutes after the first call |
ValidationException about on-demand throughput | Bare model ID where a profile is required | Use the us., eu. or global. profile ID |
ValidationException about the message list | Messages must alternate roles and start with user | Fix the conversation order |
ThrottlingException after retries | Account quota for the model reached | Lower concurrency, add a queue, request a quota increase |
ModelTimeoutException | Output too long or model slow | Lower MaxTokens, stream, or increase the timeout |
ModelNotReadyException | Model is warming or capacity is limited | Retry later; show "temporarily unavailable" |
| Empty text but a successful call | Only reasoning blocks returned, or MaxTokens consumed by thinking | Raise MaxTokens; filter correctly ⚠ VERIFY how reasoning counts toward the cap |
stopReason is guardrail_intervened | The guardrail blocked or masked | Read the trace; see Bedrock Guardrails |
Cost and cleanup
Cost label: credits. One short Converse call costs a fraction of a cent: with illustrative rates of 0.10 and 0.50 USD per million input and output tokens, a 500-token prompt and a 100-token answer cost about 0.0001 USD. Replace the illustrative rates with the current rates for your model from the Bedrock pricing page ⚠ VERIFY. A hundred test calls cost pennies; a runaway loop does not, so cap MaxTokens and never run model calls in an unbounded loop.
Free alternative: run the unit tests and the offline provider in the lab (no account). The deployed pieces from this lesson are only IAM policy documents and your local code, so teardown is:
# If you created the IAM policy for the lab role, delete it when you are done
aws iam list-policies --scope Local --query "Policies[?contains(PolicyName,'hl-m16')].Arn" --profile learn-sandbox
aws iam delete-policy --policy-arn <arn-from-above> --profile learn-sandbox
# Check nothing tagged Project=cea-lab remains
aws resourcegroupstaggingapi get-resources --tag-filters Key=Project,Values=cea-lab \
--profile learn-sandbox --region us-east-1Exercises
- 🟢 Guided: run the one-call program with your SSO profile. Print the stop reason and token counts. Then set
MaxTokensto 5 and observemax_tokens. - 🟡 Challenge: add a second
Messageso the conversation has a follow-up question, then print the usage again. Explain why the input token count grew. - 🔴 Live problem: production shows
ThrottlingExceptionat 09:00 every weekday when 300 advisers log in. You may not increase the quota this week. List three design changes, with the trade-off of each.
Assignment
Add a ModelOutcome enum (Answered, Truncated, Blocked) and a small AuditEvent record (correlation ID, user ID, model ID, input tokens, output tokens, outcome, redaction kinds) to your own project. Write unit tests with a substituted IAmazonBedrockRuntime that prove (1) a max_tokens reply is Truncated, (2) a guardrail reply is Blocked, and (3) the audit event never contains prompt text.
Solutions
With MaxTokens = 5 the answer stops after about five tokens and stopReason is max_tokens. That is a normal, successful HTTP response, which is exactly why you must check it: the text is incomplete.
The API is stateless, so the second request must include the first question and the first answer plus the new question. Input tokens therefore include the earlier turns, and a long chat costs more per turn. Mitigations: summarise old turns, cap history length, or use prompt caching for a stable prefix.
- Queue requests and process with bounded concurrency; trade-off: added latency under load. 2. Use a different inference profile or a second model for overflow; trade-off: consistency and review of a second model. 3. Cache answers to common, non-personal questions; trade-off: staleness, so key the cache on policy version. Also stagger rollout by team and request a quota increase for next week.
Knowledge check
Answer: The call can succeed while the reply is truncated (max_tokens) or replaced by a guardrail message (guardrail_intervened). Showing it as a normal answer misleads the user.
Answer: You must resend earlier messages each time. Token usage and cost grow with the conversation, so cap or summarise history.
Answer: Lab: an SSO profile such as learn-sandbox. Production: an IAM role attached to the compute (Fargate task role, Lambda execution role). Never long-lived keys in code.
Answer: bedrock:InvokeModelWithResponseStream (and bedrock:InvokeModel for Converse), on the model or inference-profile ARNs. Verify the exact set in the current IAM documentation.
Answer: Prompts can contain personal data. Log metadata instead: request ID, user ID, tokens, outcome, redaction kinds.
Interview questions
- How do you keep a Bedrock call from running up a bill? Cap
MaxTokens, limit history, set per-user rate limits, budget alarms, and use the smallest model that passes your evaluation. - Why return an enum instead of a string from your assistant? So every caller must handle blocked and truncated outcomes at compile time.
- How would you test code that calls Bedrock? Hide
IAmazonBedrockRuntimebehind an interface or substitute it, assert on the request your code builds and on how it classifies responses; gate real calls behind an environment flag. - What is the difference between Converse and InvokeModel? Converse is a unified chat request across providers; InvokeModel takes a model-specific body and is needed for embeddings.
Certification practice
An application calls Bedrock with Converse. Users sometimes see half-finished answers although the call returns HTTP 200. What is the MOST likely cause and fix?
A. The guardrail is disabled; enable it
B. inferenceConfig.maxTokens is too low and stopReason is max_tokens; raise it and handle the stop reason
C. The SDK retried too many times; set MaxErrorRetry to zero
D. The model ID is wrong; use InvokeModel
Answer: B. A truncated answer with a successful status is the signature of the token cap. A is unrelated; C would reduce resilience; D would produce an error, not a partial answer.
A .NET service on Amazon ECS needs to call one Bedrock model. Which approach follows least privilege and avoids long-lived credentials?
A. Store an IAM user's access keys in an environment variable
B. Attach an IAM task role allowing bedrock:InvokeModel only on the specific model or inference-profile ARNs
C. Use the account root user's keys
D. Attach AmazonBedrockFullAccess to the task role
Answer: B. A task role provides temporary credentials and scoped permissions. A and C use long-lived keys; D grants far more than needed.
Which TWO changes reduce Bedrock cost without changing the model?
A. Set maxTokens to what the answer actually needs
B. Resend the entire conversation history on every turn
C. Summarise or trim older turns in long chats
D. Increase temperature
E. Remove the system prompt entirely from every request, including safety instructions
Answer: A and C. Both reduce billed tokens. B increases cost; D does not affect cost and can hurt consistency; E removes safety instructions and is not an acceptable optimisation.
Completion checklist
- I made a Converse call and read the text, stop reason, tokens and latency
- I can explain why
stopReasondecides how I treat the text - I wrote or read a least-privilege policy for one model, one profile and one guardrail
- I configured retries once, in the SDK, and caught throttling at the end
- I ran the cleanup commands and confirmed nothing tagged
Project=cea-labremains
Key takeaways
- Converse gives one request shape across providers; the model ID is just a string.
- Read the stop reason and filter for text blocks on every response.
- The API is stateless: history costs tokens each turn.
- Configure retries once in the SDK, and keep prompts out of logs.
- Grant one model, one profile and one guardrail, and test your code without an account.
Further reading
- Models at a glance: which models support Converse and which features.
- Include a guardrail with the Converse API:
guardrailConfig,guardContentand the response trace. - Next: Knowledge Bases and RAG.
Independent learning resource — not affiliated with, endorsed or sponsored by Amazon Web Services. AWS and related marks are trademarks of Amazon.com, Inc. or its affiliates. All banking data in examples is fictional. Sample architectures are for learning and are not automatically compliant with GDPR, PCI DSS or any banking regulation.
Amazon Bedrock basics
Read the Bedrock model catalogue, understand model IDs and inference profiles, know how model access works today, compare pricing options and decide where a request's data may be processed.
Knowledge Bases and RAG
Build a retrieval-augmented generation design on Amazon Bedrock Knowledge Bases: ingest approved documents, choose a vector store and chunking, query with citations, and enforce who may see which source.