Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.praison.ai/llms.txt

Use this file to discover all available pages before exploring further.

Clone agents to give each channel, tenant, or session its own isolated instance — without losing config or hitting RLock pickling errors.

​
Quick Start

1

Single clone

from praisonaiagents import Agent

base = Agent(
    name="Support",
    instructions="You are a helpful support agent",
    llm="gpt-4o-mini",
)

# Get an isolated copy for one channel
telegram_agent = base.clone_for_channel()
2

Multiple clones for multi-channel deployment

from praisonaiagents import Agent

base = Agent(
    name="Support",
    instructions="You are a helpful support agent",
    llm="gpt-4o-mini",
    tools=["internet_search"],
    memory=True,
)

# Create isolated agents for each channel
telegram_agent = base.clone_for_channel()
discord_agent  = base.clone_for_channel()
slack_agent    = base.clone_for_channel()

​
How It Works

Agent cloning creates a fresh instance with the same configuration but isolated state.

​
What gets cloned vs. what’s reset

AttributeBehaviour in clone
name, role, goal, backstory, instructionsCopied as-is
llm, base_url, api_key, authCopied as-is
toolsShallow-copied (list(self.tools))
handoffsReset to None (channels should not share handoffs)
All feature configs: memory, knowledge, planning, reflection, guardrails, web, context, autonomy, output, execution, templates, caching, hooks, skills, approval, learn, sandboxForwarded from the stored _<name>_config attributes
tool_timeout, parallel_tool_calls, cli_backendForwarded
interrupt_controllerFresh instance (no cross-channel interference)
__cache_lock (threading.RLock)Fresh instance
_cost_lock (threading.Lock)Fresh instance

​
Common Patterns

​
Per-channel clone in a custom gateway

from praisonaiagents import Agent

def create_channel_agents(base_config):
    base = Agent(**base_config)
    
    return {
        'telegram': base.clone_for_channel(),
        'discord': base.clone_for_channel(),
        'slack': base.clone_for_channel()
    }

agents = create_channel_agents({
    'name': 'Support',
    'instructions': 'You are a helpful support agent',
    'llm': 'gpt-4o-mini'
})

​
Per-tenant clone in a multi-tenant API

from praisonaiagents import Agent

class TenantAgentManager:
    def __init__(self, base_agent):
        self.base = base_agent
        self.tenant_agents = {}
    
    def get_agent_for_tenant(self, tenant_id):
        if tenant_id not in self.tenant_agents:
            self.tenant_agents[tenant_id] = self.base.clone_for_channel()
        return self.tenant_agents[tenant_id]

base = Agent(name="Assistant", instructions="You are helpful")
manager = TenantAgentManager(base)

# Each tenant gets isolated agent
agent_a = manager.get_agent_for_tenant("tenant_a")
agent_b = manager.get_agent_for_tenant("tenant_b")

​
Use with copy.deepcopy

import copy
from praisonaiagents import Agent

agent = Agent(name="Test", instructions="You are a test agent")

# Both methods work - agent supports deepcopy now
clone1 = agent.clone_for_channel()  # Preferred for channels
clone2 = copy.deepcopy(agent)       # General Python compatibility

​
Best Practices

clone_for_channel() is the supported path for creating channel-safe clones. It’s optimized for multi-channel scenarios and properly handles handoffs. __deepcopy__ is provided for general Python compatibility but isn’t specifically designed for channel isolation.
Clone drops handoffs by design. Each channel should have independent routing logic. If you need cross-channel handoffs, implement them at the gateway level rather than the agent level.
If a tool holds mutable per-channel state, wrap it in a factory function or use instance-based tools. The clone shares tool instances with the original agent, which is usually fine for stateless tools.

Bot Gateway

Multi-channel gateway using agent cloning

Thread Safety

Agent thread safety and concurrency