MinimalAgent

A lightweight agent framework for building agentic applications with Amazon Bedrock.

Installation

pip install minimalagent

Quick Start

from minimalagent import Agent, tool

@tool
def get_weather(location: str):
    """Get weather for a location.

    Args:
        location: City name to get weather for

    Returns:
        Weather data dictionary
    """
    # Your implementation here
    return {"temperature": 22, "condition": "sunny"}

# Create agent
agent = Agent(tools=[get_weather])

# Run a query
response, reasoning = agent.run("What's the weather in San Francisco?")
print(response)

Key Features

• Simple API: Intuitive design with minimal boilerplate
• Tool-first approach: Easy tool creation with docstring parsing
• Built-in session memory: Persistent conversations via DynamoDB
• Step-by-step reasoning: Visibility into the agent's thought process

MinimalAgent is essentially a wrapper over the Bedrock Covnerse API (with optional session management using DDB), making it a simple framework for quickly bootstrapping AWS-native agents. It currently lacks integration with observability tools like Langfuse, so for large-scale production deployments I encourage you to use another framework.

Core Concepts

Tools

Tools give your agent capabilities. Simply decorate functions with @tool:

@tool
def search_database(query: str, limit: int = 10) -> list:
    """Search the database for records matching the query."""
    # Your implementation here
    return [{"id": 1, "name": query}]

Session Management

Enable persistent conversations across multiple interactions:

# Create an agent with session support
agent = Agent(use_session_memory=True)

# Use a consistent session ID for the same conversation
response1 = agent.run("Find information about electric cars", session_id="user123")
response2 = agent.run("What about hybrid models?", session_id="user123")  # Remembers context

Reasoning Display

Control the visibility of the agent's thinking process:

# Colorized reasoning in the terminal is enabled by default
agent = Agent(tools=[get_weather])  # show_reasoning=True is the default

# Explicitly enable reasoning display
agent_with_display = Agent(
    tools=[get_weather],
    show_reasoning=True
)

# Hide reasoning output for production use
agent_without_display = Agent(
    tools=[get_weather],
    show_reasoning=False,
    log_level="WARNING"  # Only log warnings and errors
)

Reasoning Process

Access the agent's step-by-step thinking programmatically:

response, reasoning = agent.run("Calculate 25 * 4 + 10")

# Access reasoning data
print(f"Query: {reasoning.query}")
print(f"Steps: {reasoning.total_steps}")
for step in reasoning.steps:
    print(f"Step {step.step_number} thinking: {step.thinking}")

Documentation

For more detailed documentation, visit https://niklas-palm.github.io/minimalagent/

AWS Setup

MinimalAgent requires AWS credentials for accessing Amazon Bedrock and DynamoDB.

Option 1: AWS CLI Configuration (Recommended)

1. Install and configure the AWS CLI:

   aws configure
   

Option 2: Environment Variables

export AWS_ACCESS_KEY_ID=your_access_key_id
export AWS_SECRET_ACCESS_KEY=your_secret_access_key
export AWS_REGION=us-west-2

License

MIT