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.

Other providers: adk-go-ollama · adk-go-kronk

Requirements

• Go 1.25+ (aligned with google.golang.org/adk/v2)
• 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)

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.

Usage

ctx := context.Background()
llm, err := converse.New(ctx, "us.anthropic.claude-3-5-sonnet-20241022-v2:0", &converse.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.

converse.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 converse package. It also exports MIMETypeFromExtension for inferring MIME types from a filename when building genai parts. The Bedrock Runtime API abstraction used by converse.go is exported from converse (RuntimeAPI, StreamReader, and NewRuntimeAPI).

Examples

These runnable programs show how to wire adk-go-bedrock into ADK agents: chat runners, tools, streaming, multimodal and document flows, guardrails, and provider-specific options. Each example has its own README.md and Makefile:

• examples/bedrock-a2a: A2A remote-agent example backed by Bedrock.
• examples/bedrock-artifact-s3: durable artifact storage in Amazon S3 via artifact/s3, an S3 implementation of ADK's artifact.Service.
• examples/bedrock-chat: runner-based chat example.
• examples/bedrock-mcp: MCP support via ADK's mcptoolset with an in-memory MCP server (MCP support).
• examples/bedrock-tool-calling: tool-calling agent example with function declarations.
• examples/bedrock-function-tool: ADK functiontool with typed args/results and llmagent + runner (contrasts with hand-written genai.Tool in bedrock-tool-calling).
• examples/bedrock-image-gen: ADK runner with the imagegenerator tool—Nova Canvas image generation via Bedrock InvokeModel and artifact storage.
• examples/bedrock-video-gen: ADK runner with the videogenerator tool—Nova Reel text-to-video via Bedrock async invoke, S3 output, and optional MP4 download into artifacts.
• examples/bedrock-nova-grounding: Nova Web Grounding via tools/novagrounding; prints answers and bedrock_citations metadata (see Nova Web Grounding).
• examples/bedrock-stream: direct streaming example using GenerateContent(..., true).
• examples/bedrock-tool-variants: function declaration support plus early detection of non-function ADK tool variants that Bedrock does not currently support.
• examples/bedrock-multimodal: comprehensive image analysis, document processing, tool calling with rich media, and vision-based reasoning.
• examples/bedrock-prompt-cache: ModelOption / Bedrock prompt caching for fewer repeated tokens (see AWS prompt caching docs).
• examples/bedrock-document: CLI to debug document uploads (-dry-run mapper check, optional -combined / -stream).
• examples/bedrock-guardrails: safety assessments, content filtering, and guardrail metadata handling.
• examples/bedrock-request-guardrail: request-side Bedrock guardrail configuration via ModelOption.
• examples/bedrock-system-instruction: system instructions for role definition, output formatting, and behavioral control.
• 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: the mapper converts GenerateContentConfig.Tools entries:
  • FunctionDeclarations → Bedrock ToolSpecification (custom function tools)
  • Nova Web Grounding (Bedrock-only): the reserved sentinel from tools/novagrounding maps to Bedrock Converse types.SystemTool{Name: "nova_grounding"} (not a custom ToolSpecification; see Amazon Nova Web Grounding)
  • Non-function ADK variants (Google Search, Code Execution, Retrieval, MCP Servers, Computer Use, File Search, Google Maps, URL Context, etc.) are rejected early with a clear provider error because they are not currently mapped to Bedrock Converse
  • MCP: use ADK mcptoolset so MCP tools become function declarations before they reach this provider (MCP support). Other genai.Tool variants (Google Search, code execution, etc.) are not supported here.
• Multimodal parts: ADK Part text, thoughts/reasoning, inline/file-backed images, audio, video, and documents are mapped on the Bedrock-compatible subset. Rich user media is sent as Bedrock content blocks; assistant reasoning is preserved as Bedrock reasoning content.
• Function responses: JSON tool output still maps as before, and image/video/document FunctionResponse.Parts are preserved through Bedrock tool-result content blocks.
• Streaming: When ADK uses SSE streaming, the provider calls ConverseStream, emits partial text responses, and buffers streamed tool calls, reasoning blocks, image blocks, citation deltas (for grounded responses), usage, and guardrail metadata into the final TurnComplete response.
• Guardrails / safety results: Bedrock guardrail stop reasons and trace metadata are mapped back into ADK FinishReason and CustomMetadata, including synthesized safety_ratings derived from Bedrock guardrail assessments when available.

Nova Web Grounding

Enable real-time web search for supported Nova models by adding novagrounding.Tool() to GenerateContentConfig.Tools. This tool is Bedrock-specific. Use an applicable Bedrock region and an inference profile that supports Web Grounding (for example us.amazon.nova-2-lite-v1:0; see AWS docs for current model IDs). For current regional availability, check Amazon Bedrock pricing. Converse request payloads use SystemTool name nova_grounding, while IAM policies for bedrock:InvokeTool may reference the resource identifier amazon.nova_grounding.

import (
    "context"

    "google.golang.org/adk/v2/model"
    "google.golang.org/genai"

    "github.com/craigh33/adk-go-bedrock/tools/novagrounding"
)

func groundedAsk(ctx context.Context, llm model.LLM, question string) (*model.LLMResponse, error) {
    req := &model.LLMRequest{
        Contents: []*genai.Content{
            genai.NewContentFromText(question, genai.RoleUser),
        },
        Config: &genai.GenerateContentConfig{
            Tools:           []*genai.Tool{novagrounding.Tool()},
            MaxOutputTokens: 1024,
        },
    }
    var last *model.LLMResponse
    for resp, e := range llm.GenerateContent(ctx, req, false) {
        if e != nil {
            return nil, e
        }
        last = resp
    }
    return last, nil
}

Grounded replies include citation payloads under genai.Part.PartMetadata with key "bedrock_citations" (each entry may include location.url, location.domain, etc.). Retain and surface those citations in user-facing output per AWS guidance.

A runnable CLI lives at examples/bedrock-nova-grounding.

Limitations

• Bedrock role restrictions: Rich media input still follows Bedrock Converse constraints (for example, user turns are the interoperable place for images/documents/audio/video, while model turns are reserved for text/tool use/reasoning).
• Request-side generic guardrails: ADK SafetySettings / ModelArmorConfig are not currently supported for Bedrock Converse. Because they do not contain the Bedrock guardrail identifier + version required by Converse, the request builder returns an explicit error instead of silently dropping them, and there is currently no supported way to provide GuardrailIdentifier / GuardrailVersion through this provider.
• Provider surface mismatch: Bedrock-specific features that require pre-provisioned AWS resources or have no generic ADK equivalent are exposed back through ADK-friendly CustomMetadata, but cannot always be reconstructed into first-class genai request fields.
• Unsupported tool types: Tool variants not supported by Bedrock or the target model cause a request-time error with details about which variants are unsupported.

Contributing

See CONTRIBUTING.md for Makefile targets, required pre-commit setup, commit message conventions, and pull request guidelines. For new issues, use the bug report or feature request templates.

License

Apache 2.0 — see LICENSE.

Contributing · Issues · Security