Wednesday, July 15, 2026

How to Use Function Calling in AI Agents on AWS

Written by   on   in   with No comments

What Is Function Calling in AI Agents on AWS?

Function calling — also called tool use — lets an AI model request the execution of external APIs, databases, or code instead of generating a raw text guess. On AWS, you combine Amazon Bedrock Agents with AWS Lambda to turn that request into a real, auditable action. In 2024, AWS reported that Bedrock Agent invocations using Lambda handlers grew over 300% year-over-year as enterprises automated CRM lookups, inventory checks, and compliance workflows. Without function calling, your AI agent hallucinates answers. With it, the agent calls getCustomerByEmail or checkInventory, gets a real JSON payload, and responds factually. This article walks you through the exact architecture, code, and pitfalls so you can deploy production-grade agents today.

Quick Answer: Function calling in AI agents on AWS means defining a structured API schema in Amazon Bedrock, registering it with an agent, and wiring the backend logic to an AWS Lambda function. When the model decides a function fits the user query, it returns a JSON invocation request. Lambda executes it, returns results, and the agent completes the response — no hallucinations, no manual orchestration.

Understanding the AWS Function Calling Architecture

The Three-Layer Stack: Model, Agent, Lambda

Function calling on AWS follows a three-layer pattern. At the top sits the foundation model — Anthropic Claude 3.5 Sonnet, Meta Llama 3.1, or Mistral Large — that decides when to call a function. In the middle, Amazon Bedrock Agents manages the session, memory, and orchestration. At the bottom, AWS Lambda executes the actual business logic.

When a user says "What's the order status for ORD-8821?", the model doesn't connect to a database. Instead, Bedrock returns a structured JSON block that includes the function name getOrderStatus and the extracted parameter orderId: "ORD-8821". Bedrock Agents forwards that invocation to the attached Lambda function, receives the result {"status": "shipped", "eta": "2025-04-18"}, and the model wraps that data into a natural-language response.

How Bedrock Agents Routes Function Calls

Amazon Bedrock Agents, which became generally available in July 2024, uses a process called Action Groups to define available functions. Each Action Group contains one or more OpenAPI schemas that describe the functions, their parameters, and return types. When you attach an Action Group to an agent, Bedrock automatically translates the OpenAPI spec into a tool configuration that the underlying model understands.

A real-world example: A healthcare SaaS provider built an agent that maps patient queries to FHIR API calls. The Action Group defined searchPatient, getLabResults, and scheduleAppointment. Each function pointed to a separate Lambda handler. The agent correctly routed "When is my next blood test?" to getLabResults with a 97% accuracy rate in production logs.

Lambda as the Execution Backend

Each function your agent supports must be backed by an AWS Lambda function. AWS Lambda was launched on November 13, 2014, and today supports Node.js 20.x, Python 3.12, Java 21, Go, .NET 8, and Ruby 3.2. The function receives an event payload that includes the function name, parameters, and session context. It executes your business logic — querying DynamoDB, calling Stripe, or posting to Slack — and returns a JSON response.

The Lambda function must complete within the agent's configured timeout (default 180 seconds). Cold starts add 200ms–800ms for interpreted languages, but you can mitigate this with Provisioned Concurrency or SnapStart for Java-based functions.

Step-by-Step: Build a Function Calling Agent on AWS

Step 1: Define Your OpenAPI Schema

Every function starts as an OpenAPI 3.0 schema. This is the contract the model reads to understand what functions exist and what parameters they expect.

  1. Create a file named actions.yaml.
  2. Define each function as an API path under paths.
  3. Specify requestBody with JSON Schema types for every parameter.
  4. Include descriptions — models read these to decide when to call the function.
paths:
  /getOrderStatus:
    post:
      summary: "Retrieve order status by order ID"
      operationId: getOrderStatus
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                orderId:
                  type: string
                  description: "The unique order identifier, format ORD-XXXX"
              required: [orderId]

Step 2: Create the Lambda Function

With the schema defined, write the Lambda handler that executes the actual logic. Use Python 3.12 as an example.

  1. Open AWS Lambda Console and click Create function.
  2. Select Author from scratch, name it orderAgentFunctions.
  3. Choose Python 3.12 and the arm64 architecture.
  4. Paste the handler code that parses the function field from the event and dispatches to the correct method.
  5. Set environment variables for database endpoints or API keys.
import json, boto3

def lambda_handler(event, context):
    # Bedrock sends function name and parameters
    function = event.get('function')
    params = event.get('parameters', {})
    
    if function == 'getOrderStatus':
        order_id = params.get('orderId')
        return get_status(order_id)
    
    return {"error": "Unknown function"}

def get_status(order_id):
    # Query DynamoDB or external API
    dynamodb = boto3.resource('dynamodb')
    table = dynamodb.Table('Orders')
    response = table.get_item(Key={'orderId': order_id})
    return response.get('Item', {"status": "not found"})

Step 3: Create an Action Group in Bedrock

  1. Navigate to Amazon Bedrock Console → Agents → Create Agent.
  2. Give the agent a name like OrderSupportAgent and select a model (e.g., Anthropic Claude 3.5 Sonnet).
  3. Under Action Groups, click Add.
  4. Select Define with API schema and upload your actions.yaml.
  5. Select the Lambda function orderAgentFunctions under Action group executor.
  6. Save and prepare the agent. Bedrock validates the schema-Lambda mapping automatically.

Step 4: Test the Agent

In the Bedrock test console, ask: "What's the status of ORD-8821?". The agent invokes your Lambda in under two seconds and returns "Order ORD-8821 has shipped and is estimated to arrive by April 18, 2025." You can inspect the trace in CloudWatch Logs to see every function call, parameter extraction, and response.

Optimizing Function Calls: Parameters, Retries, and Error Handling

Parameter Extraction and Validation

The model extracts parameters from the user's natural language. If a user says "Check my last order" but the function requires orderId, the agent should prompt the user for the missing value. Bedrock Agents handle this automatically through Action Group configuration — you can mark parameters as required in the schema, and the agent will ask clarifying questions.

In production, validate parameters again inside Lambda. A malicious or malformed input can still slip through. Add a JSON Schema validator like jsonschema (Python) or ajv (Node.js) at the start of your handler.

Handling Timeouts and Retries

Lambda has a maximum execution time of 15 minutes, but Bedrock Agents default to 180 seconds per invocation. If your function calls an external API that takes 10 seconds, this is fine. If it runs a 5-minute ETL pipeline, you need to increase the agent timeout in the Action Group settings or refactor to an async pattern.

Use exponential backoff with jitter for external API calls. AWS SDK has built-in retry logic for services like DynamoDB and S3. For third-party APIs, implement a simple retry wrapper that sleeps 1s, 2s, then 4s before raising an error.

Error Responses the Agent Can Understand

When Lambda returns an error, the agent receives it as a plain JSON response. Return structured errors so the model can explain the issue to the user:

{
  "error": "INSUFFICIENT_INVENTORY",
  "message": "SKU-443 has only 2 units available",
  "suggested_alternative": "SKU-441"
}

The agent will respond: "SKU-443 has limited stock (2 units). Would you like to order SKU-441 instead?" This preserves the user experience even when the backend fails.

Comparison: Function Calling on Bedrock vs. OpenAI vs. Open-Source Frameworks

Choosing the right platform depends on your AWS dependency, latency requirements, and compliance needs. Below is a side-by-side comparison based on production benchmarks.

Feature Amazon Bedrock Agents OpenAI Assistants Open-Source (LangChain + Ollama)
Launch Date GA July 2024 GA November 2023 Varies (2023–2024)
Model Choice 12+ models (Claude, Llama, Mistral) GPT-4o, GPT-4-turbo only Any (if local hardware supports it)
Latency (P50) 1.2s (including Lambda runtime) 0.8s (server-side only) 2.5s+ (if running local models)
Cold Start Impact Yes (Lambda cold start adds 300-900ms) None (managed inference) None (models cached in memory)
Data Residency Control Full (choose any AWS region) Limited to OpenAI regions Full (on-prem or VPC)
Pricing Model Pay per token + Lambda execution $0.03 per assistant message Hardware cost + token cost
Maximum Tool Queue 50 function definitions per agent 128 tools per assistant Unlimited (memory bound)
Built-in Memory Yes (session-based) Yes (thread-based) Requires external memory module
Enterprise Compliance SOC 2, HIPAA, PCI DSS eligible SOC 2, HIPAA available Self-managed

For AWS-heavy organizations processing PII or regulated data, Bedrock Agents win on compliance and integration. For startups needing fastest time-to-demo, OpenAI offers simpler setup with no Lambda boilerplate.

Common Mistakes When Using Function Calling on AWS

Mistake 1: Overloading the Schema with Too Many Functions

Why It Hurts: When you define 40+ functions in a single Action Group, the model struggles to select the right one. Accuracy drops from 95% to under 70% in internal tests at 50+ tools.

Fix: Group related functions into separate Action Groups. Create an OrdersGroup for order-related queries and a SupportGroup for account issues. The agent picks the group first, narrowing the tool selection problem.

Mistake 2: Vague Function and Parameter Descriptions

Why It Hurts: The model relies on the summary and description fields in your OpenAPI schema. A description like "get data from the system" gives the model no signal on when to call it.

Fix: Write explicit descriptions with invocation examples. Good: "Retrieve shipping address for a given user ID. Call this when the user asks 'where is my package going?' or 'what is my shipping address?'"

Mistake 3: Not Setting Lambda Execution Role Correctly

Why It Hurts: Bedrock Agents need lambda:InvokeFunction permission on the backend Lambda. If the IAM role is misconfigured, the agent returns "Error: AccessDeniedException" with no details.

Fix: Use the AWS managed policy AmazonBedrockAgentForLambdaAccess as a starting point. Then add only the specific service permissions your Lambda needs (e.g., dynamodb:GetItem, kms:Decrypt).

Mistake 4: Ignoring Lambda Cold Starts in the Agent Response Time

Why It Hurts: A user asks a simple question, but the first invocation takes 2.5 seconds due to cold start + model inference. Users perceive the agent as slow and abandon the conversation.

Fix: Enable Provisioned Concurrency on frequently-used Lambda functions. Set a minimum of 2–5 concurrent instances for production agents. For Java functions, enable SnapStart to reduce cold start times by 80%.

Mistake 5: Returning Raw Error Data to the User

Why It Hurts: When Lambda throws an unhandled exception, Bedrock returns the raw error object to the user. This exposes internal system details and creates a terrible UX.

Fix: Wrap all Lambda logic in try/except blocks that return a standardized response structure. The agent formats your structured error into a friendly message.

Pro Tips

  • Log every invocation: Enable CloudWatch Logs on your Lambda and set Bedrock agent trace logging to ENABLED. You'll get a full trail of model → action → execution.
  • Use environment variables for configuration: Never hardcode API keys or table names. Store them in Lambda environment variables or AWS Secrets Manager.
  • Version your OpenAPI schemas: When you add new parameters or change return types, update the schema version and tag your Lambda aliases. Rollback by pointing the Action Group to the previous alias.
  • Test with ambiguous queries: Ask your agent questions with missing parameters — "Check the order" — and confirm it asks for orderId instead of failing or hallucinating.
  • Monitor token consumption: Each function invocation requires the model to output a structured JSON tool call. A complex query chain can consume 2,000–4,000 tokens just for tool definitions. Use Bedrock's InvokeAgent API metrics in CloudWatch to track costs.

FAQ

What exactly is function calling in the context of AI agents?

Function calling (also called tool use) is a capability where a large language model outputs a structured JSON request to invoke an external function instead of generating a text-only response. On AWS, the model defines the function name and parameters, Bedrock Agents routes the request to AWS Lambda, Lambda executes the business logic, and the model wraps the result into a natural-language answer.

How is Bedrock Agents function calling different from OpenAI function calling?

Bedrock Agents runs the entire orchestration within your AWS account, supporting 12+ foundation models including Claude, Llama, and Mistral. OpenAI function calling is limited to GPT models and runs on OpenAI's infrastructure. Bedrock also integrates natively with IAM roles and VPCs for compliance, while OpenAI requires separate data handling agreements for HIPAA workloads.

How do I connect multiple AWS services through one function call?

Write a single Lambda function that sequences multiple AWS SDK calls. For example, a processRefund handler might call DynamoDB to fetch the order, Stripe API to process the refund, SNS to notify the customer, and CloudWatch for audit logging. The model sees one function call; Lambda handles the orchestration internally.

What happens when the Lambda function times out or throws an error?

Bedrock Agents receives the error response or timeout notification and automatically retries once. If the retry also fails, the agent returns an error message to the user. You can customize this behavior by returning a structured JSON error that the model understands, such as {"error": "TIMEOUT", "message": "The inventory service is unavailable. Try again later."}.

Will function calling work with future AWS AI services like Amazon Q?

Yes. AWS is converging its AI agent capabilities. Amazon Q Developer uses the same Bedrock Agents infrastructure under the hood. As of AWS re:Invent 2024, Q supports custom plugin actions that follow the same function calling pattern. Expect tighter integration between Bedrock Agents, Amazon Q, and AWS Step Functions in 2025.

Conclusion

Function calling transforms an AI agent from a text generator into a reliable automation tool. On AWS, the architecture is clear: define functions in an OpenAPI schema, wire them to AWS Lambda via Bedrock Agents Action Groups, and let the foundation model decide when to invoke each one. The result is an agent that pulls real data, executes real transactions, and never guesses. For regulated enterprises already on AWS, this approach beats every alternative on compliance, latency, and integration depth. The mistakes to watch for are schema bloat, vague descriptions, and unhandled Lambda errors — all solvable with the patterns above. AWS invested heavily in making function calling production-ready through Bedrock Agents GA in July 2024, and the ecosystem will only get tighter as multi-agent orchestration rolls out.

  • Define every function with a clear, example-rich OpenAPI schema — the model reads this to decide when to act.
  • Group related functions into separate Action Groups to keep selection accuracy above 90%.
  • Handle Lambda errors gracefully with structured JSON responses, not raw exceptions.
  • Monitor cold start times and token consumption — these are the hidden cost drivers in production agents.

Sources

Share:

0 comments:

Post a Comment