# @ag-ui/client

> Client SDK for connecting to **Agent-User Interaction (AG-UI) Protocol** servers.

Latest version **1.0.2** (published 2026-10-05) · MIT license · 0 weekly downloads

## Install

```sh
npm install @ag-ui/client
pnpm add @ag-ui/client
yarn add @ag-ui/client
bun add @ag-ui/client
```

## Health

**Score 80/100 (A)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score; popular repo.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 1.0.2 |
| Published | 2026-10-05 |
| First published | 2025-04-30 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 10 |
| Unpacked size | 1.1 MB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 16308 |
| Author | Markus Ecker |
| Maintainers | _mme, copilotkit |

## Links

- npm: https://www.npmjs.com/package/@ag-ui/client
- Repository: https://github.com/ag-ui-protocol/ag-ui
- Homepage: https://github.com/ag-ui-protocol/ag-ui#readme
- Issues: https://github.com/ag-ui-protocol/ag-ui/issues
- npm.io page: https://npm.io/package/@ag-ui/client

## Dependencies (10)

- [zod](https://npm.io/package/zod.md) ^3.25.76
- [rxjs](https://npm.io/package/rxjs.md) 7.8.1
- [uuid](https://npm.io/package/uuid.md) ^11.1.0
- [@ag-ui/core](https://npm.io/package/@ag-ui/core.md) 1.0.2
- [@types/uuid](https://npm.io/package/@types/uuid.md) ^10.0.0
- [@ag-ui/proto](https://npm.io/package/@ag-ui/proto.md) 1.0.2
- [@ag-ui/encoder](https://npm.io/package/@ag-ui/encoder.md) 1.0.2
- [fast-json-patch](https://npm.io/package/fast-json-patch.md) ^3.1.1
- [untruncate-json](https://npm.io/package/untruncate-json.md) ^0.0.1
- [compare-versions](https://npm.io/package/compare-versions.md) ^6.1.1

## Recent versions

- 1.0.2 (latest) — 2026-10-05
- 1.0.0-canary.1789569879.0 (canary) — 2026-09-16
- 0.0.50-alpha.0 (alpha) — 2026-04-02
- 1.0.1 — 2026-09-29
- 1.0.0 — 2026-09-17
- 0.0.59 — 2026-08-27
- 0.0.59-canary.1787220377.0 — 2026-08-20
- 0.0.58 — 2026-08-14
- 0.0.59-canary.1786716392.0 — 2026-08-14
- 0.0.59-canary.1786549251.0 — 2026-08-12
- 0.0.59-canary.1785518626.0 — 2026-07-31
- 0.1.1-canary.beta.0 — 2026-07-30
- 0.0.58-canary.beta.0 — 2026-07-28
- 0.0.59-canary.1784325892.0 — 2026-07-17
- 0.0.57 — 2026-06-12
- … 63 more at https://npm.io/package/@ag-ui/client/versions

## README

# @ag-ui/client

Client SDK for connecting to **Agent-User Interaction (AG-UI) Protocol** servers.

`@ag-ui/client` provides agent implementations that handle the full lifecycle of AG-UI communication: connecting to servers, processing streaming events, managing state mutations, and providing reactive subscriber hooks.

## Installation

```bash
npm install @ag-ui/client
pnpm add @ag-ui/client
yarn add @ag-ui/client
```

## Features

- 🔗 **HTTP connectivity** – `HttpAgent` for direct server connections with SSE/protobuf support
- 🏗️ **Custom agents** – `AbstractAgent` base class for building your own transport layer
- 📡 **Event streaming** – Full AG-UI event processing with validation and transformation
- 🔄 **State management** – Automatic message/state tracking with reactive updates
- 🪝 **Subscriber system** – Middleware-style hooks for logging, persistence, and custom logic
- 🎯 **Middleware support** – Transform and filter events with function or class-based middleware

## Quick example

```ts
import { HttpAgent } from "@ag-ui/client";

const agent = new HttpAgent({
  url: "https://api.example.com/agent",
  headers: { Authorization: "Bearer token" },
});

const result = await agent.runAgent({
  messages: [{ role: "user", content: "Hello!" }],
});

console.log(result.newMessages);
```

## Using Middleware

```ts
import { HttpAgent, FilterToolCallsMiddleware } from "@ag-ui/client";

const agent = new HttpAgent({
  url: "https://api.example.com/agent",
});

// Add middleware to transform or filter events
agent.use(
  // Function middleware for logging
  (input, next) => {
    console.log("Starting run:", input.runId);
    return next.run(input);
  },

  // Class middleware for filtering tool calls
  new FilterToolCallsMiddleware({
    allowedToolCalls: ["search", "calculate"]
  })
);

await agent.runAgent();
```

## Documentation

- Concepts & architecture: [`docs/concepts`](https://docs.ag-ui.com/concepts/architecture)
- Full API reference: [`docs/sdk/js/client`](https://docs.ag-ui.com/sdk/js/client/overview)

## Contributing

Bug reports and pull requests are welcome! Please read our [contributing guide](https://docs.ag-ui.com/development/contributing) first.

## License

MIT © 2025 AG-UI Protocol Contributors

## Activity snapshots

`MESSAGES_SNAPSHOT.metadata["@ag-ui/client"].authoritativeActivityTypes`
controls which activity types the snapshot replaces. An array owns those types;
`[]` owns none, and `null` owns all types, even for an empty snapshot. Without
a declaration, the existing rule applies: a snapshot containing any activity
replaces all activities, while a transcript-only snapshot preserves them. A missing
namespace or missing field uses this legacy rule. An invalid namespace or field
owns no types, including arrays containing non-string entries.

Authority controls deletion of omitted activity messages. A matching message ID
always updates in place, even for a type outside the declared scope. Existing
message positions are preserved and new IDs are appended in snapshot order.
This convention does not reconcile changed IDs or reposition restored activities.

History projectors must preserve full authority and extend explicit scopes with
the types they reconstruct. `withAuthoritativeActivityTypes` implements this
rule; call it on the incoming snapshot before replacing its messages.

---
_Source: https://npm.io/package/@ag-ui/client · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._