OmniLink — Full Documentation Guide

1. Introduction

OmniLink is an AI agent platform that bridges cloud-hosted intelligence with local tool execution. It pairs a cloud REST API with a lightweight local runtime so that large-language-model inference stays in the cloud while actual tool execution happens on your own hardware — a Raspberry Pi, a laptop, or an industrial gateway.

The platform answers one question: How do you let an AI model control physical systems reliably, securely, and affordably?

Platform Components

Key Differentiators

• Multi-model support — Four AI engines available per request with zero code changes.
• 1-credit architecture — Pay for decisions, not execution. Most tasks cost exactly 2 credits.
• Local-first execution — Sensor polling, hardware control, and state management run on-device at zero marginal cost.

2. Quickstart

Step 1 — Install

# Python (from PyPI, or use: pip install -e omnilink-lib/)
pip install omnilink

Step 2 — Get Your Omni Key

Sign in to the Dashboard, navigate to API, and copy your key. It starts with omk_.

Step 3 — First Agent (Python)

from omnilink import OmniLinkEngine, OmniLinkClient

client = OmniLinkClient(omni_key="omk_YOUR_KEY")
engine = OmniLinkEngine()

@engine.command("greet [name:str]")
def greet(name: str):
    return f"Hello, {name}! Welcome to OmniLink."

# Parse a local command
result = engine.parse("greet Alice")
print(result)  # "Hello, Alice! Welcome to OmniLink."

# Send a cloud chat message
response = client.chat("What can you do?", engine="g1-engine")
print(response)

3. Architecture

System Diagram

┌──────────────────────────────────────────────────────────┐
│                     CLOUD LAYER                          │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌─────────┐ │
│  │ g1-engine│  │ g2-engine│  │ g3-engine│  │g4-engine│ │
│  │ (Gemini) │  │  (GPT)   │  │ (Grok)   │  │(Claude) │ │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬────┘ │
│       └──────────────┼──────────────┼─────────────┘      │
│                      ▼                                   │
│            ┌─────────────────┐                           │
│            │  OmniLink API   │  REST endpoints           │
│            │  /api/chat      │  STT, TTS, translate      │
│            │  /api/stt, etc. │  memory, etc.             │
│            └────────┬────────┘                           │
└─────────────────────┼────────────────────────────────────┘
                      │  HTTPS
┌─────────────────────┼────────────────────────────────────┐
│               LOCAL LAYER (your device)                   │
│            ┌────────┴────────┐                           │
│            │  OmniLinkClient │  REST client               │
│            └────────┬────────┘                           │
│       ┌─────────────┼──────────────┐                     │
│  ┌────┴─────┐  ┌────┴─────┐  ┌────┴──────┐             │
│  │OmniLink  │  │ToolRunner│  │ Bridges   │             │
│  │Engine    │  │          │  │ HTTP      │             │
│  │(parser)  │  │(executor)│  │           │             │
│  └────┬─────┘  └────┬─────┘  └────┬──────┘             │
│       └──────────────┼─────────────┘                     │
│                      ▼                                   │
│          Hardware / OS / Sensors / Actuators              │
└──────────────────────────────────────────────────────────┘

Data Flow

1. User input arrives via chat, voice, or HTTP bridge.
2. OmniLinkEngine attempts local template matching first.
3. If no local match, the message is forwarded to the Cloud API.
4. The AI engine reasons over the message, context, and memory.
5. If a tool is needed, ToolRunner receives a kickoff command (1 credit).
6. The local runtime executes the tool loop — polling, acting, persisting — at zero cost.
7. On completion, results are sent back for final analysis (1 credit).
8. The response is delivered to the user.

4. Agent Configuration

Agents are configured through the Dashboard or the REST API. Each agent profile defines personality, capabilities, and behavior.

Profile Fields

System Instructions Example

You are Atlas, a warehouse logistics agent. You control a fleet of
mobile robots. When a user asks you to move inventory, use the
"move" and "pick" commands. Always confirm the destination before
dispatching. Report battery levels if they fall below 20%.

Creating a Profile via API

curl -X POST https://www.omnilink-agents.com/api/agent-profiles \
  -H "Authorization: Bearer omk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Atlas",
    "system_instructions": "You are Atlas, a warehouse logistics agent.",
    "engine": "g2-engine",
    "mode": "deep",
    "memory_enabled": true
  }'

5. Command Parsing

The OmniLinkEngine provides deterministic command matching using a template syntax with typed variables. Templates use the [variable:type] syntax.

Supported Types

Complete Example

from omnilink import OmniLinkEngine

engine = OmniLinkEngine()

# Simple command
@engine.command("ping")
def ping():
    return "pong"

# Typed variables
@engine.command("move [direction:str] [distance:int] meters")
def move(direction: str, distance: int):
    return f"Moving {direction} by {distance}m"

# Multiple variables
@engine.command("set [param:str] to [value:float]")
def set_param(param: str, value: float):
    return f"Parameter {param} set to {value}"

# Boolean flags
@engine.command("lights [state:bool]")
def lights(state: bool):
    return f"Lights {'on' if state else 'off'}"

# Parse input
result = engine.parse("move north 5 meters")
print(result)  # "Moving north by 5m"

# Unknown commands return None
result = engine.parse("fly to mars")
print(result)  # None — forward to cloud AI

Registering Handlers Programmatically

# Without decorator
def emergency_stop():
    return "All systems halted."

engine.register("emergency stop", emergency_stop)

# List all registered commands
for cmd in engine.commands:
    print(cmd.template)

6. Bridges

Bridges let external systems interact with your agent without custom networking code. Two built-in bridges are provided.

HTTP Bridge

Exposes a local REST API on port 8080. External systems send commands via POST /command.

from omnilink import OmniLinkEngine, OmniLinkHTTPBridge

engine = OmniLinkEngine()

@engine.command("status")
def status():
    return {"battery": 87, "state": "idle"}

bridge = OmniLinkHTTPBridge(engine=engine, port=8080)
bridge.start()
# Now accessible at http://localhost:8080/command

# Send a command from any HTTP client
curl -X POST http://localhost:8080/command \
  -H "Content-Type: application/json" \
  -d '{"text": "status"}'

Additional Endpoints

The HTTP bridge also exposes GET /feedback and GET /context endpoints for retrieving execution results and current agent state.

Connection via Dashboard

The Dashboard Connection page lets you configure the agent server URL and port without writing code. The Heart visualization shows real-time message flow.

7. Context & Knowledge

Operational Modes

Knowledge Base

The cloud knowledge upload feature (file upload, /api/knowledge-index, vector-indexed chunks) was removed. Agents now read knowledge from per-agent local folders (agents/<name>/knowledge/) checked into the agent repo and searched from Python via the search_knowledge tool.

Prompt Pipeline

When a message reaches the cloud API, the prompt is assembled in this order:

1. System instructions from the active profile
2. Long-term memory (persistent facts about the user/environment)
3. Short-term memory (recent conversation context)
4. User message

Memory API

from omnilink import OmniLinkClient

client = OmniLinkClient(omni_key="omk_YOUR_KEY")

# Write short-term memory
client.short_term_memory.save("User prefers metric units.")

# Write long-term memory
client.long_term_memory.save("User name is Alice. Location: Berlin.")

# Read memory
stm = client.short_term_memory.get()
ltm = client.long_term_memory.get()

8. ToolRunner

ToolRunner is the cloud-orchestrated local execution engine. It enables multi-step automations where the AI decides what to do and your local code decides how.

Lifecycle

1. User request  ──▶  Cloud AI analyzes intent
2. Kickoff       ──▶  AI issues structured command          (1 credit)
3. Local loop    ──▶  ToolRunner executes:
   │  a. Poll state (sensors, APIs, databases)
   │  b. Execute actions (move, toggle, write)
   │  c. Persist intermediate results
   │  d. Check for UI commands or abort signals
   │  e. Repeat until done or timeout
4. Completion    ──▶  Results sent to cloud for analysis     (1 credit)
5. Response      ──▶  AI summarizes results for the user
───────────────────────────────────────────────────────────
Total cost: 2 credits (regardless of loop iterations)

Implementation

from omnilink import OmniLinkClient, ToolRunner

client = OmniLinkClient(omni_key="omk_YOUR_KEY")

runner = ToolRunner(client=client)

@runner.tool("scan_warehouse")
def scan_warehouse(params):
    """Scan all aisles and return inventory counts."""
    results = []
    for aisle in range(1, 11):
        count = read_rfid_sensor(aisle)     # your hardware function
        results.append({"aisle": aisle, "count": count})
    return {"inventory": results, "status": "complete"}

@runner.tool("move_robot")
def move_robot(params):
    """Move the robot to target coordinates."""
    x, y = params["x"], params["y"]
    navigate_to(x, y)                        # your navigation function
    return {"arrived": True, "position": {"x": x, "y": y}}

# Start listening for tool invocations
runner.start()

Credit Usage

9. REST API Reference

Base URL: https://www.omnilink-agents.com
Authentication: Authorization: Bearer omk_YOUR_KEY

AI Engines

Example Request

curl -X POST https://www.omnilink-agents.com/api/chat \
  -H "Authorization: Bearer omk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What is the battery level?",
    "engine": "g1-engine",
    "mode": "deep",
    "stream": false
  }'

10. Security

Omni Key Management

• Keys start with omk_ and are scoped to your account.
• Never commit keys to version control. Use environment variables or secret managers.
• Rotate keys from the Dashboard API page at any time.
• Each key inherits the permissions and plan limits of its parent account.

CORS

The OmniLink API supports CORS for browser-based clients. Origins are validated against your account settings. Configure allowed origins in the Dashboard.

HTTP Bridge Security

• Use HTTPS for all production HTTP bridge connections.
• Authenticate with Bearer tokens or API keys.
• Restrict endpoint access using reverse proxy rules.
• The Dashboard Connection page supports TLS configuration.

Security Checklist

11. Usage & Billing

Credits

Every API call that invokes an AI engine costs credits. The exact cost depends on the engine and input size, but the 1-credit architecture ensures predictable spending.

Plan Tiers

Manage your plan from the Dashboard Plans page. Usage statistics are available on the Usage page or via GET /api/omni-key-usage.

Optimization Tips

• Use shallow mode for simple queries that do not need memory.
• Use g1-engine for cost-sensitive workloads — it is the fastest and cheapest engine.
• Batch local work in ToolRunner loops to minimize the number of kickoff/analysis cycles.
• Use the command engine for deterministic tasks — local parsing costs zero credits.
• Monitor usage via the API or Dashboard to catch unexpected spikes early.

12. FAQ

1. What is OmniLink?

An AI agent platform that combines cloud-hosted LLM inference with local tool execution, enabling autonomous agents for robotics, IoT, automation, and more.

2. Which AI models are supported?

Four engines: Gemini (g1), GPT (g2), Grok (g3), and Claude (g4). Switch per request or per agent profile.

3. How much does a typical interaction cost?

Most interactions cost 2 credits: 1 for the kickoff decision and 1 for the final analysis. Local execution is free.

4. Can I use OmniLink without the cloud?

The OmniLinkEngine (command parser) and bridges work entirely locally. Cloud access is only needed for AI inference, STT, and TTS.

5. What languages are supported?

The Python library supports Python 3.8+. The REST API is language-agnostic — call it from any language that supports HTTP.

6. Is my data secure?

All API traffic uses HTTPS. Omni Keys are scoped per account. The HTTP bridge supports TLS via reverse proxy.

7. What is the difference between deep and shallow mode?

Deep mode sends full context (memory and history) to the AI. Shallow mode sends only the current message with system instructions — faster and cheaper.

8. Can I run multiple agents on one account?

Yes. Create multiple agent profiles, each with its own system instructions, engine, and mode. Switch between them at will.

9. How does knowledge RAG work?

The cloud knowledge upload feature was removed. Agents now read knowledge from per-agent local folders (agents/<name>/knowledge/) checked into the agent repo and searched from Python via the search_knowledge tool.

10. What happens if my ToolRunner loop times out?

The runner sends whatever partial results it has to the cloud for final analysis. You can configure timeout thresholds per tool.

11. Can I use the HTTP bridge without the Python library?

Yes. Any HTTP client can send commands to POST /command and retrieve feedback from GET /feedback — the bridge is protocol-level, not library-level.

12. How do I switch AI engines mid-conversation?

Pass the engine parameter on each chat request. There is no session lock — every request can target a different engine.

13. Does OmniLink support streaming responses?

Yes. Set stream: true in the chat request to receive tokens as server-sent events.

14. Where can I get help?

Join the Discord community, browse the GitHub repository, or watch tutorials on the YouTube channel.