Streamlit A2A UI

A user-friendly chat interface for interacting with any A2A (Agent-to-Agent) protocol-compatible agent.

Overview

This Streamlit application provides a web-based chat interface for querying AI agents through the A2A protocol. It features:

• 💬 Interactive Chat Interface: Intuitive conversation UI with message history
• 🔄 Conversation Context: Maintains context throughout a conversation session
• 🆕 New Conversation: Start fresh conversations with a single click
• 📊 Real-time Updates: See AI Agent's reasoning/updates as it processes queries
• 🎨 Modern UI: Clean, responsive design built with Streamlit
• ⚙️ Flexible Configuration: Configure server URL via environment variables or UI
• 🐳 Docker Support: Easy containerization with provided Dockerfile

Prerequisites

• Python 3.10 or higher
• Running A2A-compatible agent server
• UV package manager (recommended) or pip

Project Structure

streamlit-a2a-ui/
├── src/
│   ├── a2a_client.py             # A2A client implementation
│   └── app.py                    # Streamlit UI application
├── pyproject.toml                # Project configuration & dependencies
├── Dockerfile                    # Docker build configuration
├── docker-compose.yml            # Docker Compose configuration
├── .env.example                  # Environment variables template
└── README.md                     # This file

Architecture

The application is structured with clear separation of concerns:

• src/a2a_client.py: Contains the A2AClient class that handles all JSON-RPC communication with A2A agents (streaming, polling, task management)
• src/app.py: Contains the Streamlit UI implementation, completely separated from the client logic

Installation

Using pip

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

Using UV

UV is a fast Python package manager that simplifies dependency management.

# Install UV if not already installed
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create virtual environment and install dependencies
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -r requirements.txt

Configuration

The Streamlit UI can be configured via:

1. Environment variables in .env file (copy from .env.example)
2. UI sidebar (if A2A_SERVER_URL is not set)

Environment Variables

# URL of your A2A server (Optional - can be set via UI)
# If not set, the UI will prompt you to enter it in the sidebar
A2A_SERVER_URL=http://localhost:10001

# Optional: Log level for debugging (DEBUG, INFO, WARNING, ERROR, CRITICAL)
LOG_LEVEL=INFO

# Optional: Polling configuration for task progress updates
POLL_INTERVAL=2        # Check for updates every 2 seconds
MAX_POLL_TIME=120      # Maximum wait time (2 minutes)

Defaults:

• A2A_SERVER_URL: Empty (prompted in UI)
• LOG_LEVEL: INFO
• POLL_INTERVAL: 2 seconds
• MAX_POLL_TIME: 120 seconds (2 minutes)

Usage

Starting the UI

Make sure your A2A-compatible agent server is running first, then start the Streamlit UI:

# From the project root
streamlit run src/app.py

The UI will open automatically in your default browser at http://localhost:8501.

Using the A2A Client Independently

The A2A client can be used independently of the Streamlit UI:

import sys
sys.path.insert(0, 'src')

from a2a_client import A2AClient

# Initialize the client
client = A2AClient("http://localhost:10001")

# Get agent information
agent_card = client.get_agent_card()
print(f"Connected to: {agent_card['name']}")

# Send a message (non-blocking)
response = client.send_message("Hello, agent!")

# Send a message with streaming
for event in client.send_message_stream("What can you do?"):
    print(event)

# Auto-select best method (streaming with fallback to polling)
result = client.send_message_auto("Help me with a task")
if result["mode"] == "streaming":
    for event in result["data"]:
        print(event)
else:
    print(result["data"])

# Close the client when done
client.close()

Connecting to an Agent

Option 1: Configure via Environment Variable

# Set in .env file
A2A_SERVER_URL=http://localhost:10001

# Then start the UI
streamlit run app.py

Option 2: Configure via UI

1. Start the Streamlit UI without setting A2A_SERVER_URL
2. Enter the server URL in the sidebar
3. Click "Connect"

Using the Chat Interface

1. View Agent Information: The sidebar shows the connected agent's details and capabilities
2. Ask Questions: Type your question in the chat input at the bottom
3. View Responses: AI Agent's responses appear in the chat with timestamps
4. Continue Conversation: All messages in the same session maintain conversation context
5. Start New Conversation: Click "🔄 New Conversation" in the sidebar to reset
6. Change Server: Click "Change Server" in the sidebar to connect to a different agent

Example Queries

The queries you can ask depend on your agent's capabilities. Common examples:

• "What can you help me with?"
• "Show me the available commands"
• "Help me with [your specific task]"

Features

Conversation Context Management

The UI automatically manages conversation context:

• Each chat session has a unique context_id
• All messages within a session share the same context
• The A2A server maintains conversation history
• Click "New Conversation" to start with a fresh context

Connection Status

The sidebar displays:

• Connection status to the A2A server
• Agent name and description
• Available skills and capabilities
• Current conversation context ID

Real-time Progress Updates

The UI displays live reasoning updates as the AI Agent processes your query:

• Streaming Support: Automatically uses streaming (SSE) if supported by the agent
• Polling Fallback: Falls back to polling mode if streaming is not available
• Reasoning Display: Shows AI Agent's thought process in real-time
• Progress Tracking: Displays elapsed time and current reasoning step
• Status Updates: New reasoning steps appear automatically as they become available
• Configurable Timeout: Maximum wait time of 120 seconds by default (configurable via MAX_POLL_TIME)

Example reasoning display:

🤔 AI Agent update (6s):
Analyzing your request...
Processing information...

This gives you visibility into what the AI Agent is doing while processing complex queries.

Message History

• All messages are stored in the session
• User messages show on the right with timestamps
• AI responses show on the left with timestamps
• Scroll through conversation history

Architecture

┌─────────────┐          ┌─────────────────┐            ┌───────────────────┐
│  Browser    │ ◄——————► │  Streamlit UI   │ ◄————————► │  A2A Server:      │
│  (User)     │   HTTP   │  (This App)     │  A2A       │  Any A2A          │
│             │          │                 │  JSON-RPC  │  Compatible Agent │
└─────────────┘          └─────────────────┘            └───────────────────┘
                                                       

How It Works

1. Connection: UI connects to A2A server and fetches agent card
2. User Input: User types a question in the chat input
3. A2A Request: UI sends JSON-RPC request with user message and context ID
4. Processing: A2A server processes the request through the agent
5. Response: UI displays AI Agent's answer in the chat (streaming or polling)
6. Context: Same context ID is used for follow-up questions

Troubleshooting

Cannot Connect to A2A Server

Error: "Failed to connect to [server URL]"

Solutions:

• Ensure the A2A agent server is running
• Verify the server URL is correct (check in sidebar or .env file)
• Test the server URL in your browser: http://your-server/.well-known/agent-card.json
• Check firewall settings and network connectivity
• Try using "Change Server" in the sidebar to reconnect

Port Already in Use

Error: "Address already in use"

Solution:

# Run Streamlit on a different port
streamlit run app.py --server.port 8502

Slow Responses

AI Agent queries can take variable time to complete depending on the task complexity. This is normal as the agent:

• Processes your request
• Retrieves necessary information
• Generates responses

The UI shows real-time progress updates with reasoning steps as the AI Agent processes your query. You'll see messages like:

• "⏳ AI Agent is analyzing your query..." (initial state)
• "🤔 AI Agent update: Processing..." (with progress updates)

The polling interval (default: 2 seconds) and maximum wait time (default: 120 seconds) can be configured via environment variables.

Session State Issues

If the UI behaves unexpectedly:

1. Click "🔄 New Conversation" to reset
2. Refresh the browser page
3. Restart the Streamlit app

Logging and Debugging

Enable detailed logging:

# In .env file
LOG_LEVEL=DEBUG

# Or set environment variable
export LOG_LEVEL=DEBUG
streamlit run app.py

Development

Key Components

Client Module (src/a2a_client.py)

• A2AClient: Main client class for A2A communication
  • get_agent_card(): Fetch agent capabilities
  • send_message(): Send message with polling
  • send_message_stream(): Send message with SSE streaming
  • send_message_auto(): Auto-select best method
  • get_task_status(): Poll task status

UI Module (src/app.py)

• main(): Main Streamlit application entry point
• initialize_session_state(): Setup session variables
• reset_conversation(): Create new conversation context
• parse_task_response(): Extract content from A2A responses
• display_agent_info(): Render agent information
• handle_streaming_mode(): Process streaming responses
• handle_polling_mode(): Process polling responses

Customization

You can customize the UI by editing .streamlit/config.toml:

[theme]
primaryColor = "#0066cc"      # Primary accent color
backgroundColor = "#ffffff"    # Main background
secondaryBackgroundColor = "#f0f2f6"  # Sidebar background
textColor = "#262730"         # Text color

Running with Docker

The project includes a Dockerfile that uses UV package manager for fast, reliable builds.

Build the Docker Image

docker build -t streamlit-a2a-ui .

Run the Container

Option 1: With environment file

docker run -p 8501:8501 --env-file .env streamlit-a2a-ui

Option 2: With environment variables

docker run -d --name streamlit-a2a-ui -p 8501:8501 \
  -e A2A_SERVER_URL=http://your-agent:10001 \
  -e LOG_LEVEL=INFO \
  streamlit-a2a-ui

Option 3: Configure via UI

# Run without A2A_SERVER_URL - configure in the UI sidebar
docker run streamlit-a2a-ui

Using Docker Compose

Create a docker-compose.yml:

version: '3.8'

services:
  streamlit-ui:
    build: .
    ports:
      - "8501:8501"
    environment:
      - A2A_SERVER_URL=http://a2a-agent:10001
      - LOG_LEVEL=INFO
    # Or use env_file:
    # env_file:
    #   - .env
    restart: unless-stopped

  # Add your A2A agent service here if needed
  # a2a-agent:
  #   image: your-a2a-agent:latest
  #   ports:
  #     - "10001:10001"

Then run:

docker-compose up -d

Access the UI at http://localhost:8501

Known Limitations

1. Streaming Support: The UI supports SSE streaming with automatic fallback to polling. However, streaming behavior depends on the A2A agent implementation
2. Session Persistence: Conversation history is lost on page refresh (stored in browser memory only)
3. Single User: Each browser session is independent
4. No Authentication: The UI does not implement authentication - add a reverse proxy for production use

Resources

• Streamlit Documentation
• A2A Protocol Specification

License

See LICENSE file for details.