Praison AI

Multi-Agent Context Policies

Context isolation and sharing policies for multi-agent orchestration

python
from praisonaiagents import Agent

agent1 = Agent(name="agent-1", instructions="Handle research tasks.")
agent2 = Agent(name="agent-2", instructions="Handle writing tasks.")
agent1.start("Apply shared context policy across both agents.")

MultiAgentContextManager gives each agent isolated context with controlled sharing on handoffs.

The user hands off from a researcher agent to a writer; shared context policies control what crosses the boundary.

Diagram

🤖 Researcher

↔️ Handoff policy

🤖 Writer

📋 Shared summary

How It Works

Diagram
Multi-Agent Context PoliciesAgentUserMulti-Agent Context PoliciesAgentUserRequestProcess requestResult Agent–>>User: Response

Quick Start

  1. Create the manager
    python
    from praisonaiagents import MultiAgentContextManager

manager = MultiAgentContextManager()
researcher_ctx = manager.get_agent_manager("researcher")
writer_ctx = manager.get_agent_manager("writer")
  2. Set a handoff policy
    python
    from praisonaiagents import ContextPolicy, ContextShareMode

policy = ContextPolicy(
    share=True,
    share_mode=ContextShareMode.SUMMARY,
    max_tokens=5000,
)
manager.set_agent_policy("writer", policy)
  3. Prepare handoff context
    python
    shared = manager.prepare_handoff(
    from_agent="researcher",
    to_agent="writer",
    messages=researcher_messages,
)
result = writer_ctx.process(messages=shared + writer_messages)

Architecture

Diagram

Shared Context

Context Isolation

Multi-Agent Orchestrator

Policy: share_mode

Policy: share_mode

Agent 1: Researcher

Handoff

Agent 2: Writer

Handoff

Agent 3: Editor

Agent 1 Context
Isolated

Agent 2 Context
Isolated

Agent 3 Context
Isolated

Summary/Full
Based on Policy

Context Policy

Share Modes

ModeDescriptionUse Case
NONENo context sharedIndependent agents
SUMMARYSummarized contextReduce token usage
FULLFull context (bounded)Continuity needed

Tool Share Modes

ModeDescription
NONENo tools shared
SAFEOnly safe tools shared
FULLAll tools shared

Policy Configuration

python
from praisonaiagents import ContextPolicy, ContextShareMode

policy = ContextPolicy(
    share=True,                           # Enable sharing
    share_mode=ContextShareMode.SUMMARY,  # Share as summary
    max_tokens=5000,                      # Cap shared tokens
    tools_share=ToolShareMode.SAFE,       # Share safe tools
    preserve_system=True,                 # Keep system prompts
    preserve_recent_turns=3,              # Keep last 3 turns
)

Handoff Preparation

python
# Prepare context for handoff
shared_context = manager.prepare_handoff(
    from_agent="researcher",
    to_agent="writer",
    messages=researcher_messages,
    policy=policy,  # Optional override
)

# shared_context contains messages to pass to writer
writer_ctx = manager.get_agent_manager("writer")
result = writer_ctx.process(
    messages=shared_context + writer_messages,
    system_prompt=writer_system_prompt,
)

Per-Agent Isolation

Each agent has isolated:

  • Token budget
  • Conversation history
  • Optimization state
  • Monitoring output
python
# Each agent tracks independently
agent1_ctx.process(messages=agent1_messages)
agent2_ctx.process(messages=agent2_messages)

# Get combined stats
stats = manager.get_combined_stats()
print(f"Agent 1 tokens: {stats['agents']['researcher']['ledger']['total']}")
print(f"Agent 2 tokens: {stats['agents']['writer']['ledger']['total']}")

Preventing Context Blow-up

Default policies prevent multiplicative context growth:

python
# Default: no sharing
default_policy = ContextPolicy()  # share=False

# With sharing, always bounded
bounded_policy = ContextPolicy(
    share=True,
    share_mode=ContextShareMode.SUMMARY,  # Compressed
    max_tokens=5000,                       # Hard limit
    preserve_recent_turns=3,               # Only recent
)

Integration with Workflow

python
from praisonaiagents import AgentTeam
from praisonaiagents import MultiAgentContextManager

# Create context manager
ctx_manager = MultiAgentContextManager()

# Create agents with context awareness
agents = AgentTeam(
    agents=[researcher, writer, editor],
    process="sequential",
)

# Context is managed per-agent automatically
# Handoffs use configured policies

CLI Usage

bash
# View multi-agent context stats
praisonai run agents.yaml
> /context stats

# Shows per-agent breakdown

Best Practices

Default to isolation

Keep share=False until a handoff genuinely needs prior context — unbounded sharing multiplies tokens.

Prefer SUMMARY over FULL

ContextShareMode.SUMMARY keeps continuity without copying entire histories into every agent.

Always set max_tokens

Hard-cap shared context so downstream agents cannot inherit runaway message lists.

Preserve recent turns selectively

Use preserve_recent_turns=3 for continuity while still compressing older turns.

Related

Handoffs

Delegate tasks between agents with tool and context policies.

 Context Manager

Single-agent budgeting and compaction facade.

 Multi-Agent Pipelines

Sequential and parallel orchestration patterns.

 Workflows

Route, parallel, and loop patterns for agent teams.