PromptlyAgent Trigger API Client

A standalone Python client for interacting with trigger API endpoints. Supports three modes of operation:

• Interactive TUI: Full-featured chat interface with history, commands, and file attachments
• Direct Mode: Clean answer-only output for scripting and automation
• JSON Mode: Structured output for programmatic integration

Screenshots

Interactive TUI with real-time streaming and rich markdown rendering:

Features

• ✅ Real-time SSE streaming with live status updates
• ✅ Interactive TUI with rich markdown rendering
• ✅ Session management and history
• ✅ File attachment support (up to 5MB per file)
• ✅ Multiple output modes (TUI, direct, JSON)
• ✅ Environment variable configuration
• ✅ Clipboard integration (paste command)
• ✅ Comprehensive command system

Installation

1. Install Python Dependencies

git clone git@github.com:promptlyagentai/trigger-api-client.git
cd trigger-api-client
pip install -r requirements.txt

Or if you prefer using a virtual environment:

git clone git@github.com:promptlyagentai/trigger-api-client.git
cd trigger-api-client
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

2. Configure Environment Variables (Optional)

cp .env.example .env
# Edit .env with your values

Or export them directly:

export PROMPTLYAGENT_API_TOKEN="your_token_here"
export PROMPTLYAGENT_BASE_URL="http://localhost"
export PROMPTLYAGENT_TRIGGER_ID="your_trigger_uuid"

Usage Modes

Interactive TUI Mode

Launch the interactive chat interface (when no message is provided):

python chat.py --token YOUR_TOKEN --trigger TRIGGER_ID

TUI Features:

• Rich markdown rendering for agent responses
• Live status updates as agent works
• Session history (shows last 5 interactions on start)
• File attachment management
• Keyboard shortcuts and commands

TUI Commands:

• /attach <file> - Attach a file to your next message
• /detach [file] - Remove attached file(s)
• /paste - Paste clipboard content into input
• /refresh - Reload session history from server
• /clear - Clear chat history display
• /help - Show help message
• /exit or /quit - Exit application

TUI Keyboard Shortcuts:

• Ctrl+C - Exit application
• Enter - Send message
• \+Enter - Insert new line without sending

Direct Mode

Get clean answer-only output (perfect for scripting):

python chat.py --token YOUR_TOKEN --trigger TRIGGER_ID "Your question"

With file attachments:

python chat.py --token YOUR_TOKEN --trigger TRIGGER_ID --attach .env.example "what's in this document"

With multiple files:

python chat.py --token YOUR_TOKEN --trigger TRIGGER_ID --attach file1.txt --attach file2.txt "Compare these files"

JSON Mode

Structured output for programmatic use:

python chat.py --token YOUR_TOKEN --trigger TRIGGER_ID --json "Your question"

JSON Output Format:

{
  "success": true,
  "answer": "The agent's response",
  "session_id": 123,
  "interaction_id": 456
}

Pipe Mode

Read input from stdin:

echo "Your question" | python chat.py --token YOUR_TOKEN --trigger TRIGGER_ID
cat question.txt | python chat.py --token YOUR_TOKEN --trigger TRIGGER_ID

Session Continuation

Continue an existing session:

# Interactive TUI
python chat.py --token YOUR_TOKEN --trigger TRIGGER_ID --session 123

# Direct mode
python chat.py --token YOUR_TOKEN --trigger TRIGGER_ID --session 123 "Follow-up question"

Using Environment Variables

After setting environment variables or using a .env file:

# Interactive TUI
python chat.py

# Direct mode
python chat.py "Your question"

# With file attachment
python chat.py --attach data.csv "Analyze this data"

Custom Base URL

python chat.py --base-url https://your-domain.com --token YOUR_TOKEN --trigger TRIGGER_ID "Question"

Expected Output

TUI Mode

🤖 PromptlyAgent Chat

Authenticating...
✓ Authenticated as: John Doe

Validating session...
✓ Session validated: API Testing Session

Loading conversation history...
Loaded 2 recent interactions:
────────────────────────────────────────────────────────────

You:
Previous question here

Agent:
Previous answer here
────────────────────────────────────────────────────────────

> _

Direct Mode

When working correctly, you should see real-time updates as they happen:

You:
  list pages in private notion

→ Initializing agent workflow...
[09:34:28] • Starting Promptly Agent execution (agent_execution_started)
[09:34:29] • Loaded 17 tools for agent execution (agent_tools_loaded)
[09:34:29] • Handing over to AI agent 'Promptly Agent' with 17 available tools (ai_agent_handover)
[09:34:38] • AI is now processing the request (ai_processing_started)
[09:34:38] • Agent execution completed: Promptly Agent (0 steps) (agent_execution_completed)

Agent:
Here's a list of recognizable main pages...
[full answer displayed here]

Session: 22 | Interaction: 110

Important: Each step should appear progressively with timestamps showing when they occurred, not all at once at the end.

File Attachments

Supported File Types

The API accepts various file types. Check with your administrator for specific restrictions.

Size Limits

• Maximum file size: 5MB per file
• Multiple files can be attached in a single request

TUI Mode File Attachments

# In TUI, use the /attach command:
> /attach /path/to/file.txt
✓ Attached: file.txt (24.5KB)

> What's in this document?

Direct Mode File Attachments

# Single file
python chat.py --token TOKEN --trigger ID --attach file.txt "Analyze this"

# Multiple files
python chat.py --token TOKEN --trigger ID --attach f1.txt --attach f2.txt "Compare these"

API Token Requirements

Your API token needs the following abilities:

• trigger:invoke - Required for executing triggers
• trigger:status - Required for session validation and history
• trigger:attach - Required for file attachments

Create a token with proper abilities:

php artisan tinker

$user = User::where('email', 'your@email.com')->first();
$token = $user->createToken('Trigger API Client', [
    'trigger:invoke',
    'trigger:status',
    'trigger:attach'
]);
echo $token->plainTextToken;

Getting Your Trigger ID

From the web interface:

1. Go to Settings → Input Triggers
2. Click on your trigger
3. Copy the UUID from the URL or settings

Or via API:

curl -H "Authorization: Bearer YOUR_TOKEN" http://localhost/api/v1/triggers

Troubleshooting

Import Errors

pip install -r requirements.txt

Connection Refused

Make sure your Laravel app is running:

# From project root
./vendor/bin/sail up

401 Unauthorized

Verify your API token is valid:

curl -H "Authorization: Bearer YOUR_TOKEN" http://localhost/api/user

You should see your user information in the response.

403 Forbidden - Missing Ability

Check that your token has the required abilities:

• trigger:invoke for executing triggers
• trigger:status for session operations
• trigger:attach for file uploads

All Updates Appear At Once (Not Streaming)

If you see all status updates together at the end instead of progressively, this indicates a backend streaming issue, not a client issue. The Python client correctly handles SSE - the problem is in the Laravel streaming implementation.

Check the Laravel logs for streaming behavior:

tail -f storage/logs/laravel.log | grep -E "(EventStreamNotifier|StreamingTriggerExecutor)"

No Answer Received

The response includes status updates but no final answer. Check:

• Agent configuration is correct
• Agent has necessary tools enabled
• Check storage/logs/laravel.log for errors

File Upload Errors

File not found:

• Check the file path is correct
• Use absolute paths or paths relative to current directory

File too large:

• Maximum size is 5MB per file
• Compress or split large files

Permission denied:

• Ensure the client has read permissions for the file

Why Use This Client?

Feature	Python Client	Laravel Command
Output Buffering	None - true streaming	Multiple layers of buffering
Realistic Testing	Tests actual API behavior	Tests through Laravel framework
Portability	Works anywhere Python runs	Requires Laravel environment
Debugging	See true SSE behavior	May hide streaming issues
Performance	Direct HTTP	Framework overhead
File Attachments	Full support	Not available
Interactive Mode	Rich TUI with history	Basic CLI only

Development

Project Structure

trigger-api-client/
├── chat.py              # Main entry point
├── lib/
│   ├── api_client.py    # API client helpers
│   ├── sse_client.py    # SSE stream handling
│   ├── tui_app.py       # Textual TUI application
│   ├── commands.py      # TUI command handlers
│   └── output_modes.py  # Output formatters
├── requirements.txt     # Python dependencies
└── README.md           # This file

Extending the Client

Adding new TUI commands:

Edit lib/commands.py and add your command handler:

async def handle_mycommand(app: 'ChatTUI') -> bool:
    """Handle /mycommand"""
    # Your logic here
    return True

# Register in COMMANDS dict
COMMANDS = {
    'mycommand': handle_mycommand,
    # ... other commands
}

Adding new output modes:

Edit lib/output_modes.py and extend the OutputMode base class.

Customizing SSE parsing:

Edit lib/sse_client.py to handle new event types or modify event handling logic.

License

This script is part of the PromptlyAgent project.