ag-ui CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

For requests to add A2UI rendering to AG-UI applications or to scaffold an AG-UI + A2UI quickstart, use skills/ag-ui-a2ui-integration/SKILL.md.

Common Development Commands

TypeScript SDK (Main Development)

# Install dependencies (using pnpm)
pnpm install

# Build all packages
pnpm build

# Run development mode
pnpm dev

# Run linting
pnpm lint


# Run type checking
pnpm check-types

# Run tests
pnpm test

# Format code
pnpm format

# Clean build artifacts
pnpm clean

# Full clean build
pnpm build:clean

Python SDK

# Navigate to python-sdk directory
cd python-sdk

# Install dependencies (using poetry)
poetry install

# Run tests
python -m unittest discover tests

# Build distribution
poetry build

Running Specific Integration Tests

# For TypeScript packages/integrations
cd packages/<package-name>
pnpm test

# For running a single test file
cd packages/<package-name>
pnpm test -- path/to/test.spec.ts

High-Level Architecture

AG-UI is an event-based protocol that standardizes agent-user interactions. The codebase is organized as a monorepo with the following structure:

Core Protocol Architecture

• Event-Driven Communication: All agent-UI communication happens through typed events (BaseEvent and its subtypes)
• Transport Agnostic: Protocol supports SSE, WebSockets, HTTP binary, and custom transports
• Observable Pattern: Uses RxJS Observables for streaming agent responses

Key Abstractions

1. AbstractAgent: Base class that all agents must implement with a run(input: RunAgentInput) -> Observable<BaseEvent> method
2. HttpAgent: Standard HTTP client supporting SSE and binary protocols for connecting to agent endpoints
3. Event Types: Lifecycle events (RUN_STARTED/FINISHED), message events (TEXT_MESSAGE_), tool events (TOOL_CALL_), and state management events (STATE_SNAPSHOT/DELTA)