Agent Connection

Connection Overview

A bridge wraps your OmniLinkEngine instance and exposes it over a network protocol. When an external system sends a command, the bridge receives it, passes it to the engine’s handle() method, and returns the result.

This architecture means you write your command logic once and serve it over the HTTP bridge. No additional broker software is required.

# Data flow
External System  ──▶  HTTP Bridge  ──▶  OmniLinkEngine  ──▶  Handler
                 ◀──  Response / Feedback  ◀──             ◀──  Return value

HTTP Bridge

The OmniLinkHTTPBridge starts a lightweight HTTP server that accepts command requests. It is the simplest way to expose your agent to web applications, mobile apps, or other services that speak HTTP.

Quick Start

from omnilink import OmniLinkEngine, OmniLinkHTTPBridge, TypeRegistry

types = TypeRegistry()
types.register("door", r"(?:front_door|back_door|garage_door)")

engine = OmniLinkEngine(["open_the_[door:door]", "get_status"], types=types)

def handle_open(evt):
    return {"door": evt["vars"]["door"], "state": "open"}

def handle_status(evt):
    return {"status": "operational", "uptime": 3600}

engine.on_template("open_the_[door:door]", handle_open)
engine.on_template("get_status", handle_status)

# Start the HTTP bridge
bridge = OmniLinkHTTPBridge(engine)
bridge.loop_forever()  # Listens on 0.0.0.0:8080

POST /command

The primary endpoint accepts a JSON body with a command field:

curl -X POST http://localhost:8080/command \
  -H "Content-Type: application/json" \
  -d '{"command": "open the front_door"}'

Response:

{
  "matched": true,
  "result": {
    "door": "front_door",
    "state": "open"
  }
}

POST /discover (planned — not yet available)

The discover endpoint is planned to return the list of registered templates, useful for client applications that need to know what commands are available. This endpoint is not yet implemented in the current version of OmniLinkHTTPBridge.

# Planned usage (not yet available):
curl -X POST http://localhost:8080/discover

Expected response (once implemented):

{
  "templates": [
    "open_the_[door:door]",
    "get_status"
  ]
}

Custom Host and Port

Override the default binding with constructor arguments:

bridge = OmniLinkHTTPBridge(engine, host="127.0.0.1", port=9090)
bridge.loop_forever()

CLI Entry Point

You can also start the HTTP bridge from the command line:

python -m omnilink.link_http

This reads configuration from environment variables (see the Environment Variables section below).

REST API Endpoints

The HTTP bridge exposes three endpoints for external systems to interact with your agent:

Message Format

Send a JSON payload to the command endpoint:

curl -X POST http://localhost:8080/command \
  -H "Content-Type: application/json" \
  -d '{"command": "turn_on_light"}'

The bridge processes the command and returns the result:

{
  "matched": true,
  "result": {
    "device": "light",
    "state": "on"
  }
}

Dashboard Connection Page

The Dashboard’s Connection page provides a visual interface for configuring agent connectivity:

1. Navigate to Connection. Select Connection from the Dashboard sidebar.
2. Enter the agent server URL. Specify the HTTP bridge address, for example http://localhost:8080 for a local agent or https://agent.example.com for a remote agent.
3. Set the port. Enter the port number if it differs from the default embedded in the URL.
4. Test the connection. Click Connect to verify that the Dashboard can reach the agent server.
5. Save. Once connected, the settings persist for your account.

HTTP REST API from the Browser

The Dashboard connects to your agent’s HTTP server over standard HTTP (or HTTPS for production). The agent exposes a REST API on a configurable host and port — no additional broker software is required.

Example agent HTTP server configuration:

# Start the agent HTTP server
# Default: http://localhost:8080
export OMNI_HTTP_HOST="0.0.0.0"
export OMNI_HTTP_PORT="8080"

# For production, place behind a reverse proxy with HTTPS

Heart Page

The Dashboard’s Heart page provides a real-time visualization of HTTP message flow. Once you are connected to an agent server via the Connection page, the Heart page displays:

• Live message stream — Incoming and outgoing messages appear in real time as they are sent and received.
• Endpoint filtering — Filter the display by endpoint to focus on specific message flows.
• Message inspection — Click on any message to view its full JSON payload.
• Connection health — Visual indicators show whether the HTTP connection is active or disconnected.

The Heart page is invaluable for debugging during development. It lets you verify that commands are reaching the bridge and that feedback messages are being returned correctly.

Transport Selection Guide

The HTTP bridge serves your command engine over a standard REST API. It is the recommended transport for all use cases:

Example Setup

from omnilink import OmniLinkEngine, OmniLinkHTTPBridge

engine = OmniLinkEngine(["get_status"], types=None)

def handle_status(evt):
    return {"status": "ok"}

engine.on_template("get_status", handle_status)

bridge = OmniLinkHTTPBridge(engine, port=8080)
bridge.loop_forever()

Environment Variables

The HTTP bridge reads configuration from environment variables when using the CLI entry point or when constructor arguments are not provided:

Set these in your shell or in a .env file loaded by your application:

export HTTP_BRIDGE_HOST=0.0.0.0
export HTTP_BRIDGE_PORT=9090

Security Considerations

• Do not expose bridges to the public internet without authentication. The built-in bridges do not include auth middleware. Place them behind a reverse proxy (e.g., Nginx, Caddy) or within a private network.
• Use HTTPS in production. Place your HTTP bridge behind a reverse proxy with TLS certificates.
• Bind to localhost during development. Use host="127.0.0.1" to prevent external access while testing locally.

Next Steps

• Command Parsing — Define the templates and handlers that bridges serve.
• Context System — Add knowledge grounding to your agent’s responses.
• OmniLink-lib Reference — Full API reference for bridge classes.