Add AWS Bedrock configuration guide for SDK users

[jpshackelford]

Problem

Users trying to use the OpenHands Software Agent SDK with AWS Bedrock models (like Claude) often find it tricky to configure. The current documentation doesn't have a dedicated Bedrock guide, and users need to piece together information from the LiteLLM docs.

Common pain points:

• Not knowing that boto3 is required (but doesn't need to be imported in user code)
• Confusion about the bedrock/ model prefix format
• Understanding which AWS authentication methods are supported
• Finding the correct Bedrock model IDs

Suggestion

Add a Bedrock-specific guide to the LLM provider documentation, similar to the existing guides for Azure, Google, OpenRouter, etc.

Draft Tutorial

I've created a draft HTML tutorial that covers:

1. Prerequisites and boto3 installation
2. AWS credential configuration (multiple auth methods)
3. Bedrock model name format
4. Complete working code example
5. Environment variable configuration

The key content that should be documented:

Installation

pip install openhands-sdk boto3>=1.28.57

Note: boto3 is used internally by LiteLLM - users don't need to import it in their code.

Authentication Options

Method	Environment Variables
Access Keys	AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY
Session Token	AWS_SESSION_TOKEN
AWS Profile	AWS_PROFILE_NAME
IAM Role	AWS_ROLE_NAME, AWS_WEB_IDENTITY_TOKEN
Bedrock API Key	AWS_BEARER_TOKEN_BEDROCK

Model Names

Use the bedrock/ prefix followed by the Bedrock model ID:

• bedrock/anthropic.claude-3-5-sonnet-20241022-v2:0
• bedrock/anthropic.claude-3-opus-20240229-v1:0
• bedrock/anthropic.claude-3-haiku-20240307-v1:0

Example Code

import os
from openhands.sdk import LLM, Agent, Conversation, Tool
from openhands.tools.terminal import TerminalTool
from openhands.tools.file_editor import FileEditorTool

os.environ["AWS_ACCESS_KEY_ID"] = "your-access-key"
os.environ["AWS_SECRET_ACCESS_KEY"] = "your-secret-key"
os.environ["AWS_REGION_NAME"] = "us-east-1"

llm = LLM(
    model="bedrock/anthropic.claude-3-5-sonnet-20241022-v2:0",
)

agent = Agent(
    llm=llm,
    tools=[
        Tool(name=TerminalTool.name),
        Tool(name=FileEditorTool.name),
    ],
)

conversation = Conversation(agent=agent, workspace=os.getcwd())
conversation.send_message("Your task here")
conversation.run()

Happy to help with a PR if this would be useful!

[jpshackelford]

bedrock-tutorial.html

[jpshackelford]

@OpenHands recommend some suitable places in our docs for this content. One is an SDK example. But there may be other places that would make sense too.

[openhands-ai]

I'm on it! jpshackelford can track my progress at all-hands.dev

[openhands-ai]

Summary: Recommended Locations for AWS Bedrock Documentation

Based on my analysis of the OpenHands documentation structure, here are the recommended places for the AWS Bedrock configuration content:

1. Primary Location: LLM Provider Guide

Path: openhands/usage/llms/bedrock-llms.mdx

This is the most natural fit, following the existing pattern for provider-specific guides:

• azure-llms.mdx
• google-llms.mdx
• groq.mdx
• openrouter.mdx

This location would be:

• Listed in the "LLM Provider Guides" section of llms.mdx
• Referenced from sdk/arch/llm.mdx in the LLM Providers table
• Accessible from both the Web and SDK documentation tabs

2. Secondary Location: SDK Guide

Path: sdk/guides/llm-bedrock.mdx

This would be an SDK-focused guide with a working code example, following the pattern of:

• sdk/guides/llm-registry.mdx
• sdk/guides/llm-routing.mdx

This would be added to the "LLM Features" group in the SDK navigation.

3. Cross-references to Update

• openhands/usage/llms/llms.mdx - Add Bedrock to the provider list
• sdk/arch/llm.mdx - Add Bedrock to the LLM Providers table
• docs.json - Add navigation entries for both new pages

---

Note: I did not make any changes to the repository - this was a recommendation-only task. If you'd like me to proceed with implementing these documentation files, please let me know and I'll create the files, update the cross-references, and open a PR.

View full conversation

[jpshackelford]

Implementation Proposal

After analyzing the documentation structure, here's a proposal for implementing this feature request.

Summary

This requires changes across two repositories and creates a new "LLM Providers" section in the SDK documentation that can be expanded for other providers with similar complexity (Vertex AI, local LLMs, etc.).

---

PR 1: OpenHands/software-agent-sdk

New example files:

File	Description
examples/01_standalone_sdk/15_llm_bedrock.py	Complete working example for AWS Bedrock

The example will demonstrate:

• Setting AWS credentials via environment variables
• Configuring the LLM with bedrock/ model prefix
• Running a simple agent task

---

PR 2: OpenHands/docs

New files:

File	Description
sdk/guides/llm-provider-bedrock.mdx	SDK guide for AWS Bedrock (syncs with agent-sdk example)
openhands/usage/llms/bedrock-llms.mdx	Self-hosted OpenHands guide (Docker env vars + UI config)

Updated files:

File	Change
docs.json	Add new "LLM Providers" group under SDK Guides
openhands/usage/llms/llms.mdx	Add Bedrock to LLM Provider Guides list
sdk/arch/llm.mdx	Add Bedrock to LLM Providers table

---

Proposed Navigation Structure

SDK
├── Guides
│   ├── ...existing guides...
│   ├── LLM Features (existing group)
│   │   └── ...
│   ├── LLM Providers (NEW group)  ← Add after LLM Features
│   │   └── AWS Bedrock
│   ├── Agent Features (existing group)
│   │   └── ...

---

Content Outline

sdk/guides/llm-provider-bedrock.mdx

---
title: AWS Bedrock
description: Configure the SDK to use Claude and other models via AWS Bedrock
---

## Prerequisites
- boto3 installation (used internally by LiteLLM)
- AWS credentials configured

## Authentication Options
[Table of AWS auth methods from issue]

## Model Names
[bedrock/ prefix format and examples]

## Example
[Synced code block from agent-sdk example]

## Running the Example
[Bash commands with env var exports]

openhands/usage/llms/bedrock-llms.mdx

---
title: AWS Bedrock
description: OpenHands uses LiteLLM to make calls to AWS Bedrock models.
---

## Prerequisites
- boto3 must be available in the runtime

## Configuration (Self-Hosted)

### 1. Set AWS Environment Variables
[Docker -e flags for AWS credentials]

### 2. Configure in UI
- Enable Advanced options
- Set Custom Model to bedrock/<model-id>

## Authentication Options
[Table of AWS auth methods]

## Available Models
[List of Bedrock model IDs]

---

Future Expansion

The new "LLM Providers" group can later include:

• llm-provider-vertex.mdx - Google Vertex AI (similar cloud credential pattern)
• llm-provider-local.mdx - Local models (Ollama, vLLM, SGLang, LM Studio)

---

Questions

1. Should we create the docs PR first with placeholder code blocks, or wait for the agent-sdk example PR?
2. Any preferences on the example file numbering (I used 15_ as a placeholder)?

[jpshackelford]

Updated Proposal: Examples Directory in software-agent-sdk

After further thought, it would be even more useful to add an examples/llm-providers/ subdirectory in the software-agent-sdk repository with working examples for various LLM providers.

This way users can:

• Clone the repo and run examples directly
• See real, tested code rather than just documentation snippets
• Have a consistent pattern to follow for each provider

Proposed Structure

examples/
├── 01_standalone_sdk/
│   └── ... (existing examples)
├── llm-providers/
│   ├── README.md
│   ├── bedrock_claude.py
│   ├── azure_openai.py
│   ├── google_vertex.py
│   ├── openai_direct.py
│   ├── anthropic_direct.py
│   └── openrouter.py

Draft Examples

bedrock_claude.py

"""
AWS Bedrock with Claude models.

Prerequisites:
    pip install boto3>=1.28.57

Environment variables:
    AWS_ACCESS_KEY_ID       - Your AWS access key
    AWS_SECRET_ACCESS_KEY   - Your AWS secret key
    AWS_REGION_NAME         - AWS region (e.g., us-east-1)
"""
import os
from openhands.sdk import LLM, Agent, Conversation, Tool
from openhands.tools.terminal import TerminalTool
from openhands.tools.file_editor import FileEditorTool

llm = LLM(
    model=os.getenv("LLM_MODEL", "bedrock/anthropic.claude-3-5-sonnet-20241022-v2:0"),
)

agent = Agent(
    llm=llm,
    tools=[Tool(name=TerminalTool.name), Tool(name=FileEditorTool.name)],
)

conversation = Conversation(agent=agent, workspace=os.getcwd())
conversation.send_message("List the files in this directory and summarize what you see.")
conversation.run()

azure_openai.py

"""
Azure OpenAI Service.

Environment variables:
    AZURE_API_KEY           - Your Azure OpenAI API key
    AZURE_API_BASE          - Your Azure endpoint (e.g., https://your-resource.openai.azure.com/)
    AZURE_API_VERSION       - API version (e.g., 2024-02-15-preview)
    LLM_MODEL               - Deployment name (e.g., azure/your-gpt4-deployment)
"""
import os
from openhands.sdk import LLM, Agent, Conversation, Tool
from openhands.tools.terminal import TerminalTool
from openhands.tools.file_editor import FileEditorTool

llm = LLM(
    model=os.getenv("LLM_MODEL", "azure/your-deployment-name"),
    api_key=os.getenv("AZURE_API_KEY"),
    base_url=os.getenv("AZURE_API_BASE"),
    api_version=os.getenv("AZURE_API_VERSION", "2024-02-15-preview"),
)

agent = Agent(
    llm=llm,
    tools=[Tool(name=TerminalTool.name), Tool(name=FileEditorTool.name)],
)

conversation = Conversation(agent=agent, workspace=os.getcwd())
conversation.send_message("List the files in this directory and summarize what you see.")
conversation.run()

google_vertex.py

"""
Google Vertex AI / Gemini.

Prerequisites:
    pip install google-cloud-aiplatform

Environment variables:
    GOOGLE_APPLICATION_CREDENTIALS  - Path to service account JSON
    VERTEXAI_PROJECT               - Your GCP project ID
    VERTEXAI_LOCATION              - Region (e.g., us-central1)
"""
import os
from openhands.sdk import LLM, Agent, Conversation, Tool
from openhands.tools.terminal import TerminalTool
from openhands.tools.file_editor import FileEditorTool

llm = LLM(
    model=os.getenv("LLM_MODEL", "vertex_ai/gemini-1.5-pro"),
)

agent = Agent(
    llm=llm,
    tools=[Tool(name=TerminalTool.name), Tool(name=FileEditorTool.name)],
)

conversation = Conversation(agent=agent, workspace=os.getcwd())
conversation.send_message("List the files in this directory and summarize what you see.")
conversation.run()

openai_direct.py

"""
OpenAI API directly.

Environment variables:
    OPENAI_API_KEY  - Your OpenAI API key
"""
import os
from openhands.sdk import LLM, Agent, Conversation, Tool
from openhands.tools.terminal import TerminalTool
from openhands.tools.file_editor import FileEditorTool

llm = LLM(
    model=os.getenv("LLM_MODEL", "openai/gpt-4o"),
    api_key=os.getenv("OPENAI_API_KEY"),
)

agent = Agent(
    llm=llm,
    tools=[Tool(name=TerminalTool.name), Tool(name=FileEditorTool.name)],
)

conversation = Conversation(agent=agent, workspace=os.getcwd())
conversation.send_message("List the files in this directory and summarize what you see.")
conversation.run()

anthropic_direct.py

"""
Anthropic API directly.

Environment variables:
    ANTHROPIC_API_KEY  - Your Anthropic API key
"""
import os
from openhands.sdk import LLM, Agent, Conversation, Tool
from openhands.tools.terminal import TerminalTool
from openhands.tools.file_editor import FileEditorTool

llm = LLM(
    model=os.getenv("LLM_MODEL", "anthropic/claude-sonnet-4-5-20250929"),
    api_key=os.getenv("ANTHROPIC_API_KEY"),
)

agent = Agent(
    llm=llm,
    tools=[Tool(name=TerminalTool.name), Tool(name=FileEditorTool.name)],
)

conversation = Conversation(agent=agent, workspace=os.getcwd())
conversation.send_message("List the files in this directory and summarize what you see.")
conversation.run()

openrouter.py

"""
OpenRouter (access multiple providers through one API).

Environment variables:
    OPENROUTER_API_KEY  - Your OpenRouter API key
"""
import os
from openhands.sdk import LLM, Agent, Conversation, Tool
from openhands.tools.terminal import TerminalTool
from openhands.tools.file_editor import FileEditorTool

llm = LLM(
    model=os.getenv("LLM_MODEL", "openrouter/anthropic/claude-3.5-sonnet"),
    api_key=os.getenv("OPENROUTER_API_KEY"),
    base_url="https://openrouter.ai/api/v1",
)

agent = Agent(
    llm=llm,
    tools=[Tool(name=TerminalTool.name), Tool(name=FileEditorTool.name)],
)

conversation = Conversation(agent=agent, workspace=os.getcwd())
conversation.send_message("List the files in this directory and summarize what you see.")
conversation.run()

Benefits

1. Discoverability - Users browsing the SDK examples will find provider configs
2. Testable - Examples can be validated in CI (with mocked credentials)
3. Consistent - Same task across all providers makes comparison easy
4. Maintainable - Code changes can be tested against real examples

Happy to open a PR for this in the software-agent-sdk repo!