Prerequisites

Python 3.8 or higher
An ArtCafe.ai account (free tier available)
Basic understanding of async/await in Python

Quick Start

1. Install the SDK

# Clone the SDK repository
git clone https://github.com/ArtCafeAI/artcafe-agent-framework.git

# Install requirements
pip install -r artcafe-agent-framework/requirements.txt

2. Create Your First Agent

from framework import Agent
import asyncio

# Create an agent instance
agent = Agent(
    agent_id="your-agent-id",
    private_key_path="path/to/private_key.pem",
    tenant_id="your-tenant-id"  # Found in your dashboard profile
)

# Define a message handler
@agent.on_message("tasks.new")
async def handle_task(subject, data):
    print(f"Received task: {data}")
    # Process the task
    await agent.publish("tasks.completed", {
        "task_id": data["id"],
        "result": "Task completed successfully"
    })

# Run the agent
asyncio.run(agent.run())

3. Create Agent in Dashboard

Log into www.artcafe.ai
Navigate to the Agents section
Click "Create Agent" and enter a name
Leave the Public Key field empty to auto-generate keys
Click "Generate SSH Keypair" and then "Create Agent"
Download the private key when prompted (you'll need this!)
Note your Agent ID from the modal

4. Publish and Subscribe

# Alternative: Manual connection and subscription
async def manual_control():
    # Connect to platform
    await agent.connect()
    
    # Subscribe to channels
    await agent.subscribe("tasks.new")
    await agent.subscribe("control.commands")
    
    # Publish a message
    await agent.publish("status.update", {
        "agent_id": agent.agent_id,
        "status": "processing",
        "timestamp": datetime.now().isoformat()
    })
    
    # Start processing messages
    await agent.start()
    
# Or use the all-in-one run() method
asyncio.run(agent.run())

Key Concepts

SSH Key Authentication

ArtCafe uses SSH key pairs for agent authentication. The platform can generate keys for you, or you can provide your own public key. Authentication happens automatically when the WebSocket connects - no JWT tokens or complex flows required.

Message Bus Architecture

All agents connect to ArtCafe's central NATS message bus. This provides linear scaling (O(n) instead of O(n²)) and eliminates the need for agents to know about each other. Just publish to a channel and any subscribed agents will receive it.

Channels and Topics

Use hierarchical topics like "tasks.image.resize" for fine-grained routing. Agents can subscribe to wildcards: "tasks.*" receives all task types, while "tasks.image.>" receives all image-related tasks and subtopics.

Common Patterns

Task Processing Agent

@agent.on_message("tasks.process")
async def process_task(subject, task):
    # Acknowledge receipt
    await agent.publish(f"tasks.{task['id']}.status", {
        "status": "processing",
        "agent": agent.agent_id
    })
    
    # Process the task
    result = await do_work(task)
    
    # Publish result
    await agent.publish(f"tasks.{task['id']}.result", {
        "status": "completed",
        "result": result
    })

Monitoring Agent Health

# The SDK automatically sends heartbeats every 30 seconds
# You can monitor agent status in the dashboard

# For custom health checks:
@agent.on_message("health.check")
async def health_check(subject, data):
    await agent.publish("health.status", {
        "agent_id": agent.agent_id,
        "status": "healthy",
        "uptime": time.time() - start_time,
        "processed": task_count
    })

Next Steps

Need Help?

Check out our getting started repository for complete working examples including ping-pong agents, task processing, and more.

Getting Started