RubyLLM Agent for AWS Bedrock AgentCore

A "hello world" agent built with RubyLLM that can be deployed to AWS Bedrock AgentCore.

Overview

This agent provides a simple conversational AI interface using RubyLLM's unified API. It supports multiple LLM providers including OpenAI, Anthropic Claude, and AWS Bedrock.

AgentCore Requirements

AWS Bedrock AgentCore requires:

• /invocations endpoint: POST endpoint for agent interactions (supports streaming)
• /ping endpoint: GET endpoint for health checks
• Docker container: ARM64 architecture
• Port 8080: Application must run on this port

Project Structure

.
├── Gemfile          # Ruby dependencies
├── agent.rb         # Main Sinatra application
├── config.ru        # Rack configuration
├── puma.rb          # Puma web server configuration
├── Dockerfile       # ARM64 container configuration
└── README.md        # This file

Quick Start

Prerequisites

• Ruby 3.2+
• Docker with buildx support
• AWS CLI configured
• An LLM API key (OpenAI, Anthropic, etc.)

Local Development

1. Install dependencies:

bundle install

2. Set your API key:

# For OpenAI (default)
export OPENAI_API_KEY="your-api-key"

# Or for Anthropic Claude
export ANTHROPIC_API_KEY="your-api-key"

# Optionally set a different model
export MODEL="gpt-4o-mini"  # or "claude-sonnet-4", etc.

3. Run the server:

bundle exec puma -C puma.rb

4. Test the endpoints:

# Health check
curl http://localhost:8080/ping

# Invoke the agent
curl -X POST http://localhost:8080/invocations \
  -H "Content-Type: application/json" \
  -d '{
    "input": {"prompt": "Hello! What is Ruby?"}
  }'

Docker Build & Test

Setup Docker buildx

docker buildx create --use

Build for ARM64

docker buildx build --platform linux/arm64 -t rubyllm-agent:arm64 --load .

Test Locally

docker run --platform linux/arm64 -p 8080:8080 \
  -e OPENAI_API_KEY="$OPENAI_API_KEY" \
  rubyllm-agent:arm64

Then test with curl:

curl http://localhost:8080/ping
curl -X POST http://localhost:8080/invocations \
  -H "Content-Type: application/json" \
  -d '{"input": {"prompt": "Hello!"}}'

Deploy to AWS Bedrock AgentCore

1. Create ECR Repository

aws ecr create-repository --repository-name rubyllm-agent --region us-west-2

2. Login to ECR

aws ecr get-login-password --region us-west-2 | \
  docker login --username AWS --password-stdin \
  <account-id>.dkr.ecr.us-west-2.amazonaws.com

3. Build and Push

docker buildx build --platform linux/arm64 \
  -t <account-id>.dkr.ecr.us-west-2.amazonaws.com/rubyllm-agent:latest \
  --push .

4. Create Agent Runtime

Create a file deploy_agent.py:

import boto3

client = boto3.client('bedrock-agentcore-control', region_name='us-west-2')

response = client.create_agent_runtime(
    agentRuntimeName='rubyllm_agent',
    agentRuntimeArtifact={
        'containerConfiguration': {
            'containerUri': '<account-id>.dkr.ecr.us-west-2.amazonaws.com/rubyllm-agent:latest'
        }
    },
    networkConfiguration={"networkMode": "PUBLIC"},
    roleArn='arn:aws:iam::<account-id>:role/AgentRuntimeRole',
    environmentVariables={
        'OPENAI_API_KEY': '<your-api-key>'  # Or use AWS Secrets Manager
    }
)

print(f"Agent Runtime ARN: {response['agentRuntimeArn']}")
print(f"Status: {response['status']}")

Run:

python deploy_agent.py

5. Invoke Deployed Agent

import boto3
import json

client = boto3.client('bedrock-agentcore', region_name='us-west-2')

response = client.invoke_agent_runtime(
    agentRuntimeArn='arn:aws:bedrock-agentcore:us-west-2:<account-id>:runtime/rubyllm_agent-<suffix>',
    runtimeSessionId='your-unique-session-id-must-be-33-chars',
    payload=json.dumps({
        "input": {"prompt": "What is artificial intelligence?"}
    }),
    qualifier="DEFAULT"
)

response_body = response['response'].read()
print(json.loads(response_body))

Configuration

Environment Variables

Variable	Description	Default
OPENAI_API_KEY	OpenAI API key	-
ANTHROPIC_API_KEY	Anthropic API key	-
AWS_REGION	AWS region for Bedrock	-
AWS_ACCESS_KEY_ID	AWS access key	-
AWS_SECRET_ACCESS_KEY	AWS secret key	-
AWS_SESSION_TOKEN	AWS session token	-
MODEL	LLM model to use	gpt-4o-mini
PUMA_WORKERS	Number of Puma workers	1
PUMA_THREADS	Threads per worker	5

Supported Models

RubyLLM supports 500+ models including:

• OpenAI: gpt-4o, gpt-4o-mini, gpt-4-turbo
• Anthropic: claude-sonnet-4, claude-3-5-haiku
• Google: gemini-2.0-flash, gemini-1.5-pro
• AWS Bedrock: Various models via Bedrock API

API Reference

POST /invocations

Invoke the agent with a prompt. Responses are streamed back as JSON chunks.

See: AgentCore Response Streaming

Request:

{
  "input": {
    "prompt": "Your question here"
  }
}

Streaming Response:

Text chunks are streamed directly as plain text:

Hello there! How can I help you today?

Test locally with curl:

curl -N -X POST http://localhost:8080/invocations \
  -H "Content-Type: application/json" \
  -d '{"input": {"prompt": "Tell me a short story"}}'

Invoke via AWS SDK (Python):

python invoke_agent.py --stream --prompt "Hello!"

GET /ping

Health check endpoint.

Response:

{
  "status": "healthy",
  "timestamp": "2025-12-08T12:00:00Z"
}

License

MIT