Skip to content

README.md

Latest commit

 

History

History
220 lines (165 loc) · 5.89 KB

README.md

File metadata and controls

220 lines (165 loc) · 5.89 KB
Raw

Template Agent Client Examples

This directory contains client examples demonstrating how to interact with the Template Agent's simplified streaming API. These examples show best practices for handling real-time streaming, different event types, and error scenarios.

📁 Available Examples

1. Streamlit Demo App (streamlit_app.py)

A full-featured chat application built with Streamlit:

  • Real-time chat interface with message history
  • Token streaming visualization for responsive UX
  • Session management with thread and session persistence
  • Configuration panel for API settings and debugging
  • Export functionality for conversation data

Key Features:

  • Live token streaming with visual updates
  • Tool call visualization with expandable details
  • API health monitoring
  • Conversation export to JSON
  • Session state management

To Run:

# Install Streamlit if not already installed
pip install streamlit requests

# Run the app
streamlit run examples/streamlit_app.py

# Open http://localhost:8501 in your browser

2. Python Async Client (client_python.py)

A robust async Python client for server-to-server communication:

  • Async/await support using aiohttp
  • Streaming and non-streaming modes for different use cases
  • Comprehensive error handling with detailed error messages
  • Session management with automatic ID generation
  • Health checking for API availability

Key Features:

  • Generator-based streaming for memory efficiency
  • Automatic session ID generation
  • Built-in retry logic and timeout handling
  • Example conversation flows

To Run:

# Install dependencies
pip install aiohttp

# Run the example
python examples/client_python.py

Usage as Library:

from examples.client_python import TemplateAgentClient

client = TemplateAgentClient()

# Simple message
response, messages = await client.send_message("Hello!")

# Streaming chat
async for event in client.stream_chat("Hello!", "thread-123", "session-123", "user-123"):
    if event['type'] == 'token':
        print(event['content'], end='', flush=True)

🔗 API Reference

Request Format

All clients use the simplified request format:

{
  "message": "User's input message",
  "thread_id": "Conversation thread identifier",
  "session_id": "Session identifier",
  "user_id": "User identifier",
  "stream_tokens": true
}

Response Format

The API returns Server-Sent Events with this format:

{"type": "message", "content": {"type": "ai", "content": "Hello"}}
{"type": "token", "content": " world"}
{"type": "error", "content": {"message": "Error occurred", "recoverable": false}}
[DONE]

Event Types:

  • message - Complete messages (AI responses, tool calls, tool results)
  • token - Individual tokens for real-time streaming
  • error - Error messages with recovery information
  • [DONE] - Stream completion marker

🚀 Getting Started

Prerequisites

  1. Template Agent Server Running

    # Start the Template Agent server
cd template-agent
python -m uvicorn template_agent.src.main:app --reload --port 8081

  2. Install Client Dependencies

    # For Python examples
pip install aiohttp requests streamlit

# For TypeScript example
npm install # (if using in a Node.js project)

Quick Test

Test the API is working:

# Health check
curl http://localhost:8081/health

# Simple streaming test
curl -X POST 'http://localhost:8081/stream' \
  -H 'Content-Type: application/json' \
  -H 'Accept: text/event-stream' \
  -d '{
    "message": "Hello!",
    "thread_id": "test-123",
    "session_id": "test-123",
    "user_id": "test-user",
    "stream_tokens": true
  }'

🎯 Best Practices

1. Session Management

  • Use consistent thread_id for multi-turn conversations
  • Use session_id to group related threads
  • Generate UUIDs for unique identifiers

2. Error Handling

  • Always handle error events in streams
  • Check recoverable flag to determine retry logic
  • Implement timeout and connection error handling

3. Token Streaming

  • Set stream_tokens: true for real-time UX
  • Set stream_tokens: false for simpler message-only handling
  • Buffer tokens appropriately for UI updates

4. Performance

  • Use appropriate timeouts for your use case
  • Handle stream interruption gracefully
  • Consider connection pooling for high-volume usage

🔧 Enterprise Features

All examples preserve enterprise features from the original implementation:

  • SSO Authentication: Pass X-Token header for enterprise auth
  • Langfuse Tracing: Automatic tracing and analytics
  • PostgreSQL Persistence: Conversation history and checkpointing
  • Error Monitoring: Comprehensive error logging and recovery

📚 Additional Resources

🐛 Troubleshooting

Common Issues

Connection Refused

  • Ensure Template Agent server is running on http://localhost:8081
  • Check firewall settings and port availability

Authentication Errors

  • Verify SSO token is valid (if using enterprise features)
  • Check X-Token header format

Streaming Issues

  • Ensure Accept: text/event-stream header is set
  • Check for proxy/firewall interference with streaming
  • Verify timeout settings are appropriate

Token Streaming Not Working

  • Confirm stream_tokens: true in request
  • Check for buffering issues in HTTP clients
  • Verify WebSocket/EventSource compatibility

Debug Mode

Enable detailed logging in examples:

# Python examples
import logging
logging.basicConfig(level=logging.DEBUG)

# Streamlit
st.set_option('client.showErrorDetails', True)

For more help, check the main project documentation or create an issue in the repository.