Getting Started

Teleon is a production-ready platform for building, deploying, and managing AI agents. The Python library is the main integration surface (via TeleonClient and the @client.agent(...) decorator), while Cortex, Sentinel, and Helix can be enabled per-agent as needed.

How the pieces fit together

1) Installation

pip install teleon

API key

API keys must follow one of these formats:

• tlk_live_xxx (production)
• tlk_test_xxx (test)
• teleon_xxx (legacy)

You can provide the key explicitly when constructing TeleonClient, or via environment variables (recommended for production deployments).

export TELEON_API_KEY="tlk_live_xxx"

$env:TELEON_API_KEY = "tlk_live_xxx"

set TELEON_API_KEY=tlk_live_xxx

Optional environment variables:

2) Create your first agent

from teleon import TeleonClient
 
client = TeleonClient(api_key="tlk_live_xxx")
 
@client.agent(name="support", model="gpt-4")
async def support_agent(query: str):
    return "ok"

You can also configure the client for different environments or networking setups (for example, environment, base_url, and verify_key).

Agent functions must be async def and should return a value.

3) Define a tool

Tools are async callables that your agents can invoke.

For production, consider setting timeouts on agents and tools to prevent hanging requests.

from teleon import tool
 
@tool(name="echo", category="utility")
async def echo(text: str) -> str:
    return text

The SDK supports optional parameters like timeout (agents and tools) and cache_ttl (tools) for production safety and performance.

4) Configure core systems

Cortex (memory)

Cortex provides persistent, searchable memory with a small set of core methods (store, search, get, update, delete, count). It supports production features like scope enforcement (multi-tenancy) and auto-context injection.

@client.agent(name="support", cortex=True)
async def support_agent(query: str, customer_id: str, cortex):
    await cortex.store(content=f"Customer asked: {query}", customer_id=customer_id)
    return "ok"

For multi-tenant apps, prefer configuring Cortex with a mandatory scope (for example, customer_id) so memories remain isolated per tenant.

Sentinel (safety)

Sentinel validates inputs before execution and outputs after execution. Enable it for user-facing agents to add guardrails like content filtering and PII detection.

If Sentinel blocks execution (for example with action_on_violation: "block"), it raises an AgentValidationError.

@client.agent(
    name="support",
    sentinel={
        "content_filtering": True,
        "pii_detection": True,
        "action_on_violation": "block",
    },
)
async def support_agent(query: str):
    return "ok"

Helix (runtime)

Helix is Teleon’s production runtime system for running agents reliably, with resource limits, health checks, and scaling. It also includes LLM runtime features like token tracking and cost / budget management.

@client.agent(
    name="support",
    helix={
        "min_instances": 1,
        "max_instances": 10,
        "memory_limit_mb": 512,
    },
)
async def support_agent(query: str):
    return "ok"

5) Deploy

Use Helix configuration to run agents reliably in production, with health checks, scaling, and resource limits.

If you’re starting simple, deploy with conservative values (for example, low max_instances and explicit memory_limit_mb), then scale up as you observe real traffic.

6) Monitor

Helix provides health endpoints and metrics reporting hooks for production monitoring.

7) Error handling

In production, handle validation and runtime failures explicitly.

import asyncio
 
from teleon.core import TeleonError, AgentExecutionError, AgentValidationError, LLMRateLimitError
 
try:
    result = await support_agent("hello")
except LLMRateLimitError as e:
    await asyncio.sleep(e.retry_after)
    result = await support_agent("hello")
except AgentValidationError as e:
    # Sentinel blocked input/output
    raise
except AgentExecutionError as e:
    # Agent runtime failure
    raise
except TeleonError as e:
    # Any Teleon SDK error
    raise