FAQ

Getting Started

What is OmniLink?

OmniLink is an AI agent platform that combines cloud-hosted intelligence with local tool execution. It provides a REST API and a Python library for building autonomous agents that can control real-world systems — robots, IoT devices, smart homes, and more — while keeping API costs minimal through its 1-credit architecture.

How do I get an Omni Key?

Sign up at omnilink-agents.com, then navigate to Settings > API Keys in the Dashboard. Click Generate Key. The key (prefixed with omk_) is displayed once — copy and store it securely in an environment variable.

What programming languages are supported?

OmniLink provides first-class support for Python via pip install omnilink — a full library with OmniLinkEngine, ToolRunner, bridges, and client.

Since OmniLink exposes a standard REST API, you can integrate from any language that supports HTTP requests — TypeScript / JavaScript, Go, Rust, Java, C#, Ruby, and others.

Is there a free tier?

OmniLink does not currently offer a permanent free tier. However, the Bronze plan provides an affordable entry point for personal projects and prototyping. New accounts may receive introductory credits — check the Dashboard for current promotions.

How do I install the Python library?

# From PyPI (when published)
pip install omnilink

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

Requires Python 3.9 or later. It is recommended to use a virtual environment:

python -m venv .venv
source .venv/bin/activate   # macOS/Linux
.venv\Scripts\activate      # Windows
pip install omnilink        # or: pip install -e path/to/omnilink-lib

Agents and Configuration

What is an agent profile?

An agent profile is a named configuration that defines your agent’s behavior. It includes system instructions (the agent’s persona and rules), the selected AI engine, available commands, voice settings, knowledge base preferences, and operational mode. You can create multiple profiles and switch between them.

How many agents can I create?

There is no hard limit on the number of agent profiles. You can create as many as your use case requires. Each profile is stored independently and can be configured with different engines, system instructions, and settings.

How do I change my agent’s AI model?

In the Dashboard, open your agent profile and select a different engine from the AI Engine dropdown. Options include:

• g1-engine — Gemini
• g2-engine — GPT
• g3-engine — Grok
• g4-engine — Claude

You can also set the engine per request in the API by specifying the engine parameter. No code changes are needed to switch models.

What are available commands?

Available commands are a list of command templates that your agent can execute. They are defined using the OmniLinkEngine template syntax with typed variables. When you configure available commands in the Dashboard, the AI knows exactly what actions it can dispatch to your local runtime.

# Example command templates
"move [direction:str] [distance:int] meters"
"turn [room:str] lights [state:str]"
"set thermostat to [temp:int] degrees"
"read [sensor:str] sensor"

How do system instructions work?

System instructions are a block of text that defines your agent’s persona, rules, and behavior. They are sent to the AI engine as a system message on every request, so the model always has context about how to behave. System instructions should define:

• The agent’s role and personality
• Rules and constraints (what the agent should and should not do)
• Response format preferences
• Domain-specific context

Keep them concise — longer instructions consume more input tokens on every request.

API and Integration

What AI models are available?

OmniLink provides four AI engines, each powered by a leading foundation model:

How does conversation memory work?

OmniLink provides two memory systems:

• Short-term memory (/api/short-term-memory) — Stores the conversation history for the current session. Messages are automatically included as context in subsequent requests. Cleared when the session is reset.
• Long-term memory (/api/long-term-memory) — Persistent key-value storage that survives across sessions. Use it for user preferences, learned facts, and configuration that the agent should always remember.

Can I use OmniLink from a mobile app?

Yes. The CORS policy explicitly allows capacitor:// and ionic:// origins, so hybrid frameworks like Capacitor and Ionic can call the REST API directly. You can also call the REST API from native Swift, Kotlin, or Flutter code.

How do I stream responses?

The Chat API supports streaming via Server-Sent Events (SSE). Set the stream parameter to true in your request:

# Python streaming
response = client.chat(
    message="Explain quantum computing",
    stream=True,
)
for chunk in response:
    print(chunk, end="", flush=True)

// TypeScript streaming
const stream = await client.chat({
  message: "Explain quantum computing",
  stream: true,
});

for await (const chunk of stream) {
  process.stdout.write(chunk);
}

What is the knowledge system?

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

ToolRunner

What is the ToolRunner?

The ToolRunner is OmniLink’s framework for cloud-orchestrated local tool execution. You subclass ToolRunner in Python, implement methods for getting state, executing actions, and checking completion. The cloud AI handles high-level reasoning while your local code handles the actual execution — all for a fixed credit cost.

How many credits does a ToolRunner session cost?

A minimal session costs 2 credits: 1 for the kickoff and 1 for the final analysis. If periodic reviews are enabled, each review adds 1 credit. A typical 30-minute session costs 1–2 credits. Even an hour-long session with multiple reviews rarely exceeds 5 credits.

Can ToolRunner control physical hardware?

Yes. The ToolRunner runs on your local machine, so it has direct access to any hardware connected to that machine — serial ports, GPIO pins, USB devices, network-connected robots, and more. The cloud AI decides what to do; your local code decides how to do it.

def execute_action(self, action: str) -> str:
    if action == "read_temperature":
        # Direct hardware access on the local machine
        temp = self.sensor.read()
        return f"Temperature: {temp}°C"

How long can a ToolRunner session last?

There is no hard time limit on ToolRunner sessions. Sessions run as long as your local process remains active and the is_game_over() method returns False. Sessions lasting hours are feasible and still cost-efficient due to the fixed-credit model.

Billing and Usage

How does billing work?

OmniLink uses a monthly subscription model processed through Stripe. You choose a plan tier (Bronze, Silver, Gold, or Diamond), and you receive a monthly credit allocation. Usage is tracked in real time and deducted from your balance. See the Usage Management page for full details.

What happens when I run out of credits?

When your credit balance reaches zero, API requests return a 402 Payment Required error. You can either wait for the next billing cycle (credits reset automatically) or upgrade to a higher plan for an immediate credit boost. Active ToolRunner sessions in progress are allowed to complete their current action before being paused.

Can I upgrade my plan mid-cycle?

Yes. Upgrades take effect immediately. Stripe prorates the cost for the remainder of your billing cycle, and your new credit allocation is applied instantly. There is no downtime during the transition.

How do I cancel my subscription?

Navigate to Settings > Billing in the Dashboard and click Cancel Subscription. Your plan remains active until the end of the current billing cycle. Data is retained for 30 days after expiration, then may be permanently deleted.

Troubleshooting

Why does my agent return “none” for commands?

The OmniLinkEngine returns "none" when no registered command template matches the input. Common causes:

• Typo in the command template — Verify that the template string exactly matches expected input patterns.
• Missing type registration — If you use custom types (e.g., [state:lock_state]), make sure you called engine.register_type() before parsing.
• Type mismatch — If a variable expects int but receives a word, the match fails. Check that user input matches the expected variable types.

# Debug command matching
result = engine.parse("turn living room lights on")
if result.matched:
    print(f"Matched: {result.template}")
    print(f"Variables: {result.variables}")
else:
    print("No match. Registered templates:")
    for cmd in engine.get_available_commands():
        print(f"  {cmd}")

Why is my memory not persisting?

Check which memory system you are using:

• Short-term memory is session-scoped. It resets when you call the reset endpoint or start a new session. This is expected behavior.
• Long-term memory persists across sessions. If it appears to be lost, verify that you are using the same Omni Key and agent profile. Memory is scoped to the key and profile combination.

How do I fix CORS errors?

CORS errors typically occur when making requests from a browser. Solutions:

1. Use a backend proxy (recommended) — Route API calls through your own server so the browser never makes cross-origin requests to OmniLink directly.
2. Check your origin — localhost (any port), capacitor://, and ionic:// are allowed. Other origins are allowed with standard wildcard CORS.
3. Verify HTTPS — Mixed-content requests (HTTP page calling HTTPS API) are blocked by browsers regardless of CORS headers.
4. Check the request method — Ensure your preflight (OPTIONS) request is not being blocked by a firewall or proxy.

Why am I getting rate limited?

Rate limits are enforced per Omni Key based on your plan tier. When you receive a 429 Too Many Requests response:

1. Check the Retry-After header and wait the indicated number of seconds.
2. Implement exponential backoff in your client code.
3. Review your request patterns — batching multiple operations into fewer requests can help.
4. Consider upgrading to a higher plan tier for increased rate limits.

import time
import requests

def call_with_retry(url, headers, payload, max_retries=3):
    for attempt in range(max_retries):
        response = requests.post(url, headers=headers, json=payload)
        if response.status_code == 429:
            retry_after = int(response.headers.get("Retry-After", 5))
            print(f"Rate limited. Retrying in {retry_after}s...")
            time.sleep(retry_after)
            continue
        return response
    raise Exception("Max retries exceeded")

Why is my ToolRunner session not starting?

Common causes for ToolRunner startup failures:

• Missing OMNI_KEY — Ensure the OMNI_KEY environment variable is set and valid.
• Insufficient credits — The kickoff requires at least 1 credit. Check your balance.
• Concurrent session limit — You may have reached the maximum concurrent ToolRunner sessions for your plan. Wait for an existing session to complete or upgrade your plan.

How do I debug API errors?

All OmniLink API errors return a JSON body with an error code and a human-readable message. Common error codes:

How do I report a bug or request a feature?

Use the Support section in the Dashboard to submit bug reports or feature requests. Include the following information for fastest resolution:

• Your Omni Key prefix (e.g., omk_abc...) — never share the full key.
• The endpoint or SDK method that failed.
• The full error response (status code, error body).
• Steps to reproduce the issue.
• Your platform (Python version, Node.js version, OS).