maos-agent 0.1.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
|
@@ -0,0 +1,147 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: maos-agent
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: The Observability & Resilience SDK for Maos AI Agents
|
|
5
|
+
Project-URL: Homepage, https://github.com/maosproject-dev/maos-agent
|
|
6
|
+
Project-URL: Bug Tracker, https://github.com/maosproject-dev/maos-agent/issues
|
|
7
|
+
Author-email: Maos AI <support@maosproject.io>
|
|
8
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
9
|
+
Classifier: Operating System :: OS Independent
|
|
10
|
+
Classifier: Programming Language :: Python :: 3
|
|
11
|
+
Classifier: Topic :: System :: Monitoring
|
|
12
|
+
Requires-Python: >=3.9
|
|
13
|
+
Requires-Dist: prometheus-client>=0.17.0
|
|
14
|
+
Description-Content-Type: text/markdown
|
|
15
|
+
|
|
16
|
+
**CTO here.**
|
|
17
|
+
|
|
18
|
+
Here is the `README.md`.
|
|
19
|
+
|
|
20
|
+
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).
|
|
21
|
+
|
|
22
|
+
I’ve added badges, a clear "Quick Start," and a section linking the metrics directly to the Grafana dashboard we just built.
|
|
23
|
+
|
|
24
|
+
---
|
|
25
|
+
|
|
26
|
+
# Maos Agent SDK
|
|
27
|
+
|
|
28
|
+
The official Python SDK for building resilient, observable AI Agents on the **Maos Platform**.
|
|
29
|
+
|
|
30
|
+
**`maos-agent`** provides the "Day 2" primitives required to run autonomous agents in production:
|
|
31
|
+
|
|
32
|
+
1. **Zero-Config Telemetry:** Automatically emits Prometheus metrics for every tool call, token used, and cognitive step.
|
|
33
|
+
2. **Spot Instance Resilience:** Handles `SIGTERM` signals from Kubernetes to allow graceful state checkpointing before node termination.
|
|
34
|
+
|
|
35
|
+
---
|
|
36
|
+
|
|
37
|
+
## Installation
|
|
38
|
+
|
|
39
|
+
```bash
|
|
40
|
+
pip install maos-agent
|
|
41
|
+
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
---
|
|
45
|
+
|
|
46
|
+
## Quick Start
|
|
47
|
+
|
|
48
|
+
Wrap your existing agent code with the Maos decorators to instantly get Grafana dashboards and Spot interruption protection.
|
|
49
|
+
|
|
50
|
+
```python
|
|
51
|
+
import time
|
|
52
|
+
import random
|
|
53
|
+
from maos_agent import MaosAgent, SpotInterruptionError
|
|
54
|
+
|
|
55
|
+
# 1. Initialize (Starts Prometheus server on port 8000)
|
|
56
|
+
agent = MaosAgent(service_name="financial-analyst", version="v1.2")
|
|
57
|
+
|
|
58
|
+
# 2. Define Tools (Auto-tracked for success/failure rates)
|
|
59
|
+
@agent.tool(name="stock_lookup")
|
|
60
|
+
def get_stock_price(ticker: str):
|
|
61
|
+
# Simulate work
|
|
62
|
+
if random.random() < 0.05:
|
|
63
|
+
raise ConnectionError("API Timeout") # Recorded as 'error' in Grafana
|
|
64
|
+
return 150.00
|
|
65
|
+
|
|
66
|
+
# 3. The Agent Loop
|
|
67
|
+
def run_job():
|
|
68
|
+
# Track duration, steps, and success automatically
|
|
69
|
+
with agent.task("analyze_portfolio") as task:
|
|
70
|
+
print("Starting analysis...")
|
|
71
|
+
|
|
72
|
+
for i in range(5):
|
|
73
|
+
# --- THE MAOS GUARANTEE ---
|
|
74
|
+
# Checks if K8s sent a termination signal (Spot reclaim).
|
|
75
|
+
# Raises SpotInterruptionError if node is draining.
|
|
76
|
+
agent.check_health()
|
|
77
|
+
|
|
78
|
+
# Record a "cognitive step" (thinking loop)
|
|
79
|
+
task.step()
|
|
80
|
+
|
|
81
|
+
price = get_stock_price("AAPL")
|
|
82
|
+
time.sleep(1)
|
|
83
|
+
|
|
84
|
+
if __name__ == "__main__":
|
|
85
|
+
try:
|
|
86
|
+
run_job()
|
|
87
|
+
except SpotInterruptionError:
|
|
88
|
+
print("🚨 SPOT RECLAIM DETECTED! SAVING STATE TO REDIS...")
|
|
89
|
+
# Checkpoint your agent's memory here so it can resume on a new node
|
|
90
|
+
exit(0)
|
|
91
|
+
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
---
|
|
95
|
+
|
|
96
|
+
## Key Features
|
|
97
|
+
|
|
98
|
+
### 1. Automatic Telemetry (The "Brain Scan")
|
|
99
|
+
|
|
100
|
+
Stop guessing if your agent is working. The SDK automatically exposes a `/metrics` endpoint on port `8000` (configurable) with standard Prometheus metrics:
|
|
101
|
+
|
|
102
|
+
| Metric Name | Type | Description |
|
|
103
|
+
| --- | --- | --- |
|
|
104
|
+
| `maos_agent_tool_calls_total` | Counter | Tracks tool usage + Success/Error rates. |
|
|
105
|
+
| `maos_agent_steps_per_goal` | Histogram | Detects "Loops of Death" (agents spinning in circles). |
|
|
106
|
+
| `maos_agent_token_usage_total` | Counter | Tracks cost (Input vs Output tokens). |
|
|
107
|
+
| `maos_agent_task_duration_seconds` | Histogram | End-to-end latency of jobs. |
|
|
108
|
+
|
|
109
|
+
*Compatible with the [Maos Agent Quality Dashboard](https://www.google.com/search?q=https://github.com/maos-ai/platform/tree/main/dashboards).*
|
|
110
|
+
|
|
111
|
+
### 2. Graceful Shutdown (The "Money Saver")
|
|
112
|
+
|
|
113
|
+
Maos runs agents on Spot Instances to save you 90% on compute. However, Spot nodes can disappear with a 2-minute warning.
|
|
114
|
+
|
|
115
|
+
The `agent.check_health()` method abstracts the complexity of Kubernetes signal handling.
|
|
116
|
+
|
|
117
|
+
* **Normal operation:** Returns immediately.
|
|
118
|
+
* **During Drain:** Raises `SpotInterruptionError`.
|
|
119
|
+
|
|
120
|
+
**Best Practice:** Call `check_health()` inside your main `while` loop or before every LLM call.
|
|
121
|
+
|
|
122
|
+
---
|
|
123
|
+
|
|
124
|
+
## Configuration
|
|
125
|
+
|
|
126
|
+
You can configure the agent via environment variables or constructor arguments.
|
|
127
|
+
|
|
128
|
+
| Environment Variable | Default | Description |
|
|
129
|
+
| --- | --- | --- |
|
|
130
|
+
| `MAOS_SERVICE_NAME` | `unknown-agent` | The name of your agent (for filtering in Grafana). |
|
|
131
|
+
| `MAOS_METRICS_PORT` | `8000` | Port to expose Prometheus metrics. |
|
|
132
|
+
| `MAOS_LOG_LEVEL` | `INFO` | Logging verbosity. |
|
|
133
|
+
|
|
134
|
+
---
|
|
135
|
+
|
|
136
|
+
## Contributing
|
|
137
|
+
|
|
138
|
+
We welcome contributions! Please see [CONTRIBUTING.md](https://www.google.com/search?q=CONTRIBUTING.md) for details.
|
|
139
|
+
|
|
140
|
+
1. Fork the repo.
|
|
141
|
+
2. Create a feature branch (`git checkout -b feature/langchain-integration`).
|
|
142
|
+
3. Commit your changes.
|
|
143
|
+
4. Open a Pull Request.
|
|
144
|
+
|
|
145
|
+
---
|
|
146
|
+
|
|
147
|
+
**Built by [Maos AI](https://www.google.com/search?q=https://maosproject.io) — The Control Plane for Autonomous Compute.**
|