Skip to main content
This guide provides a quick overview for getting started with Amazon Nova chat models. Amazon Nova models are OpenAI-compatible and accessed via the OpenAI SDK pointed at Nova’s endpoint, providing seamless integration with LangChain’s standard interfaces. You can find information about Amazon Nova’s models, their features, and API details in the Amazon Nova documentation.
API ReferenceFor detailed documentation of all ChatAmazonNova features and configuration options, head to the ChatAmazonNova API reference.For Amazon Nova model details and capabilities, see the Amazon Nova documentation.

​
Overview

​
Integration details

ClassPackageSerializableJS/TS SupportDownloadsLatest Version
ChatAmazonNovalangchain-amazon-nova❌beta❌PyPI - DownloadsPyPI - Version

​
Model features

Tool callingStructured outputJSON modeImage inputAudio inputVideo inputToken-level streamingNative asyncToken usageLogprobs
✅❌❌Model-dependent❌❌✅✅✅❌

​
Setup

To access Amazon Nova models, you’ll need to obtain API credentials and install the langchain-amazon-nova integration package.

​
Installation

pip install -U langchain-amazon-nova

​
Credentials

Set your Nova API credentials as environment variables: 
import getpass
import os

if "NOVA_API_KEY" not in os.environ:
    os.environ["NOVA_API_KEY"] = getpass.getpass("Enter your Nova API key: ")

if "NOVA_BASE_URL" not in os.environ:
    os.environ["NOVA_BASE_URL"] = getpass.getpass("Enter your Nova base URL: ")
To enable automated tracing of your model calls, set your LangSmith API key: 
os.environ["LANGSMITH_API_KEY"] = getpass.getpass("Enter your LangSmith API key: ")
os.environ["LANGSMITH_TRACING"] = "true"

​
Instantiation

Now we can instantiate our model object and generate chat completions: 
from langchain_amazon_nova import ChatAmazonNova

model = ChatAmazonNova(
    model="nova-2-lite-v1",
    temperature=0.7,
    max_tokens=2048,
    timeout=None,
    max_retries=2,
    # other params...
)
For a complete list of supported parameters and their descriptions, see the Amazon Nova documentation.

​
Invocation

messages = [
    (
        "system",
        "You are a helpful assistant that translates English to French. Translate the user sentence.",
    ),
    ("human", "I love programming."),
]
ai_msg = model.invoke(messages)
ai_msg

AIMessage(content="J'adore la programmation.", response_metadata={'model': 'nova-2-lite-v1', 'finish_reason': 'stop'}, id='run-12345678-1234-1234-1234-123456789abc', usage_metadata={'input_tokens': 29, 'output_tokens': 8, 'total_tokens': 37})

print(ai_msg.content)

J'adore la programmation.

​
Content blocks

Amazon Nova messages can contain either a single string or a list of content blocks. You can access standardized content blocks using the content_blocks property: 
ai_msg.content_blocks
Using content_blocks will render the content in a standard format that is consistent across other model providers. Read more about content blocks.

​
Streaming

Amazon Nova supports token-level streaming for real-time response generation: 
for chunk in model.stream(messages):
    print(chunk.content, end="", flush=True)

J'adore la programmation.

​
Async streaming

For async applications, use astream: 
import asyncio

async def main():
    async for chunk in model.astream(messages):
        print(chunk.content, end="", flush=True)

asyncio.run(main())

​
Tool calling

Amazon Nova supports tool calling (function calling) on compatible models. You can check if a model supports tool calling using LangChain model profiles.
For details on Nova’s tool calling implementation and available parameters, see the tool calling documentation.

​
Basic tool usage

Bind tools to the model using Pydantic models or LangChain @tool: 
from pydantic import BaseModel, Field

class GetWeather(BaseModel):
    """Get the weather for a location."""

    location: str = Field(..., description="City name")

model_with_tools = model.bind_tools([GetWeather])
response = model_with_tools.invoke("What's the weather in Paris?")
print(response.tool_calls)

[{'name': 'GetWeather', 'args': {'location': 'Paris'}, 'id': 'call_abc123', 'type': 'tool_call'}]
You can also access tool calls specifically in a standard format using the tool_calls attribute: 
response.tool_calls

[{'name': 'GetWeather',
  'args': {'location': 'Paris'},
  'id': 'call_abc123',
  'type': 'tool_call'}]

​
Using LangChain tools

You can also use standard LangChain tools: 
from langchain.tools import tool

@tool
def get_weather(location: str) -> str:
    """Get the weather for a location."""
    return f"Weather in {location}: Sunny, 72°F"

model_with_tools = model.bind_tools([get_weather])
response = model_with_tools.invoke("What's the weather in San Francisco?")

​
Strict tool binding

By default, BaseChatModel.bind_tools validates that the model supports tool calling. To disable this validation: 
model_with_tools = model.bind_tools([GetWeather], strict=False)

​
System tools

Amazon Nova provides built-in system tools that can be enabled by passing them to the model initialization. See the Amazon Nova documentation for available system tools and their capabilities. 
from langchain_amazon_nova import ChatAmazonNova

model = ChatAmazonNova(
    model="nova-2-lite-v1",
    system_tools=["nova_grounding", "nova_code_interpreter"],
)
System toolsSystem tools like nova_grounding and nova_code_interpreter provide built-in capabilities. For details on available system tools and their usage, see the Amazon Nova documentation.

​
Model Profile

Amazon Nova provides different models with varying capabilities. It includes support for LangChain model profiles.
Model capabilities vary by modelSome Amazon Nova models support vision inputs while others do not. Always check model capabilities before using multimodal features.For a complete list of available models and their capabilities, see the Amazon Nova documentation.

​
Async operations

For production applications requiring high throughput, use native async operations: 
import asyncio

async def main():
    messages = [
        ("system", "You are a helpful assistant."),
        ("human", "What is the capital of France?"),
    ]
    response = await model.ainvoke(messages)
    print(response.content)

asyncio.run(main())

The capital of France is Paris.

​
Chaining

Amazon Nova models work seamlessly with LangChain’s LCEL (LangChain Expression Language) for building chains: 
from langchain_core.output_parsers import StrOutputParser
from langchain_core.prompts import ChatPromptTemplate

prompt = ChatPromptTemplate.from_messages([
    ("system", "You are a helpful assistant that translates {input_language} to {output_language}."),
    ("human", "{text}"),
])

chain = prompt | model | StrOutputParser()

result = chain.invoke({
    "input_language": "English",
    "output_language": "Spanish",
    "text": "Hello, how are you?"
})
print(result)

Hola, ¿cómo estás?

​
Error handling

The model includes built-in retry logic with configurable parameters: 
model = ChatAmazonNova(
    model="nova-2-lite-v1",
    max_retries=3,  # Number of retries on failure
    timeout=60.0,   # Request timeout in seconds
)
For additional control over retries, use the with_retry method: 
model_with_custom_retry = model.with_retry(
    stop_after_attempt=5,
    wait_exponential_jitter=True,
)

​
Troubleshooting

​
Connection issues

If you encounter connection errors, verify your environment variables are set correctly: 
import os
print(f"API Key set: {'NOVA_API_KEY' in os.environ}")
print(f"Base URL: {os.environ.get('NOVA_BASE_URL', 'Not set')}")
For authentication and connection issues, refer to the Amazon Nova documentation.

​
Compression errors

The ChatAmazonNova client automatically disables compression to avoid potential decompression issues.
If you need to customize HTTP client behavior, you can access the underlying OpenAI client: 
# The client is automatically configured with no compression
model = ChatAmazonNova(model="nova-2-lite-v1")
# model.client is the configured OpenAI client

​
Tool calling validation errors

If you receive a validation error when binding tools, ensure the model supports tool calling.

​
API reference

For detailed documentation of all ChatAmazonNova features and configurations, head to the ChatAmazonNova API reference. For Amazon Nova-specific features, model details, and API specifications, see the Amazon Nova documentation.
Edit the source of this page on GitHub.
Connect these docs programmatically to Claude, VSCode, and more via MCP for real-time answers.