Quickstart

Prerequisites

Before you begin, make sure you have the following:

Your Omni Key has the format olink_... and is used as a Bearer token for all API requests. Keep it secret — treat it like a password.

Step 1: Install the Python Library

Open a terminal and install the omnilink package:

# From PyPI (when published)
pip install omnilink

# Or install from source
git clone https://github.com/omnilink/omnilink
pip install -e omnilink/omnilink-lib

Verify the installation:

python -c "import omnilink; print(omnilink.__version__)"

Expected output:

0.1.0

The library has minimal dependencies and installs in seconds. It includes the OmniLinkEngine, OmniLinkClient, ToolRunner, and both bridges.

Step 2: Set Your Omni Key

If you don’t have a key yet, generate one now:

Get your Omni Key →

Export your Omni Key as an environment variable. This is the recommended way to provide credentials — it keeps your key out of source code.

Linux / macOS

export OMNI_KEY="olink_your_key_here"

Windows (PowerShell)

$env:OMNI_KEY = "olink_your_key_here"

Windows (CMD)

set OMNI_KEY=olink_your_key_here

Alternatively, you can pass the key directly when creating a client instance. Both approaches work, but environment variables are preferred for production use.

Step 3: Create Your First Agent

Create a file called my_agent.py and add the following code. This sets up an OmniLinkEngine with two custom commands:

from omnilink import OmniLinkEngine

# Initialize the command engine
engine = OmniLinkEngine()

# Register a greeting command
@engine.command("greet [name:str]")
def greet(name: str):
    """Greet someone by name."""
    return f"Hello, {name}! Welcome to OmniLink."

# Register a math command
@engine.command("add [a:int] and [b:int]")
def add(a: int, b: int):
    """Add two numbers together."""
    result = a + b
    return f"{a} + {b} = {result}"

# Register a status command
@engine.command("system status")
def status():
    """Report the current system status."""
    return "All systems operational. Engine running. 0 errors."

# Test the engine locally
if __name__ == "__main__":
    # Parse and execute commands
    result1 = engine.parse("greet Alice")
    print(result1)

    result2 = engine.parse("add 17 and 25")
    print(result2)

    result3 = engine.parse("system status")
    print(result3)

Run it:

python my_agent.py

Expected output:

Hello, Alice! Welcome to OmniLink.
17 + 25 = 42
All systems operational. Engine running. 0 errors.

The OmniLinkEngine parsed each input string, matched it against the registered templates, extracted the typed variables, and called the corresponding handler. No cloud API was needed for this step — command parsing is entirely local.

Step 4: Register on the Platform

Now connect your local agent to the OmniLink cloud. Use the OmniLinkClient to create an agent profile:

import os
from omnilink import OmniLinkClient

# Initialize the client with your Omni Key
client = OmniLinkClient(omni_key=os.environ["OMNI_KEY"])

# Create a new agent profile
profile = client.create_profile(
    name="MyFirstAgent",
    persona="A helpful assistant that can greet people and do math.",
    system_instructions="""
You are MyFirstAgent. You can:
- Greet people by name
- Add two numbers together
- Report system status

When a user asks you to perform one of these tasks, respond with
the appropriate command. Be friendly and concise.
""",
    engine="g1-engine"  # Gemini for fast responses
)

print(f"Profile created: {profile['name']}")
print(f"Profile ID: {profile['id']}")

Expected output:

Profile created: MyFirstAgent
Profile ID: prof_abc123def456

Your agent profile is now stored in the cloud. It includes the system instructions, persona, and engine preference. You can manage this profile from the Dashboard or through the API.

Step 5: Send Your First Chat Message

With the profile in place, send a message through the cloud AI:

import os
from omnilink import OmniLinkClient

client = OmniLinkClient(omni_key=os.environ["OMNI_KEY"])

# Send a chat message
response = client.chat(
    message="Can you add 150 and 273 for me?",
    profile="MyFirstAgent",
    engine="g1-engine"
)

# Print the AI response
print(f"AI says: {response.text}")
print(f"Engine used: {response.engine}")
print(f"Credits used: {response.credits_used}")

Expected output:

AI says: Sure! 150 + 273 = 423.
Engine used: g1-engine
Credits used: 1

The cloud AI received your message, processed it using Gemini, and returned a response. The system instructions you set in Step 4 shaped how the model responded.

Try Different Engines

Switch to a different engine by changing the engine parameter:

# Try GPT for complex reasoning
response = client.chat(
    message="Explain quantum entanglement in simple terms.",
    profile="MyFirstAgent",
    engine="g2-engine"
)
print(response.text)

# Try Claude for precise instruction following
response = client.chat(
    message="List exactly 5 benefits of automation.",
    profile="MyFirstAgent",
    engine="g4-engine"
)
print(response.text)

Step 6: Run a ToolRunner Example

ToolRunner is OmniLink’s most powerful feature. It lets the cloud AI orchestrate a local tool while keeping costs to just 2 credits. Here is a complete example:

import os
from omnilink import ToolRunner

class FileOrganizer(ToolRunner):
    """An AI-powered file organizer that sorts files by type."""

    def __init__(self, target_dir: str, **kwargs):
        super().__init__(**kwargs)
        self.target_dir = target_dir
        self.files_moved = 0

    def get_state(self) -> dict:
        """Return the current state of the target directory."""
        import os
        files = os.listdir(self.target_dir)
        by_extension = {}
        for f in files:
            ext = os.path.splitext(f)[1] or "no_extension"
            by_extension.setdefault(ext, []).append(f)
        return {
            "directory": self.target_dir,
            "total_files": len(files),
            "by_extension": by_extension,
            "files_moved_so_far": self.files_moved,
        }

    def execute_action(self, state: dict) -> None:
        """Execute a file organization action."""
        import shutil, os

        action = state.get("action", "")
        # Action format: "move  to "
        parts = action.split()
        if len(parts) >= 4 and parts[0] == "move" and parts[2] == "to":
            filename = parts[1]
            subfolder = parts[3]
            src = os.path.join(self.target_dir, filename)
            dst_dir = os.path.join(self.target_dir, subfolder)
            os.makedirs(dst_dir, exist_ok=True)
            dst = os.path.join(dst_dir, filename)
            if os.path.exists(src):
                shutil.move(src, dst)
                self.files_moved += 1

    def is_game_over(self, state: dict) -> bool:
        """Check if all files have been organized."""
        import os
        remaining = [
            f for f in os.listdir(self.target_dir)
            if os.path.isfile(os.path.join(self.target_dir, f))
        ]
        return len(remaining) == 0

# Create and start the runner
runner = FileOrganizer(
    target_dir="./messy_folder",
    omni_key=os.environ["OMNI_KEY"],
    engine="g2-engine",  # GPT for smart file categorization
    task_description="Organize all files in the directory into subfolders by type.",
)

# Start the ToolRunner lifecycle:
#   1 credit  -> Kickoff (AI analyzes state, plans actions)
#   0 credits -> Main loop (local execution)
#   1 credit  -> Final analysis (AI summarizes what was done)
result = runner.start()

print(f"Task complete!")
print(f"Files moved: {runner.files_moved}")
print(f"AI summary: {result.summary}")
print(f"Total credits: {result.credits_used}")  # Typically 2

Expected output:

Task complete!
Files moved: 23
AI summary: Organized 23 files into 5 categories: images/ (8 files),
  documents/ (6 files), code/ (5 files), data/ (3 files), misc/ (1 file).
Total credits: 2

What You Have Learned

In this quickstart you have:

1. Installed the OmniLink Python library
2. Configured authentication with your Omni Key
3. Created a local command engine with typed templates
4. Registered an agent profile on the cloud platform
5. Sent chat messages through multiple AI engines
6. Explored the TypeScript Web SDK
7. Run a ToolRunner session with the 1-credit architecture

Next Steps

• Architecture — Understand how the cloud API, local runtime, and transport layers work together.
• Use Cases — Explore robotics, smart home, industrial, and other integration patterns.
• API Reference — Full endpoint documentation for every REST route.
• Python Library Reference — Detailed docs for OmniLinkEngine, OmniLinkClient, ToolRunner, and bridges.