Skip to content

AgentFlow Client - Documentation

Welcome to the AgentFlow Client documentation! This guide will help you integrate the AgentFlow multi-agent API into your applications.

Document Description
Getting Started Complete setup guide (15 min)
API Reference All methods and types
React Integration ⭐ Hooks, patterns, best practices
React Examples ⭐ Complete component examples
Tools Guide Tool registration and execution
Troubleshooting Common issues and solutions

📖 What is AgentFlow Client?

AgentFlow Client is a TypeScript client library that connects your React applications to the AgentFlow multi-agent system. It provides:

  • ✅ Simple API Client - Clean interface to AgentFlow backend
  • ✅ Streaming Support - Real-time responses for chat interfaces
  • ✅ Tool Execution - Automatic local tool handling
  • ✅ State Management - Dynamic schema-based state handling
  • ✅ React-Ready - Built specifically for React applications
  • ✅ TypeScript - Full type safety and IntelliSense support

🚨 CRITICAL: Remote Tools vs Backend Tools

Before you start: Understanding tool types is essential for proper AgentFlow usage.

🔴 Remote Tools (Client-Side - LIMITED USE)

  • WHEN TO USE: Only for browser-level APIs
  • navigator.geolocation (GPS/location)
  • localStorage/sessionStorage (client-side storage)
  • DOM manipulation and access
  • WebRTC, camera/microphone access
  • File uploads from user's device
  • WHEN NOT TO USE: Database queries, external APIs, calculations, file operations
  • WHY LIMITED: Runs in browser, less secure, no server access

✅ Backend Tools (Server-Side - PREFERRED)

  • WHEN TO USE: For most operations
  • Database queries and operations
  • External API calls (weather, payments, etc.)
  • Mathematical calculations
  • File system operations
  • Business logic and data processing
  • WHY PREFERRED: More secure, efficient, scalable, full server access

💡 Rule of Thumb: If your tool needs server-side resources or external APIs, define it as a backend tool in your Python AgentFlow library instead of using remote tools.

🎓 Learning Path

👶 Beginner (Start Here)

  1. Getting Started - Install and make your first API call
  2. API Reference - Learn core methods: ping(), invoke(), stream()
  3. React Examples - See simple chat component example

🧑‍💻 Intermediate

  1. Invoke API Guide - Deep dive into request/response pattern
  2. Stream API Guide - Learn real-time streaming
  3. Tools Guide - Register and execute custom tools
  4. React Integration - Custom hooks and patterns

🚀 Advanced

  1. State Schema Guide - Dynamic forms and validation
  2. TypeScript Types - Advanced type usage
  3. React Examples - Complex workflows and multi-step UIs

📚 Core Documentation

Essential Guides

Getting Started

Complete setup guide to get you up and running in 15 minutes. Covers: - Installation - Basic configuration - First API call - Simple examples

API Reference

Comprehensive reference for all client methods: - AgentFlowClient configuration - invoke() - Batch processing with tools - stream() - Real-time streaming - graphStateSchema() - Get state schema - threadState(), updateThreadState(), clearThreadState() - Tool registration API - Message helpers

React Integration ⭐

Essential for React developers! Learn how to: - Set up AgentFlowClient in React - Use context providers - Create custom hooks (useInvoke, useStream, useStateSchema) - Manage loading and error states - Best practices for React apps

React Examples ⭐

Complete working examples including: - Simple chat component - Streaming chat with real-time updates - Dynamic form builder from schema - Agent with custom tools - Multi-step workflows - Thread management UI

API Deep Dives

Invoke API - Comprehensive Guide

Detailed documentation for the invoke() method: - Request/response patterns - Tool execution loop - Recursion handling - Response granularity - Error handling - Complete examples

Quick Reference: Invoke Quick Start

Stream API - Comprehensive Guide

Everything about real-time streaming: - Streaming architecture - Event types and handling - React integration patterns - Memory efficiency - Error handling - Performance tips

Quick Reference: Stream Quick Reference

State Schema API - Guide

Working with dynamic agent state: - Schema structure - Building dynamic forms - Data validation - Type generation - Dynamic fields

Quick Reference: State Schema Quick Reference

Advanced Topics

Tools Guide

Master tool registration and execution: - What are tools? - 🔴 REMOTE TOOLS vs BACKEND TOOLS ⚠️ CRITICAL DISTINCTION - Tool registration patterns - Handler implementation - OpenAI-style parameters - Error handling - Testing tools - Common patterns (weather, calculator, API calls)

🚨 REMOTE TOOLS (Client-Side): - ✅ USE ONLY FOR: Browser APIs (localStorage, navigator.geolocation, DOM manipulation, WebRTC) - ❌ DO NOT USE FOR: Database queries, external API calls, calculations, file operations - INSTEAD: Define these as backend tools in your Python AgentFlow library

✅ BACKEND TOOLS (Server-Side - PREFERRED): - Database operations, API calls, calculations, file system access - More secure, efficient, and scalable - Full access to your server infrastructure

TypeScript Types

Advanced TypeScript usage: - Type imports - Core interfaces - Type guards - Custom extensions - Type-safe tool handlers - Schema-based type inference

Troubleshooting

Solutions to common issues: - Installation problems - Connection errors - Timeout issues - Authentication failures - Stream disconnections - TypeScript errors - React integration issues

🔍 Find What You Need

I want to...

...get started quickly → Getting Started Guide

...build a chat interface → React Examples - Chat Component

...use streaming responses → Stream API Guide or Stream Quick Reference

...register custom tools → Tools Guide 🚨 REMOTE TOOLS: Only for browser APIs (geolocation, localStorage, DOM) ❌ BACKEND TOOLS: Preferred for everything else (APIs, databases, calculations)

...build dynamic forms → State Schema Guide or React Examples - Form Builder

...integrate with React → React Integration Guide

...understand all available methods → API Reference

...solve an issue → Troubleshooting Guide

...see complete examples → React Examples or /examples folder

📦 Installation

npm install @10xscale/agentflow-client

🚀 30-Second Example

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

const client = new AgentFlowClient({
  baseUrl: 'http://localhost:8000'
});

const result = await client.invoke([
  Message.text_message('Hello!', 'user')
]);

console.log(result.messages);