@ag-ui/client (1.0.0)
Installation
@ag-ui:registry=npm install @ag-ui/client@1.0.0"@ag-ui/client": "1.0.0"About this package
@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
npm install @ag-ui/client
pnpm add @ag-ui/client
yarn add @ag-ui/client
Features
- 🔗 HTTP connectivity –
HttpAgentfor direct server connections with SSE/protobuf support - 🏗️ Custom agents –
AbstractAgentbase 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
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
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 - Full API reference:
docs/sdk/js/client
Contributing
Bug reports and pull requests are welcome! Please read our contributing guide 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.
Dependencies
Dependencies
| ID | Version |
|---|---|
| @ag-ui/core | 1.0.0 |
| @ag-ui/encoder | 1.0.0 |
| @ag-ui/proto | 1.0.0 |
| @types/uuid | ^10.0.0 |
| compare-versions | ^6.1.1 |
| fast-json-patch | ^3.1.1 |
| rxjs | 7.8.1 |
| untruncate-json | ^0.0.1 |
| uuid | ^11.1.0 |
| zod | ^3.25.76 |
Development Dependencies
| ID | Version |
|---|---|
| @arethetypeswrong/cli | ^0.17.4 |
| @copilotkit/aimock | 1.37.4 |
| @types/node | ^20.11.19 |
| @vitest/coverage-istanbul | ^4.0.18 |
| eslint | ^9.37.0 |
| publint | ^0.3.12 |
| tsdown | ^0.20.1 |
| typescript | ^5.3.3 |
| vitest | ^4.0.18 |