AWS Bedrock Agents¶
Bedrock Agents can't send their own model calls through the gateway. An agent's orchestration model must be a model in Amazon Bedrock, and AWS calls it directly. What you can send through the gateway is every model call your own code makes: in an action group's Lambda function, or in an agent you write with a framework and host on Amazon Bedrock AgentCore. Those calls are then checked against your policies, charged to the right team and recorded in Request logs.
What it is¶
| Part | Who calls the model | Through the gateway |
|---|---|---|
| A Bedrock agent's orchestration (planning, choosing actions, answering) | AWS, with a Bedrock model | No |
| An action group's Lambda function that calls a model itself | Your code | Yes, with an SDK pointed at the gateway |
| An agent you write (with an agent framework or your own code) and host on AgentCore Runtime | Your code | Yes: AgentCore runs any model, so the agent's every model call can go through the gateway |
The gateway can itself call models in Bedrock (Claude, Nova, Llama, Mistral) once an admin adds Bedrock as a provider, so moving an agent's model calls into your own code doesn't mean leaving Bedrock's models.
The two settings¶
In the Lambda function or the AgentCore agent, the model SDK's two settings:
| Setting | Environment variable (OpenAI SDK) | Value |
|---|---|---|
| Base address | OPENAI_BASE_URL |
https://<your-gateway>/v1 |
| Key | OPENAI_API_KEY |
Your Vidai key (starts vk_), never a provider's key |
For the Anthropic SDK: ANTHROPIC_BASE_URL = https://<your-gateway> and ANTHROPIC_API_KEY = your Vidai key. Keep the
key in AWS Secrets Manager (or an encrypted environment variable) and read it at start-up.
The gateway's address is under Connect your app on the Keys page and in System › Settings › Gateway. You get the key from Keys › Issue a key; its secret is shown once.
A minimal call¶
An action group's Lambda function (function details) that drafts a reply through the gateway:
from openai import OpenAI
llm = OpenAI() # reads OPENAI_BASE_URL and OPENAI_API_KEY
def lambda_handler(event, context):
params = {p["name"]: p["value"] for p in event.get("parameters", [])}
reply = llm.chat.completions.create(
model="claude-sonnet-4.5",
messages=[{"role": "user", "content": f"Draft a short reply to: {params.get('message', '')}"}],
)
return {
"messageVersion": "1.0",
"response": {
"actionGroup": event["actionGroup"],
"function": event["function"],
"functionResponse": {"responseBody": {"TEXT": {"body": reply.choices[0].message.content}}},
},
}
Any approved model works in model: gpt-4o-mini, claude-sonnet-4.5 or gemini-3.5-flash. The gateway translates
the request for that provider and the answer back into the OpenAI shape.
For an agent on AgentCore, configure the framework's OpenAI-compatible (or Anthropic) model with the same two settings; every step of the agent then goes through the gateway. See LangChain for one framework's settings.
Tool calls¶
In an agent you host yourself, tools are offered to the model in each call and work on every provider the gateway translates to. In Request logs, the Tool filter under More filters finds the calls that offered or called a tool by its name. A Bedrock agent's own action groups are chosen by its Bedrock model, outside the gateway.
Reading what the gateway did¶
raw = llm.chat.completions.with_raw_response.create(model="gpt-4o-mini", messages=messages)
print(raw.headers.get("x-vidai-request-id")) # log it; paste into Request logs › Request reference
Write the reference to CloudWatch beside the agent's session id, so one search finds both. Cost is never in the answer: find the call in Request logs.
Errors¶
The SDK raises its usual exceptions; match on the x-vidai-error-code header. Return a short text to the agent rather
than failing the Lambda, so the agent can tell the user:
import openai
try:
reply = llm.chat.completions.create(model="gpt-4o-mini", messages=messages)
text = reply.choices[0].message.content
except openai.APIStatusError as e:
text = f"Could not draft a reply ({e.response.headers.get('x-vidai-error-code')})."
The full list of codes is on the OpenAI SDK for Python page.
Model names¶
Use the names your organisation has approved, as listed under Models in the Control room, not Bedrock model ids.
llm.models.list() returns exactly the models your key may call.
What goes through the gateway¶
| On AWS | Through the gateway |
|---|---|
| Model calls from your Lambda functions, containers or AgentCore agents, with an SDK pointed at the gateway | Yes, to every provider your organisation has set up, Bedrock included |
| A Bedrock agent's orchestration and answers | No: AWS calls a Bedrock model directly |
| Bedrock knowledge bases and flows | No: they call Bedrock models directly |
Check it works in a minute¶
Test the action group from the agent's test window in the Bedrock console, or invoke the Lambda function with a test event. The call shows in Request logs within seconds, under the function's key.
Good to know¶
- The function must reach the gateway: a Lambda function in a VPC needs a route out (a NAT gateway, or a private connection to where the gateway runs).
- Give each agent its own key (an agent's key in Vidai works well) so each one's spend is apart.
- The SDK retries twice by default and Lambda functions have a time limit; set
max_retries=0or1and atimeoutshorter than the function's. - To move a whole Bedrock agent under your policies, rebuild it with an agent framework on AgentCore (or anywhere you run code) and give the framework the gateway's address.