Skip to content

Latest commit

 

History

History

echo-js

README.md

Echo Tool as a Service Example (JavaScript)

A minimal example demonstrating how to build and coordinate a tool as a service using Orra's Plan Engine. It's Orra Hello World!

sequenceDiagram
    participant CLI as Orra CLI
    participant PE as Plan Engine
    participant ES as Echo Tool as Service
    participant WH as Webhook Server

    CLI->>PE: Send action
    PE->>ES: Orchestrate task
    ES->>PE: Return echo
    PE->>WH: Send result
    Note over WH: See result in terminal
Loading

✨ Features

  • 🔄 Basic service registration and coordination
  • 📡 Real-time WebSocket communication
  • ⚡ Reliable message delivery
  • 🛡️ Built-in health monitoring
  • 🚀 Simple but production-ready patterns

Prerequisites

Setup

  1. First, setup Orra and the CLI by following the installation instructions:

  2. Setup your Orra project:

# Create project, add a webhook and API key
orra projects add my-echo-app
orra webhooks add http://host.docker.internal:8888/webhook
orra api-keys gen echo-key
  1. Configure the Echo tool as service:
cd examples/echo-js
echo "ORRA_API_KEY=echo-key-from-step-2" > .env

Running the Example

  1. Start the webhook server (in a separate terminal):
# Start the webhook server using the verify subcommand
orra verify webhooks start http://localhost:8888/webhook
  1. Start the Echo service:
# Start Echo Service
docker compose up
  1. Try it out:
# Send a test message
orra verify run "Echo this message" --data message:"Hello from Orra!"

# Check the result
orra ps
orra inspect <orchestration-id>

You should see the result both in the webhook server terminal and through the inspect command.

SDK Integration Example

Here's the complete Echo service implementation showing how simple Orra integration can be:

import { initService } from '@orra.dev/sdk';
import schema from './schema.json' assert { type: 'json' };

const echoToolSvc = initService({
	name: 'echo',
	orraUrl: process.env.ORRA_URL,
	orraKey: process.env.ORRA_API_KEY
});

// Health check
app.get('/health', (req, res) => {
	res.status(200).json({ status: 'healthy' });
});

async function startService() {
	try {
		// Register the echo service with Orra
		await echoToolSvc.register({
			description: 'An echo provider that echoes back the first input value it receives.',
			schema
		});
			
		echoToolSvc.start(async (task) => {
            console.log('Echoing input:', task.id);
            const { message } = task?.input;
            return { echo: `Echo: ${message}` };
		});
	} catch (error) {
		console.error('Failed to start:', error);
		process.exit(1);
	}
}

// Start the Express server and the service
app.listen(port, () => {
	console.log(`Server listening on port ${port}`);
	startService().catch(console.error);
});

That's it! Orra provides:

  • Service discovery
  • Health monitoring
  • Reliable task execution
  • Error recovery

Learn More