adk-go-bedrock

README

adk-go-bedrock

Amazon Bedrock Converse / ConverseStream implementation of the model.LLM interface for adk-go, so you can run agents on Claude, Nova, and other Bedrock chat models with the same ADK APIs you use for Gemini.

Requirements

• Go 1.25+ (aligned with google.golang.org/adk)
• AWS account with Bedrock model access in your chosen region
• Credentials via the default AWS chain (environment variables, shared config, IAM role, etc.)
• A region where Bedrock is available: AWS_REGION, or region in ~/.aws/config for your profile
• IAM permission to call inference, for example:
  • bedrock:InvokeModel for Converse
  • bedrock:InvokeModelWithResponseStream for ConverseStream (when ADK uses SSE streaming)
• golangci-lint if you run make lint (uses .golangci.yaml)

Install

go get github.com/craigh33/adk-go-bedrock

Replace the module path with your fork or published path if you rename the module in go.mod.

Makefile

Target	Description
make test	Run unit tests
make build	Compile all packages
make lint	Run golangci-lint run ./...
make pre-commit-install	Install pre-commit hooks

Contributing / Development

Pre-commit hooks

This project uses pre-commit to enforce code quality and commit hygiene. The following tools must be available on your PATH before installing the hooks:

Tool	Purpose	Install
pre-commit	Hook framework	brew install pre-commit
golangci-lint	Go linter (runs make lint)	brew install golangci-lint
gitleaks	Secret / credential scanner	brew install gitleaks

Once the tools are installed, wire the hooks into your local clone:

make pre-commit-install

This installs hooks for both the pre-commit stage and the commit-msg stage.

What the hooks do

Hook	Stage	Description
trailing-whitespace	pre-commit	Strips trailing whitespace
end-of-file-fixer	pre-commit	Ensures files end with a newline
check-yaml	pre-commit	Validates YAML syntax
no-commit-to-branch	pre-commit	Prevents direct commits to main
conventional-pre-commit	commit-msg	Enforces Conventional Commits message format (feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert)
golangci-lint	pre-commit	Runs make lint against all Go files
gitleaks	pre-commit	Scans staged diff for secrets/credentials

Usage

ctx := context.Background()
llm, err := bedrock.New(ctx, "us.anthropic.claude-3-5-sonnet-20241022-v2:0", &bedrock.Options{
    Region: os.Getenv("AWS_REGION"),
})
if err != nil {
    log.Fatal(err)
}

agent, err := llmagent.New(llmagent.Config{
    Name:  "assistant",
    Model: llm,
    Instruction: "You are helpful.",
})
// Wire agent into runner.New(...) as usual.

bedrock.New accepts a model ID or inference profile ARN as documented by AWS. LLMRequest.Model can override the model ID at runtime (e.g. from ADK callbacks).

The bedrock/mappers package holds genai ↔ Bedrock conversions (requests, responses, tools, usage). Import it if you need the same mappings outside the default bedrock package. The Bedrock Runtime API abstraction used by converse.go is exported from bedrock (RuntimeAPI, StreamReader, and NewRuntimeAPI).

Examples

Each example has its own README.md and Makefile:

• examples/bedrock-a2a: A2A remote-agent example backed by Bedrock.
• examples/bedrock-chat: runner-based chat example.
• examples/bedrock-tool-calling: tool-calling agent example with function declarations.
• examples/bedrock-stream: direct streaming example using GenerateContent(..., true).
• examples/bedrock-web-ui: ADK local web UI launcher.

All examples load AWS configuration with config.LoadDefaultConfig and require BEDROCK_MODEL_ID plus region configuration (AWS_REGION or profile region).

export BEDROCK_MODEL_ID=us.anthropic.claude-3-5-sonnet-20241022-v2:0
export AWS_REGION=us-east-1   # optional if your profile already defines region
make -C examples/bedrock-chat run

Run streaming example:

make -C examples/bedrock-stream run

How it maps to Bedrock

• Messages: genai roles user and model map to Bedrock user and assistant. Optional system role entries in the conversation are mapped to Bedrock system blocks.
• System instruction: GenerateContentConfig.SystemInstruction is sent as Bedrock system content.
• Tools: GenerateContentConfig.Tools with FunctionDeclarations are converted to Bedrock tool specifications. Other genai.Tool variants (Google Search, code execution, etc.) are not supported here.
• Streaming: When ADK uses SSE streaming, the provider calls ConverseStream, emits partial text responses, then a final response with TurnComplete set.

Limitations

• Non–function-calling tools: Only function declarations are mapped; retrieval, Google Search, MCP, and similar tool types are ignored.
• Multimodal: Inline images are supported for user turns with supported MIME types (image/jpeg, image/png, image/gif, image/webp). Other modalities may not round-trip.
• Streaming tool calls: Tool input is accumulated as JSON text; streamed tool use is best-effort compared to non-streaming Converse.
• Safety / guardrails: Genai safety settings are not mapped to Bedrock guardrails (you can extend the request builders if needed).

License

Apache 2.0 — see LICENSE.