Agent Protocol Handler Setup

Enable agent:// URL scheme for spawning agents from browsers and other applications.

Format: agent://<role>/<task-description>

Example: agent://engineer/implement%20user%20authentication

Overview

The agent protocol handler allows you to spawn AI-Pack agents using URLs. This enables:

Browser-based agent spawning
Integration with task management tools
Command-line URL handling
Cross-application workflows

URL Format

agent://<role>/<task-description>

Components:
  <role>         - Agent role: engineer, tester, or reviewer
  <task-description> - URL-encoded task description

Examples:

agent://engineer/implement%20REST%20API
agent://tester/create%20unit%20tests
agent://reviewer/security%20audit

Platform-Specific Setup

macOS

Option 1: Manual Registration (Recommended)

Create Handler App using Automator:

a. Open Automator b. Create new "Application" c. Add "Run Shell Script" action d. Set shell to /bin/bash e. Paste this script:

AGENT_URL="$1"
AGENT_TYPE=$(echo "$AGENT_URL" | sed 's|agent://||' | cut -d'/' -f1)
TASK_DESC=$(echo "$AGENT_URL" | sed 's|agent://||' | cut -d'/' -f2-)
TASK_DESC=$(python3 -c "import urllib.parse; print(urllib.parse.unquote('$TASK_DESC'))")

cd /path/to/ai-pack
./agent "$AGENT_TYPE" "$TASK_DESC"

f. Save as "AI-Pack Handler.app" in Applications folder

Register Protocol:

Create ~/Library/Preferences/com.aipack.handler.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>CFBundleURLTypes</key>
    <array>
        <dict>
            <key>CFBundleURLName</key>
            <string>AI-Pack Agent Protocol</string>
            <key>CFBundleURLSchemes</key>
            <array>
                <string>agent</string>
            </array>
        </dict>
    </array>
</dict>
</plist>

Register with Launch Services:

/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister \
  -f "/Applications/AI-Pack Handler.app"

Test:
```
open "agent://engineer/test%20task"
```

Option 2: Using Provided Script

The setup script creates .ai-pack/agent_protocol_handler.sh. To use:

Create app wrapper using Automator (steps 1-2 above)
Point to the generated script

Verification

# Test URL handling
open "agent://engineer/implement%20greeting%20function"

# Check if protocol is registered
/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister \
  -dump | grep agent

Linux

Automatic Registration (via setup.py)

The setup script automatically registers the handler on Linux if update-desktop-database is available.

Manual Registration

Handler Script (created by setup.py):

.ai-pack/agent_protocol_handler.sh

Desktop Entry:

Create ~/.local/share/applications/ai-pack-handler.desktop:

[Desktop Entry]
Type=Application
Name=AI-Pack Agent Handler
Exec=/path/to/ai-pack/.ai-pack/agent_protocol_handler.sh %u
MimeType=x-scheme-handler/agent
NoDisplay=true

Update MIME Database:

update-desktop-database ~/.local/share/applications

Set Default Handler:

xdg-mime default ai-pack-handler.desktop x-scheme-handler/agent

Verification

# Test URL handling
xdg-open "agent://engineer/test%20task"

# Check registration
xdg-mime query default x-scheme-handler/agent
# Should output: ai-pack-handler.desktop

Windows

Manual Registry Setup

Handler Script (created by setup.py):

.ai-pack\agent_protocol_handler.bat

Registry Entries:

Create agent-protocol.reg:

Windows Registry Editor Version 5.00

[HKEY_CLASSES_ROOT\agent]
@="URL:AI-Pack Agent Protocol"
"URL Protocol"=""

[HKEY_CLASSES_ROOT\agent\DefaultIcon]
@="C:\\path\\to\\ai-pack\\.ai-pack\\icon.ico,1"

[HKEY_CLASSES_ROOT\agent\shell]

[HKEY_CLASSES_ROOT\agent\shell\open]

[HKEY_CLASSES_ROOT\agent\shell\open\command]
@="\"C:\\path\\to\\ai-pack\\.ai-pack\\agent_protocol_handler.bat\" \"%1\""

Important: Replace C:\\path\\to\\ai-pack with your actual installation path.

Import Registry:
```
regedit /s agent-protocol.reg
```

PowerShell Script (Alternative)

# Register agent:// protocol
$handlerPath = "C:\path\to\ai-pack\.ai-pack\agent_protocol_handler.bat"

New-Item -Path "HKCU:\Software\Classes\agent" -Force
Set-ItemProperty -Path "HKCU:\Software\Classes\agent" -Name "(Default)" -Value "URL:AI-Pack Agent Protocol"
Set-ItemProperty -Path "HKCU:\Software\Classes\agent" -Name "URL Protocol" -Value ""

New-Item -Path "HKCU:\Software\Classes\agent\shell\open\command" -Force
Set-ItemProperty -Path "HKCU:\Software\Classes\agent\shell\open\command" -Name "(Default)" -Value "`"$handlerPath`" `"%1`""

Verification

REM Test URL handling
start agent://engineer/test%20task

REM Check registration
reg query HKEY_CLASSES_ROOT\agent

Usage Examples

Browser Integration

HTML Links

<a href="agent://engineer/implement%20login%20API">
  Spawn Engineer: Implement Login API
</a>

<a href="agent://tester/create%20unit%20tests%20for%20auth">
  Spawn Tester: Create Auth Tests
</a>

<a href="agent://reviewer/security%20review%20of%20auth">
  Spawn Reviewer: Security Review
</a>

JavaScript

// Spawn agent from JavaScript
function spawnAgent(role, task) {
  const encodedTask = encodeURIComponent(task);
  const url = `agent://${role}/${encodedTask}`;
  window.location.href = url;
}

// Usage
spawnAgent('engineer', 'implement user authentication');
spawnAgent('tester', 'create tests for auth module');
spawnAgent('reviewer', 'review authentication code');

Command Line

macOS/Linux

# Spawn engineer
open "agent://engineer/implement%20REST%20API"     # macOS
xdg-open "agent://engineer/implement%20REST%20API" # Linux

# With dynamic task
TASK="implement user registration"
ENCODED=$(python3 -c "import urllib.parse; print(urllib.parse.unquote('$TASK'))")
open "agent://engineer/$ENCODED"

Windows

REM Spawn engineer
start agent://engineer/implement%20REST%20API

REM With dynamic task
set TASK=implement user registration
start agent://engineer/%TASK: =%%20%

Task Management Integration

JIRA Integration

Use custom fields or automation rules:

Trigger: Issue status changed to "Ready for Development"
Action: POST to webhook with agent:// URL
URL: agent://engineer/implement%20{{issue.summary}}

Notion Integration

Create database with formula field:

concat("agent://engineer/", replaceAll(prop("Task"), " ", "%20"))

Slack Integration

Slash command:

/spawn engineer implement user auth
→ Generates: agent://engineer/implement%20user%20auth

URL Encoding

Common Encodings

Character	Encoded	Example
Space	`%20`	`user auth` → `user%20auth`
Slash	`%2F`	`src/auth.py` → `src%2Fauth.py`
Quote	`%22`	`"test"` → `%22test%22`
Ampersand	`%26`	`A & B` → `A%20%26%20B`

Python Encoding

import urllib.parse

task = "implement user authentication with OAuth"
encoded = urllib.parse.quote(task)
url = f"agent://engineer/{encoded}"

JavaScript Encoding

const task = "implement user authentication with OAuth";
const encoded = encodeURIComponent(task);
const url = `agent://engineer/${encoded}`;

Bash Encoding

TASK="implement user authentication with OAuth"
ENCODED=$(python3 -c "import urllib.parse; print(urllib.parse.quote('$TASK'))")
URL="agent://engineer/$ENCODED"

Security Considerations

Input Validation

The protocol handler should validate:

Role is valid (engineer, tester, reviewer)
Task description is reasonable length (less than 10KB)
No command injection attempts

Sandboxing

Consider running agents in restricted environments:

Limited file system access
Network restrictions
Timeout enforcement

Audit Logging

Log all agent spawns via protocol handler:

Timestamp
Role
Task description
Source (if available)
User context

Troubleshooting

Handler Not Registered

macOS:

# Check registration
/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister \
  -dump | grep -i agent

# Re-register
/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister \
  -f "/Applications/AI-Pack Handler.app"

Linux:

# Check MIME association
xdg-mime query default x-scheme-handler/agent

# Re-register
update-desktop-database ~/.local/share/applications
xdg-mime default ai-pack-handler.desktop x-scheme-handler/agent

Windows:

REM Check registration
reg query HKEY_CLASSES_ROOT\agent

REM Re-import
regedit /s agent-protocol.reg

URL Not Opening

Check handler script permissions (Unix):

chmod +x .ai-pack/agent_protocol_handler.sh

Verify paths in handler - ensure absolute paths are correct

Test handler directly:

.ai-pack/agent_protocol_handler.sh "agent://engineer/test"

Task Not Spawning

Check bd spawn works:
```
agent engineer "test task"
```
Check task packet creation:
```
ls .beads/tasks/
```
Review handler logs - add logging to handler script

Advanced Configuration

Custom Protocol Schemes

agent-dev:// - Development environment
agent-staging:// - Staging environment
agent-prod:// - Production environment

Multi-Project Support

Include project identifier in URL:

agent://engineer/project-name/task-description

Handler extracts project and switches context:

PROJECT=$(echo "$AGENT_URL" | cut -d'/' -f2)
TASK=$(echo "$AGENT_URL" | cut -d'/' -f3-)

cd "/path/to/$PROJECT"
./agent engineer "$TASK"

Remote Agent Spawning

For Phase 2, support remote agent spawning:

agent://engineer/task?remote=true&server=https://a2a-server.example.com

Testing

Basic Test

# macOS
open "agent://engineer/implement%20greeting%20function"

# Linux
xdg-open "agent://engineer/implement%20greeting%20function"

# Windows
start agent://engineer/implement%20greeting%20function

Verify Task Creation

# Check for new task packet
ls -lt .beads/tasks/ | head -5

# View task metadata
cat .beads/tasks/task-engineer-*/00-metadata.json

Integration Test

Create HTML test file:

<!DOCTYPE html>
<html>
<head><title>Agent Protocol Test</title></head>
<body>
  <h1>AI-Pack Protocol Handler Test</h1>
  <ul>
    <li><a href="agent://engineer/implement%20test%20function">Test Engineer</a></li>
    <li><a href="agent://tester/create%20test%20suite">Test Tester</a></li>
    <li><a href="agent://reviewer/review%20code%20quality">Test Reviewer</a></li>
  </ul>
</body>
</html>

Open in browser
Click links
Verify agents spawn

Future Enhancements (Phase 2)

A2A Protocol Integration

agent://engineer/task?protocol=a2a&timeout=30m

Streaming Progress

agent://engineer/task?stream=true&callback=https://example.com/progress

Agent Chaining

agent://workflow/feature-development?steps=engineer,tester,reviewer

Reference

Documentation:

Setup Script: setup.py
Usage Guide: docs/USAGE-GUIDE.md
Architecture: docs/A2A-IMPLEMENTATION-PLAN.md

Generated Scripts:

macOS/Linux: .ai-pack/agent_protocol_handler.sh
Windows: .ai-pack\agent_protocol_handler.bat

Last Updated: 2026-01-23 Version: 1.0.0 (Phase 1)

Overview​

URL Format​

Platform-Specific Setup​

macOS​

Option 1: Manual Registration (Recommended)​

Option 2: Using Provided Script​

Verification​

Linux​

Automatic Registration (via setup.py)​

Manual Registration​

Verification​

Windows​

Manual Registry Setup​

PowerShell Script (Alternative)​

Verification​

Usage Examples​

Browser Integration​

HTML Links​

JavaScript​

Command Line​

macOS/Linux​

Windows​

Task Management Integration​

JIRA Integration​

Notion Integration​

Slack Integration​

URL Encoding​

Common Encodings​

Python Encoding​

JavaScript Encoding​

Bash Encoding​

Security Considerations​

Input Validation​

Sandboxing​

Audit Logging​

Troubleshooting​

Handler Not Registered​

URL Not Opening​

Task Not Spawning​

Advanced Configuration​

Custom Protocol Schemes​

Multi-Project Support​

Remote Agent Spawning​

Testing​

Basic Test​

Verify Task Creation​

Integration Test​

Future Enhancements (Phase 2)​

A2A Protocol Integration​

Streaming Progress​

Agent Chaining​

Reference​

Overview

URL Format

Platform-Specific Setup

macOS

Option 1: Manual Registration (Recommended)

Option 2: Using Provided Script

Verification

Linux

Automatic Registration (via setup.py)

Manual Registration

Verification

Windows

Manual Registry Setup

PowerShell Script (Alternative)

Verification

Usage Examples

Browser Integration

HTML Links

JavaScript

Command Line

macOS/Linux

Windows

Task Management Integration

JIRA Integration

Notion Integration

Slack Integration

URL Encoding

Common Encodings

Python Encoding

JavaScript Encoding

Bash Encoding

Security Considerations

Input Validation

Sandboxing

Audit Logging

Troubleshooting

Handler Not Registered

URL Not Opening

Task Not Spawning

Advanced Configuration

Custom Protocol Schemes

Multi-Project Support

Remote Agent Spawning

Testing

Basic Test

Verify Task Creation

Integration Test

Future Enhancements (Phase 2)

A2A Protocol Integration

Streaming Progress

Agent Chaining

Reference