AgentFlow Client

A TypeScript/React client library for the AgentFlow multi-agent system API. Build conversational AI applications with streaming responses, tool execution, and dynamic state management.

✨ Features

• 🚀 Simple API - Clean, intuitive client for AgentFlow
• 💬 Streaming Support - Real-time streaming responses for chat UIs
• 🔧 Tool Execution - Automatic local tool execution with recursion handling
• 📊 State Management - Dynamic state schema with validation
• ⚛️ React Ready - Built for React applications with hooks and patterns
• 📘 TypeScript First - Full TypeScript support with comprehensive types
• 🎯 Zero Config - Works out of the box with sensible defaults

📦 Installation

npm install @10xscale/agentflow-client
# or
yarn add @10xscale/agentflow-client
# or
pnpm add @10xscale/agentflow-client

🚀 Quick Start

Basic Usage

import { AgentFlowClient, Message } from '@10xscale/agentflow-client';

// Initialize client
const client = new AgentFlowClient({
  baseUrl: 'http://localhost:8000',
  authToken: 'your-token', // optional
  debug: true              // optional
});

// Send a message and get response
const result = await client.invoke([
  Message.text_message('Hello, how can you help me?', 'user')
]);

console.log(result.messages); // Array of response messages

Streaming Chat

// Stream responses in real-time
const stream = client.stream([
  Message.text_message('Tell me a story', 'user')
]);

for await (const chunk of stream) {
  if (chunk.event === 'message') {
    console.log(chunk.message?.content);
  }
}

React Integration

import { useState } from 'react';
import { AgentFlowClient, Message } from '@10xscale/agentflow-client';

function ChatComponent() {
  const [messages, setMessages] = useState<Message[]>([]);
  const client = new AgentFlowClient({ baseUrl: 'http://localhost:8000' });

  const sendMessage = async (text: string) => {
    const userMsg = Message.text_message(text, 'user');
    setMessages(prev => [...prev, userMsg]);

    const result = await client.invoke([...messages, userMsg]);
    setMessages(result.messages);
  };

  return (
    <div>
      {messages.map((msg, i) => (
        <div key={i}>{msg.content}</div>
      ))}
    </div>
  );
}

Tool Registration

⚠️ Important: Remote tools (registered client-side) should only be used for browser-level APIs like localStorage, navigator.geolocation, etc. For most operations (database queries, external API calls, calculations), define your tools in the Python backend instead. See Tools Guide for details.

// Register custom tools for agent execution (ONLY for browser APIs)
client.registerTool({
  node: 'assistant',
  name: 'get_weather',
  description: 'Get current weather for a location',
  parameters: {
    type: 'object',
    properties: {
      location: { type: 'string' }
    },
    required: ['location']
  },
  handler: async ({ location }) => {
    // Your tool logic here
    return { temperature: 72, conditions: 'sunny' };
  }
});

// Tools execute automatically during invoke
const result = await client.invoke([
  Message.text_message('What is the weather in NYC?', 'user')
]);

📚 Documentation

Getting Started

• Getting Started Guide - Complete setup and first steps
• API Reference - Complete API documentation
• TypeScript Types - Type definitions and usage

Core Concepts

• Invoke API - Request/response pattern with tool execution
• Stream API - Real-time streaming responses
• State Schema - Dynamic state management and validation
• Tools Guide - Tool registration and execution ⚠️ Important: Remote vs Backend tools

React Integration

• React Integration Guide - Hooks and patterns for React
• React Examples - Complete component examples

Reference

• Quick References - Quick refs for stream and state schema APIs
• Troubleshooting - Common issues and solutions

🎯 Key APIs

invoke() - Batch Processing

Execute agent with automatic tool execution loop:

const result = await client.invoke(messages, {
  recursion_limit: 25,
  response_granularity: 'full'
});

stream() - Real-time Streaming

Stream responses as they're generated:

const stream = client.stream(messages);
for await (const chunk of stream) {
  // Process chunks in real-time
}

graphStateSchema() - Dynamic Schema

Get agent state schema for form generation and validation:

const schema = await client.graphStateSchema();
// Build forms, validate data, generate types

Tool Registration

Register local tools that agents can execute:

client.registerTool({
  node: 'node_name',
  name: 'tool_name',
  handler: async (args) => { /* ... */ }
});

💡 Examples

Check out the examples/ directory for complete working examples:

• invoke-example.ts - Basic invoke with tool execution
• stream-example.ts - Streaming responses
• state-schema-examples.ts - Form generation and validation
• react-chat-component.tsx - React chat UI
• react-form-builder.tsx - Dynamic form builder

🏗️ Architecture

┌─────────────────────┐
│   Your React App    │
└──────────┬──────────┘
           │
           │ AgentFlowClient
           ▼
┌─────────────────────┐
│  @10xscale/agentflow-client    │  ← This library
│  - Client           │
│  - Tools            │
│  - Messages         │
└──────────┬──────────┘
           │
           │ HTTP/HTTPS
           ▼
┌─────────────────────┐
│  AgentFlow Server   │  ← Your backend
│  (Multi-agent API)  │
└─────────────────────┘

🔧 Configuration

const client = new AgentFlowClient({
  baseUrl: string,           // Required: API base URL
  authToken?: string,        // Optional: Bearer token
  timeout?: number,          // Optional: Request timeout (default: 5min)
  debug?: boolean            // Optional: Enable debug logging
});

🧪 Testing

# Run all tests
npm test

# Run tests once
npm run test:run

# Build the library
npm run build

📝 TypeScript Support

Full TypeScript support with comprehensive type definitions:

import type {
  AgentFlowClient,
  Message,
  ToolRegistration,
  InvokeResult,
  StreamChunk,
  AgentState,
  AgentStateSchema
} from '@10xscale/agentflow-client';

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

• 📚 Documentation
• 🐛 Issue Tracker
• 💬 Discussions

🙏 Acknowledgments

Built for the AgentFlow multi-agent system framework.

Made with ❤️ for the AgentFlow community