Agent Workshop

A TUI-based agentic chat application built with Textual.

Workshop

This repository ships with base functionality only — a simple echo agent and a debug panel. To build the full agentic experience (LLM integration, conversation history, tools, and an agentic loop), follow the steps in workshop_steps.md one at a time.

HTTP display (required for later steps)

The text display tool (introduced in step 4) depends on http-display, a separate macOS app that shows header and body text controlled via HTTP.

Before starting the workshop:

1. Clone and set up http-display following the instructions in that repository's README.
2. Start the HTTP display app and keep it running (by default it listens on http://localhost:8080).
3. Then proceed with the workshop steps in workshop_steps.md.

The agent workshop connects to the display at http://localhost:8080 by default. Override with the TEXT_DISPLAY_URL environment variable if needed.

Prerequisites

• Python 3.12+
• uv — Python package and project manager

Install uv if you do not have it yet:

curl -LsSf https://astral.sh/uv/install.sh | sh

Setup

Clone the repository and install dependencies:

git clone <repository-url>
cd agent-workshop
uv sync

This creates a virtual environment and installs all project dependencies.

To include development tools (pytest, etc.):

uv sync --group dev

Run the application

Start the TUI with either command:

uv run agent-workshop

uv run python -m agent_workshop

Type a message in the input field and press Enter to send it. The agent echoes your message back and telemetry appears in the debug panel on the right.

Quit the app with Ctrl+C or Ctrl+Q.

Environment variables

Variable	Description
DEBUG=1	Emit debug-level messages to the debug panel (info and warn are always shown)
TEXT_DISPLAY_URL	Base URL for the HTTP display app (default: http://localhost:8080; used after workshop step 4)

Run tests

uv run pytest -v

Run a specific test module:

uv run pytest tests/composition/ -v