Metadata-Version: 2.4
Name: agentlasso
Version: 0.3.0
Summary: Send your AI agent's production traces to AgentLasso: continuous behavioral coverage for AI agents.
Author-email: AgentLasso <hello@agentlasso.dev>
License-Expression: Apache-2.0
Project-URL: Homepage, https://agentlasso.dev
Project-URL: Documentation, https://agentlasso.dev/docs/send-traces
Project-URL: Source, https://github.com/agentlassohq/agentlasso/tree/main/sdk/python
Keywords: ai-agents,llm,evals,observability,telemetry,testing
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Testing
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# agentlasso

Send your AI agent's production traces to [AgentLasso](https://agentlasso.dev): it learns what your agent actually does, shows what you're not testing, and turns real behavior into golden tests that run in CI.

No dependencies: standard library only. Python 3.9+.

```sh
pip install agentlasso
```

## Send a trace

Set your project's API key (AgentLasso → **Settings**):

```sh
export AGENTLASSO_API_KEY="<your-project-api-key>"
```

Then, wherever your agent finishes handling a request:

```python
import agentlasso

agentlasso.send_trace(
    user_input="I want my money back for order 44182",
    agent_output="Refund of $89.00 issued to your card, 3-5 business days.",
    tool_calls=[
        {"name": "orders.lookup", "arguments": {"order_id": "44182"}, "latency_ms": 210},
        {"name": "stripe.refund", "arguments": {"charge_id": "ch_1P9", "amount": 8900}},
    ],
    session_id="conv_8fa21",
    model="claude-sonnet-5-5",
    background=True,  # don't make the user wait
)
```

One call per request your agent handled. Send `tool_calls` in the order the agent called them: trajectory checks, risk, money at stake and coverage are all built on them. `arguments` can be a dict or a JSON string (as OpenAI-style tool calls carry them).

| Argument                        | Meaning                                                                                  |
| ------------------------------- | ---------------------------------------------------------------------------------------- |
| `user_input`                    | What the user asked. Required.                                                           |
| `agent_output`                  | The agent's final reply. Needed for content checks and AI judge checks.                  |
| `tool_calls`                    | The tools the agent called, in order: `name`, optional `arguments` and `latency_ms`.     |
| `session_id`                    | Groups the turns of one conversation. A random ID is used if omitted.                    |
| `model`                         | The model that produced the reply.                                                       |
| `input_tokens`, `output_tokens` | Token usage.                                                                             |
| `timestamp`                     | When it happened (a `datetime`, ISO 8601 string or Unix time). Only for importing history. |
| `outcome`                       | Optional: `"resolved"`, `"escalated"` or `"failed"`. When given, it decides whether the request counts as a success. |
| `background`                    | `True`: return immediately and send from a background thread (failures are logged, never raised). |

## Import history

Bring in traffic your agent already handled, 500 traces per request, each kept on the day it happened (traces older than 90 days are skipped):

```python
import agentlasso

rows = [
    {"user_input": "Where is order 44907?", "tool_calls": [{"name": "shippo.track"}], "timestamp": "2026-09-28T14:05:00Z"},
    # ...
]
totals = agentlasso.send_traces(rows)  # {"sent": ..., "accepted": ..., "skipped_too_old": ..., "requests": ...}
```

Every row is checked before anything is sent, so a bad one raises (naming its index) instead of leaving half an import. AgentLasso doesn't recognize traces it already has, so import each period once (for example, last week's traces every Monday) to avoid counting them twice.

From a file (JSON Lines, a JSON array, or `{"traces": [...]}`):

```sh
agentlasso import traces.jsonl              # or: python -m agentlasso import traces.jsonl
agentlasso import traces.jsonl --dry-run    # check the file, send nothing
```

## Background sending

With `background=True`, `send_trace` returns at once and a failure is logged to the `agentlasso` logger instead of raised, so a trace can never break your agent's reply. A normal Python exit waits for pending sends; in a short-lived process (a script, a serverless function), call `agentlasso.flush()` before returning.

Without it, `send_trace` waits and returns AgentLasso's response (`{"accepted": 1, "traceIds": [...], ...}`), or raises `agentlasso.AgentLassoError` (with `.status`, the HTTP status code).

## Configuration

```python
from agentlasso import Client

client = Client(
    api_key="...",                                   # default: AGENTLASSO_API_KEY
    base_url="https://agentlasso.example.com/api/v1",  # self-hosted; default: AGENTLASSO_BASE_URL, then agentlasso.dev
    timeout=10.0,
)
client.send_trace(user_input="...", agent_output="...")
```

Already running OpenTelemetry? You don't need this package: point your OTLP/HTTP exporter at the same endpoint. See [Send traces](https://agentlasso.dev/docs/send-traces).

## Links

- [Developer guide](https://agentlasso.dev/docs)
- [API reference](https://agentlasso.dev/docs/api-reference)
- [Source](https://github.com/agentlassohq/agentlasso/tree/main/sdk/python)

Apache-2.0
