Skip to main content

​
Overview

Handler’s TUI (Terminal User Interface) provides an interactive, Textual-based interface for communicating with A2A agents. The TUI offers real-time message streaming, task tracking, artifact viewing, and built-in authentication management.

​
Launching the TUI

1

Start the TUI

Launch Handler’s TUI using the default command:
handler
# or explicitly
handler tui
The TUI will start with a welcome message and display the main interface.
2

Understand the layout

The TUI is divided into four main panels:
  • Contact Panel (top-left): Agent URL input and connection
  • Agent Card Panel (bottom-left): Displays agent metadata and capabilities
  • Messages Panel (right-top): Shows conversation history, tasks, artifacts, and logs
  • Input Panel (bottom-right): Message input and send controls

​
Connecting to an Agent

1

Enter agent URL

In the Contact Panel, enter your agent’s base URL:
http://localhost:8000
Press the Connect button or hit Enter.
2

View agent card

Once connected, the Agent Card Panel displays:
  • Agent name and description
  • Protocol version
  • Capabilities (streaming, push notifications)
  • Available skills
  • Supported content types
The TUI fetches the agent card from {agent_url}/.well-known/a2a/agent.json.

​
Sending Messages

1

Type your message

In the Input Panel at the bottom, type your message in the text field.
2

Send the message

Press Enter or click the Send button. The message is sent with:
  • Your message text
  • Current context_id (automatically managed for conversation continuity)
  • Any configured authentication credentials
3

View the response

Agent responses appear in the Messages Panel. The TUI displays:
  • User messages (your input)
  • Agent messages (text responses)
  • Task updates (state changes)
  • Artifacts (structured outputs)
  • System messages (connection status, errors)

​
Working with Tasks

The TUI automatically tracks task state throughout the conversation: 
# Context and task IDs are managed automatically
if send_result.context_id:
    self.current_context_id = send_result.context_id

# Tasks are tracked in the UI
if send_result.task:
    messages_panel.update_task(send_result.task)
Tasks can be in various states:
  • working: Agent is processing
  • input-required: Waiting for user input
  • auth-required: Needs authentication
  • completed: Successfully finished
  • failed: Encountered an error
  • canceled: User or agent canceled

​
Viewing Artifacts

Artifacts are structured outputs from agents (code, data, files, etc.).
1

Switch to Artifacts tab

Click the Artifacts tab in the Messages Panel when artifacts are available.
2

Browse artifacts

Each artifact shows:
  • Artifact ID
  • Content type
  • Parts (text, code, data)
The TUI extracts and displays artifact content from task updates:
service.py:244-250
if send_result.task.artifacts:
    for artifact in send_result.task.artifacts:
        messages_panel.update_artifact(
            artifact,
            send_result.task_id or "",
            self.current_context_id or "",
        )

​
Using Authentication

For agents requiring authentication, the TUI provides built-in credential management.
1

Open authentication panel

In the Messages Panel, navigate to the authentication section (implementation in tui/components/auth.py).
2

Choose auth type

Select from:
  • None: No authentication
  • API Key: Custom header authentication
  • Bearer Token: OAuth-style token
3

Enter credentials

For API Key:
API Key: your-api-key-here
Header Name: X-API-Key (default)
For Bearer Token:
Bearer Token: your-bearer-token-here
Credentials are applied to subsequent requests:
app.py:214-216
credentials = messages_panel.get_auth_credentials()
if credentials:
    self._agent_service.set_credentials(credentials)
Credentials entered in the TUI are stored in memory only and cleared when the TUI exits. For persistent credentials, use session management.

​
Keyboard Shortcuts

The TUI provides several keyboard shortcuts for efficient navigation:
ShortcutAction
Ctrl+QQuit the TUI
/Open command palette
Ctrl+MMaximize focused panel
TabNavigate between panels
EnterSend message (when in input field)

​
Viewing Logs

The TUI includes a built-in log viewer for debugging:
1

Switch to Logs tab

Click the Logs tab in the Messages Panel.
2

Monitor activity

View real-time logs including:
  • Connection events
  • Message send/receive
  • HTTP requests
  • Error messages
The log handler is configured in app.py:100-104:
tui_log_handler = install_tui_log_handler(level=logging.DEBUG)
tui_log_handler.set_callback(self._on_log_line)

messages_panel = self.query_one("#messages-container", TabbedMessagesPanel)
messages_panel.load_logs(tui_log_handler.get_lines())

​
Web Mode

You can also run the TUI as a web application: 
handler tui --web
This serves the TUI in your browser, making it accessible remotely or for sharing.

​
Theming

Handler supports custom themes. Your theme preference is saved to ~/.handler/ and persists across sessions:
app.py:121-126
def watch_theme(self, new_theme: str) -> None:
    """Called when the app theme changes."""
    logger.debug("Theme changed to: %s", new_theme)
    save_theme(new_theme)
    agent_card_panel = self.query_one("#agent-card-container", AgentCardPanel)
    agent_card_panel.refresh_theme()

​
Tips and Best Practices

Context Continuity

The TUI automatically manages context_id for conversation continuity. Each new connection generates a fresh context.

Streaming Support

If the agent supports streaming, responses appear incrementally as they’re generated.

Panel Maximization

Use Ctrl+M to maximize the Messages or Agent Card panel for better visibility.

Error Handling

Connection errors and agent errors are displayed as system messages in the Messages Panel.

​
Next Steps

Authentication

Learn about bearer tokens and API key authentication

Sessions

Persist context and credentials across TUI sessions

CLI Reference

Complete CLI reference for TUI options