Skip to content

Mamba Agents

A simple, extensible AI Agent framework built on pydantic-ai.

Installation

uv add mamba-agents

pip install mamba-agents

Quick Start

from mamba_agents import Agent, AgentSettings

# Load settings from env vars, .env, ~/mamba.env, config.toml
settings = AgentSettings()

# Create agent using settings
agent = Agent(settings=settings)

# Run the agent - context and usage are tracked automatically
result = await agent.run("What files are in the current directory?")
print(result.output)

# Check usage and cost
print(agent.get_usage())  # TokenUsage(prompt_tokens=..., request_count=1)
print(agent.get_cost())   # Cost in USD

Features

  • Agent Basics

    Thin wrapper around pydantic-ai with tool-calling support and automatic context management.

    Learn more

  • Built-in Tools

    Filesystem, glob, grep, and bash operations with security controls.

    Explore tools

  • MCP Integration

    Connect to Model Context Protocol servers (stdio and SSE transports).

    Setup MCP

  • Token Tracking

    Track usage with tiktoken, estimate costs automatically.

    Track usage

  • Message Analytics

    Query, filter, export, and visualize conversation history with rich formatting.

    Message analytics

  • Context Compaction

    5 strategies to manage long conversations without losing important context.

    Manage context

  • Workflows

    Orchestration patterns for multi-step execution (ReAct, Plan-Execute, etc.).

    Build workflows

  • Model Backends

    OpenAI-compatible adapter for Ollama, vLLM, LM Studio.

    Use local models

  • Observability

    Structured logging, tracing, and OpenTelemetry hooks.

    Add observability

Choose Your Path

  • New to Mamba Agents?

    Get up and running in under 5 minutes with the quick start guide.

    Quick Start

  • Want to use local models?

    Set up Ollama, vLLM, or LM Studio for offline inference.

    Local LLM Setup

  • Building a code assistant?

    Step-by-step tutorial for building an AI coding assistant.

    Code Assistant Tutorial

  • Need multi-step workflows?

    Learn the ReAct pattern for complex reasoning tasks.

    ReAct Workflow

Quick Reference

Use Case Import
Basic agent from mamba_agents import Agent
With settings from mamba_agents import Agent, AgentSettings
Built-in tools from mamba_agents.tools import read_file, run_bash, glob_search
ReAct workflow from mamba_agents.workflows import ReActWorkflow, ReActConfig
Token tracking from mamba_agents.tokens import TokenCounter, CostEstimator
Message analytics from mamba_agents import MessageQuery, print_stats
MCP servers from mamba_agents.mcp import MCPClientManager, MCPServerConfig

Explore the Docs

  • Getting Started

    Install the package and configure your environment.

    Get started

  • User Guide

    Learn how to use all the features of Mamba Agents.

    User Guide

  • Tutorials

    Step-by-step guides for common use cases.

    Tutorials

  • Concepts

    Understand the architecture and design patterns.

    Concepts

  • API Reference

    Complete reference for all classes and functions.

    API Reference