CTO here.

Here is the README.md.

It is written to be "Marketing-Engineering" aligned. It doesn't just say how to use it; it explains why a developer needs it (to stop their agents from dying silently on Spot instances).

I’ve added badges, a clear "Quick Start," and a section linking the metrics directly to the Grafana dashboard we just built.

Maos Agent SDK

The official Python SDK for building resilient, observable AI Agents on the Maos Platform.

maos-agent provides the "Day 2" primitives required to run autonomous agents in production:

1. Zero-Config Telemetry: Automatically emits Prometheus metrics for every tool call, token used, and cognitive step.
2. Spot Instance Resilience: Handles SIGTERM signals from Kubernetes to allow graceful state checkpointing before node termination.

Installation

pip install maos-agent

Quick Start

Wrap your existing agent code with the Maos decorators to instantly get Grafana dashboards and Spot interruption protection.

import time
import random
from maos_agent import MaosAgent, SpotInterruptionError

# 1. Initialize (Starts Prometheus server on port 8000)
agent = MaosAgent(service_name="financial-analyst", version="v1.2")

# 2. Define Tools (Auto-tracked for success/failure rates)
@agent.tool(name="stock_lookup")
def get_stock_price(ticker: str):
    # Simulate work
    if random.random() < 0.05:
        raise ConnectionError("API Timeout") # Recorded as 'error' in Grafana
    return 150.00

# 3. The Agent Loop
def run_job():
    # Track duration, steps, and success automatically
    with agent.task("analyze_portfolio") as task:
        print("Starting analysis...")
        
        for i in range(5):
            # --- THE MAOS GUARANTEE ---
            # Checks if K8s sent a termination signal (Spot reclaim).
            # Raises SpotInterruptionError if node is draining.
            agent.check_health() 
            
            # Record a "cognitive step" (thinking loop)
            task.step() 
            
            price = get_stock_price("AAPL")
            time.sleep(1)

if __name__ == "__main__":
    try:
        run_job()
    except SpotInterruptionError:
        print("🚨 SPOT RECLAIM DETECTED! SAVING STATE TO REDIS...")
        # Checkpoint your agent's memory here so it can resume on a new node
        exit(0)

Key Features

1. Automatic Telemetry (The "Brain Scan")

Stop guessing if your agent is working. The SDK automatically exposes a /metrics endpoint on port 8000 (configurable) with standard Prometheus metrics:

Compatible with the Maos Agent Quality Dashboard.

2. Graceful Shutdown (The "Money Saver")

Maos runs agents on Spot Instances to save you 90% on compute. However, Spot nodes can disappear with a 2-minute warning.

The agent.check_health() method abstracts the complexity of Kubernetes signal handling.

• Normal operation: Returns immediately.
• During Drain: Raises SpotInterruptionError.

Best Practice: Call check_health() inside your main while loop or before every LLM call.

Configuration

You can configure the agent via environment variables or constructor arguments.

Contributing

We welcome contributions! Please see CONTRIBUTING.md for details.

1. Fork the repo.
2. Create a feature branch (git checkout -b feature/langchain-integration).
3. Commit your changes.
4. Open a Pull Request.

Built by Maos AI — The Control Plane for Autonomous Compute.