Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,19 @@ trace, study, receipt, API and database schema versions.

## [Unreleased]

### Documentation

- The README has an Install section covering the PyPI package, the npm
TypeScript SDK and standalone executables, an npm badge, and a JavaScript
tracing example verified against the published npm package. The
installation guide documents `npm install agentloop-profiler` instead of
saying npm publication is pending.
- The README integrations table lists the TypeScript SDK and the Codex and
Claude Code runners. The API, upgrade and installation guides cover the
npm package's client, upgrades and version check.
- The TypeScript SDK README says how to install the `agentloop` CLI that
analyzes its traces.

## [0.2.6] - 2026-11-19

### Added
Expand Down
67 changes: 59 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,13 +13,15 @@
<p align="center">
<a href="https://github.com/dipeshbabu/agentloop/actions/workflows/ci.yml"><img src="https://github.com/dipeshbabu/agentloop/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
<a href="https://pypi.org/project/agentloop-profiler/"><img src="https://img.shields.io/pypi/v/agentloop-profiler.svg?cacheSeconds=300" alt="PyPI"></a>
<a href="https://www.npmjs.com/package/agentloop-profiler"><img src="https://img.shields.io/npm/v/agentloop-profiler.svg?cacheSeconds=300" alt="npm"></a>
<a href="https://pepy.tech/projects/agentloop-profiler"><img src="https://static.pepy.tech/badge/agentloop-profiler/month" alt="Downloads/month"></a>
<a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.11%2B-3776AB.svg" alt="Python 3.11 or newer"></a>
<a href="https://github.com/dipeshbabu/agentloop/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue.svg" alt="License: Apache-2.0"></a>
</p>

<p align="center">
<a href="https://dipeshbabu.github.io/agentloop/">Documentation</a> ·
<a href="#install">Install</a> ·
<a href="#quickstart">Quickstart</a> ·
<a href="#guided-optimization">Improve an agent</a> ·
<a href="#record-your-own-run">Trace your code</a> ·
Expand All @@ -37,13 +39,24 @@ The core Python SDK and CLI work with JSON files. You can trace and analyze your
code without a hosted account or database. A dashboard, HTTP API, and shared
storage are available as optional components.

For Node.js and browser applications, the source checkout includes a
[TypeScript SDK](https://github.com/dipeshbabu/agentloop/blob/main/sdk/typescript/README.md) with native tracing and an API v1 client.
It has no runtime dependencies and installs with `npm install agentloop-profiler`.
## Install

AgentLoop is published as `agentloop-profiler` on PyPI and on npm.

| Install | For | Requires |
| --- | --- | --- |
| `python -m pip install agentloop-profiler` | Python SDK and the `agentloop` CLI, which analyzes traces, writes reports and runs the guided workflow | Python 3.11+ |
| `npm install agentloop-profiler` | [TypeScript SDK](https://github.com/dipeshbabu/agentloop/blob/main/sdk/typescript/README.md) for Node.js and browser code: native tracing and an API v1 client, with no runtime dependencies | Node.js 22+ |
| [Standalone executable](#standalone-cli) | The `agentloop` CLI without installing Python | Linux, macOS or Windows |

The two packages are versioned separately and share the trace format, so traces
recorded with the TypeScript SDK are analyzed with the `agentloop` CLI. See the
[installation guide](https://dipeshbabu.github.io/agentloop/installation/) for
virtual environments, optional extras and installing from source.

## Quickstart

Install with Python 3.11 or newer:
Install the Python package and record an example trace:

```bash
python -m pip install agentloop-profiler
Expand All @@ -54,9 +67,9 @@ agentloop analyze runs/agentloop_quickstart.json --html runs/report.html --json-
Open `runs/report.html` in your browser to inspect the timeline and findings.
`runs/analysis.json` contains the trace, metrics, diagnosis, and optimization plan.

The package name is `agentloop-profiler`; the Python import and CLI command are
both `agentloop`. `quickstart` creates a labeled synthetic trace and makes no model
API calls. It tests your installation, not your application's performance.
The Python import and CLI command are both `agentloop`. `quickstart` creates a
labeled synthetic trace and makes no model API calls. It tests your installation,
not your application's performance.

If your shell cannot find `agentloop`, activate the Python environment where you
installed it. Run `agentloop doctor` to check the installation and available adapters.
Expand Down Expand Up @@ -178,6 +191,40 @@ Saving `metadata["output"]` is an explicit choice in this example. Review the
inputs, outputs, errors, and metadata you retain before sharing real traces.
See [trace retention](https://dipeshbabu.github.io/agentloop/TRACE_RETENTION/) for capture controls.

### From TypeScript or JavaScript

After `npm install agentloop-profiler`, save this as `example_agent.mjs`:

```javascript
import { writeFile } from "node:fs/promises";
import { AgentTrace } from "agentloop-profiler";

const NOTES = {
tracing: "Record the steps in a workflow.",
optimization: "Investigate repeated or expensive work.",
};

const trace = new AgentTrace("research_agent", { metadata: { synthetic: true } });
const notes = [];
for (const topic of Object.keys(NOTES)) {
notes.push(await trace.tool("lookup_note", async () => NOTES[topic]));
}
trace.setOutput({ notes });
trace.finish();
await writeFile("research_agent_js.json", trace.toJSONString());
```

Run it and analyze the trace with the `agentloop` CLI:

```bash
node example_agent.mjs
agentloop analyze research_agent_js.json --html research_agent_js.html
```

The SDK also records model calls with provider token usage, retries and nested
spans, and can send traces to the HTTP API. See the
[TypeScript SDK guide](https://dipeshbabu.github.io/agentloop/reference/typescript/).

## Inspect findings

For a fixed task set, use the [guided workflow](#guided-optimization) to capture
Expand Down Expand Up @@ -307,6 +354,8 @@ gate. Run `agentloop COMMAND --help` to see its output options and thresholds.
| Source | Integration path |
| --- | --- |
| Custom Python agents and pipelines | Decorators, context managers, and [workflow annotations](https://dipeshbabu.github.io/agentloop/WORKFLOW_TRACING/). |
| TypeScript and JavaScript applications | `npm install agentloop-profiler`, then record model, tool and retry spans with the [TypeScript SDK](https://dipeshbabu.github.io/agentloop/reference/typescript/). |
| OpenAI Codex CLI and Claude Code | Built-in [Codex](https://dipeshbabu.github.io/agentloop/CODEX/) and [Claude Code](https://dipeshbabu.github.io/agentloop/CLAUDE_CODE/) runners for the guided workflow. |
| OpenAI SDK | Wrap a client or callable to capture calls, streams, and reported usage. |
| OpenAI Agents SDK | Attach an AgentLoop tracing processor. |
| LangGraph | Instrument the builder before adding nodes, then wrap the compiled runnable. |
Expand Down Expand Up @@ -372,7 +421,9 @@ uv run --frozen --all-extras streamlit run dashboard/app.py
Open Streamlit's printed URL and leave the sidebar's Project field set to `default`.
Use `store-trace` to load your own files. Storage uses SQLite by default and also
supports Postgres. The optional HTTP API serves project-scoped traces and reports
through `/v1` endpoints.
through `/v1` endpoints. Python applications use `agentloop.AgentLoopClient`;
TypeScript applications use `AgentLoopClient` from the npm package to upload
traces and read reports.

See [dashboard setup](https://dipeshbabu.github.io/agentloop/DASHBOARD/), [API versioning](https://dipeshbabu.github.io/agentloop/API_VERSIONING/),
and [production deployment](https://dipeshbabu.github.io/agentloop/PRODUCTION/) for configuration and authentication.
Expand Down
4 changes: 4 additions & 0 deletions docs/API_VERSIONING.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,10 @@ This sends `GET /v1/traces?page_size=20`. A mount such as
requires a server with v1 support; upgrade the server before upgrading clients.
Older clients can continue using the deprecated unversioned aliases during 0.x.

The TypeScript SDK's `AgentLoopClient`, installed with
`npm install agentloop-profiler`, uses the same `/v1` routes. See the
[TypeScript SDK guide](../sdk/typescript/README.md#use-the-api).

The Python client rejects redirects so project and admin keys cannot be forwarded
to another endpoint. Credentials are omitted from its representation, and HTTP
errors report the status without copying response bodies. Responses must be JSON
Expand Down
9 changes: 7 additions & 2 deletions docs/UPGRADING.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,10 @@
# Existing installations and stored data

The TypeScript SDK is published on npm as `agentloop-profiler` and is versioned
separately from the Python package. Upgrade it in your application with
`npm install agentloop-profiler@latest`. Native trace schema 1.1 and API v1,
not package versions, determine compatibility with the Python CLI and server.

Version `0.2.0` adds the guided `improve init`, `capture`, `start` and `finish`
workflow. Python 3.11 remains the minimum. Existing explicit `--tasks FILE`
commands and runner argv remain valid; `agentloop.toml` is optional data-only
Expand Down Expand Up @@ -27,8 +32,8 @@ Version `0.1.1` requires **Python 3.11 or newer** so supported installations can
use patched dependencies. It adds Hermes tracing and fixes CLI output collisions,
retry/error reporting, and API client credential handling. Native trace schema
1.1, API v1, and database migration IDs continue unchanged; retain existing data.
The TypeScript SDK remains a separately versioned source package, with npm
publication pending.
The TypeScript SDK was then a separately versioned source package; it has since
been published on npm.

Version `0.1.0` includes the evidence workflow: canonical findings and estimator
provenance, intervention records, paired studies, offline HTML reports, telemetry
Expand Down
3 changes: 3 additions & 0 deletions docs/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,9 @@ agentloop analyze runs/agentloop_quickstart.json --html runs/report.html
Open `runs/report.html` to inspect the timeline and findings.
This example runs locally with synthetic data.

For Node.js or browser code, `npm install agentloop-profiler` installs the
[TypeScript SDK](../sdk/typescript/README.md); analyze its traces with the same CLI.

</div>

## How AgentLoop fits your workflow
Expand Down
31 changes: 26 additions & 5 deletions docs/installation.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,14 @@ search:

# Installation

AgentLoop requires Python 3.11 or newer. The package is `agentloop-profiler` and
the Python import and CLI command are `agentloop`.
AgentLoop is published as `agentloop-profiler` on PyPI and on npm:

- the Python package (Python 3.11 or newer) provides the Python SDK and the
`agentloop` CLI, which analyzes traces, writes reports and runs the guided
workflow. The Python import and CLI command are `agentloop`;
- the npm package (Node.js 22 or newer) provides the
[TypeScript SDK](#typescript) for recording traces from Node.js and browser
code. Analyze its traces with the `agentloop` CLI.

## Published package

Expand Down Expand Up @@ -86,6 +92,21 @@ client compatibility and optional dependency updates.

## TypeScript

The separately versioned TypeScript SDK supports Node.js 22 and newer. Follow
its [source installation instructions](../sdk/typescript/README.md).
Its initial npm publication is pending.
The TypeScript SDK is versioned separately from the Python package and supports
Node.js 22 and newer. Install it in your application:

```bash
npm install agentloop-profiler
```

Upgrade an existing install with `npm install agentloop-profiler@latest` and check
the installed version with `npm ls agentloop-profiler`.

It is an ESM package with TypeScript declarations and no runtime dependencies.
Import from `agentloop-profiler` for tracing and `agentloop-profiler/client` for
the HTTP API client. Published versions are listed on
[npm](https://www.npmjs.com/package/agentloop-profiler), with provenance linking
each version to the workflow that built it.

The [TypeScript SDK guide](../sdk/typescript/README.md) covers tracing, model usage,
the API client and building the SDK from source.
6 changes: 5 additions & 1 deletion sdk/typescript/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -61,9 +61,13 @@ trace.finish();
await writeFile("trace.json", trace.toJSONString());
```

Analyze this local example with the Python CLI:
Analyze this local example with the `agentloop` CLI. It comes from the Python
package (Python 3.11 or newer), or use a
[standalone executable](https://github.com/dipeshbabu/agentloop#standalone-cli)
that needs no Python:

```bash
python -m pip install agentloop-profiler
agentloop analyze trace.json --html report.html
```

Expand Down
Loading