Metadata-Version: 2.4
Name: agentlint-trace
Version: 0.1.0a2
Summary: A CI linter for AI agent execution traces.
Project-URL: Homepage, https://github.com/DarrelFW321/AgentLint
Project-URL: Documentation, https://github.com/DarrelFW321/AgentLint/blob/main/Documents/user-guide.md
Project-URL: Issues, https://github.com/DarrelFW321/AgentLint/issues
Project-URL: Repository, https://github.com/DarrelFW321/AgentLint.git
Author: AgentLint contributors
License-Expression: MIT
License-File: LICENSE
Keywords: agents,ai,ci,lint,policy,traces
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.12
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Provides-Extra: openai-agents
Requires-Dist: openai-agents<0.19,>=0.18; extra == 'openai-agents'
Provides-Extra: otel-demo
Requires-Dist: opentelemetry-sdk>=1.0; extra == 'otel-demo'
Provides-Extra: release
Requires-Dist: build>=1.2; extra == 'release'
Requires-Dist: twine>=6.0; extra == 'release'
Description-Content-Type: text/markdown

# AgentLint

[![CI](https://github.com/DarrelFW321/AgentLint/actions/workflows/ci.yml/badge.svg)](https://github.com/DarrelFW321/AgentLint/actions/workflows/ci.yml)
[![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org/downloads/)
[![PyPI](https://img.shields.io/pypi/v/agentlint-trace.svg)](https://pypi.org/project/agentlint-trace/)

AgentLint checks recorded agent runs for unsafe tool use, missing approvals,
sensitive-data flows, and unsupported claims.

## Integrations

| Integration | Workflow |
| --- | --- |
| OpenAI Agents SDK | Automatic pytest capture or `instrument()` in any Python runner |
| OpenTelemetry | Import existing OTLP-style JSON |

## Install

```bash
python -m pip install "agentlint-trace[openai-agents]==0.1.0a2"
```

AgentLint requires Python 3.12 or newer.

## Define a policy

Create `agentlint.yaml`:

```yaml
version: 1
policy_id: customer_support

tools:
  lookup_status:
    permission: allowed
    approval: not_required

  issue_refund:
    permission: allowed
    approval: required

rules:
  unknown_tool: error
  denied_tool_call: error
  missing_approval: error
```

## Run

Pytest is optional. Choose the workflow that fits the project.

### Pytest

```bash
pytest --agentlint --agentlint-policy agentlint.yaml
```

The command runs the tests, captures their agent traces, and checks the saved run.
Artifacts are written to `.agentlint/runs/`.

```bash
agentlint check-run .agentlint/runs/latest.json
```

Use a [test marker or routing file](https://github.com/DarrelFW321/AgentLint/blob/main/Documents/user-guide.md#policy-selection) when
tests require different policies.

### Any Python runner

```python
from agentlint.integrations.openai_agents import instrument

session = instrument(".agentlint/openai-agents")

# Run the agent.

snapshot_paths = session.close()
```

Check the capture directory:

```bash
agentlint check-capture .agentlint/openai-agents --policy agentlint.yaml
```

`check-capture` also accepts one JSON file and detects OpenAI Agents, OpenTelemetry,
and native AgentLint formats.

## Sample output

```text
AgentLint Report
traces: 0 passed, 1 failed, 0 not verifiable, 0 invalid
diagnostics: 1 error, 0 warning, 0 info

error[DENIED_TOOL_CALL]: tool call "evt_delete_account" uses tool
"delete_account" denied by trace policy
  related events: evt_delete_account
  remediation: Remove the call or update the trace policy when this tool
  should be permitted.
```

## Documentation

- [User guide](https://github.com/DarrelFW321/AgentLint/blob/main/Documents/user-guide.md)
- [Examples](https://github.com/DarrelFW321/AgentLint/tree/main/examples)
- [OpenTelemetry compatibility](https://github.com/DarrelFW321/AgentLint/blob/main/Documents/user-guide.md#opentelemetry-compatibility)

## License

[MIT](https://github.com/DarrelFW321/AgentLint/blob/main/LICENSE)
