Metadata-Version: 2.4
Name: agenttool-sdk
Version: 0.2.3
Summary: Python SDK for agenttool.dev — memory and tools for AI agents
License-Expression: MIT
Requires-Python: >=3.9
Requires-Dist: httpx>=0.27
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == 'dev'
Description-Content-Type: text/markdown

# agenttool-sdk · Python

> Persistent memory, verified actions, and tool access for AI agents — one API key.

[![PyPI](https://img.shields.io/pypi/v/agenttool-sdk)](https://pypi.org/project/agenttool-sdk/)
[![Python](https://img.shields.io/pypi/pyversions/agenttool-sdk)](https://pypi.org/project/agenttool-sdk/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![API Status](https://img.shields.io/badge/API-live-brightgreen)](https://api.agenttool.dev/health)

```bash
pip install agenttool-sdk
```

## What is this?

AgentTool gives AI agents the infrastructure they need to operate reliably:

| Service | What it does |
|---------|-------------|
| **agent-memory** | Persistent semantic memory — store facts, retrieve by similarity |
| **agent-tools** | Web search, page scraping, code execution |
| **agent-verify** | SHA-256 proof-of-work attestations with timestamps |
| **agent-economy** | Wallets, credits, agent-to-agent billing |

All four services, one API key, one SDK.

## Quick start (60 seconds)

**1. Get your API key** — create a free project at [app.agenttool.dev](https://app.agenttool.dev)

**2. Set your key:**
```bash
export AT_API_KEY=at_your_key_here
```

**3. Store and retrieve a memory:**
```python
from agenttool import AgentTool

at = AgentTool()  # reads AT_API_KEY from env

# Store a memory
memory = at.memory.store(
    content="The user prefers dark mode and concise responses",
    agent_id="my-assistant",
    tags=["preference", "ui"]
)

# Retrieve it later (semantic search)
results = at.memory.search("what does the user prefer?", limit=5)
for r in results:
    print(f"{r.score:.2f}  {r.content}")
```

## Usage

### Memory

```python
from agenttool import AgentTool

at = AgentTool(api_key="at_...")  # or use AT_API_KEY env var

# Store
mem = at.memory.store("User is based in London, timezone Europe/London")

# Search (semantic)
results = at.memory.search("where is the user?")

# Retrieve by ID
mem = at.memory.get(memory_id="mem_...")

# Delete
at.memory.delete(memory_id="mem_...")
```

### Tools

```python
# Web search
results = at.tools.search("latest papers on RAG", num_results=5)
for r in results:
    print(r.title, r.url)

# Scrape a page
page = at.tools.scrape("https://example.com")
print(page.text)

# Execute code
output = at.tools.execute("import math; print(math.pi)")
print(output.stdout)
```

### Verify

```python
# Create an attestation
proof = at.verify.create(
    action="task_completed",
    agent_id="my-agent",
    payload={"task": "data_analysis", "rows_processed": 1500}
)
print(proof.attestation_id, proof.hash)

# Verify an attestation
result = at.verify.check(attestation_id="att_...")
print(result.valid)  # True
```

### Economy

```python
# Create a wallet
wallet = at.economy.create_wallet(name="agent-wallet")

# Check balance
balance = at.economy.get_balance(wallet_id=wallet.id)

# Transfer credits to another agent
at.economy.transfer(
    from_wallet=wallet.id,
    to_wallet="wlt_...",
    amount=10,
    memo="payment for search service"
)
```

## Integration example — LangChain

```python
from langchain.tools import tool
from agenttool import AgentTool

at = AgentTool()

@tool
def remember(content: str) -> str:
    """Store a memory for later retrieval."""
    mem = at.memory.store(content, agent_id="langchain-agent")
    return f"Stored memory: {mem.id}"

@tool
def recall(query: str) -> str:
    """Search past memories by semantic similarity."""
    results = at.memory.search(query, limit=3)
    return "\n".join(r.content for r in results)
```

## Integration example — any agent loop

```python
from agenttool import AgentTool

at = AgentTool()

def agent_loop(user_message: str) -> str:
    # Recall relevant memories
    memories = at.memory.search(user_message, limit=5)
    context = "\n".join(m.content for m in memories)

    # Call your LLM with context
    response = your_llm(f"Context:\n{context}\n\nUser: {user_message}")

    # Store the exchange
    at.memory.store(f"User said: {user_message}\nAgent replied: {response}")

    return response
```

## Free tier

| Resource | Free | Seed ($29/mo) | Grow ($99/mo) |
|----------|------|----------------|----------------|
| Memory ops/day | 100 | 10,000 | 100,000 |
| Tool calls/day | 10 | 500 | 5,000 |
| Verifications/day | 5 | 100 | 1,000 |

[Upgrade at app.agenttool.dev/billing](https://app.agenttool.dev/billing)

## Configuration

```python
from agenttool import AgentTool

at = AgentTool(
    api_key="at_...",          # default: AT_API_KEY env var
    base_url="https://api.agenttool.dev",  # default
    timeout=30,                # seconds
)
```

## Links

- 🏠 [agenttool.dev](https://agenttool.dev)
- 📖 [docs.agenttool.dev](https://docs.agenttool.dev)
- 🎛️ [app.agenttool.dev](https://app.agenttool.dev) — dashboard + API key
- 📦 [PyPI](https://pypi.org/project/agenttool-sdk/)
- 🟦 [TypeScript SDK](https://github.com/cambridgetcg/agenttool-sdk-ts)

## License

MIT
