Five-Layer Agent Stack
The five layers every agent has — and which PraisonAI parameter lives at each
Every agent has five layers. When one misbehaves, the layer tells you where to look.
| Layer | The question it answers | PraisonAI |
|---|---|---|
| 1 · Prompt | Did I say it clearly? | instructions=, role/goal/backstory, output=, templates= |
| 2 · Context | Is the right thing in the window? | memory=, knowledge=, context=, handoff ContextPolicy |
| 3 · Harness | Can it act, and be checked? | tools=, MCP(), guardrails=, approval=, hooks=, sandbox= |
| 4 · Loop | When do we stop? | execution=ExecutionConfig(...), autonomy=, doom-loop detection |
| 5 · Graph | Who runs when, and who checks whom? | AgentFlow, route(), parallel(), loop(), repeat() |
| ⬡ Managed | Where does it actually run? | run_on= on AgentFlow / AgentTeam (or run_on: docker at the top of an agents.yaml / workflow.yaml) to share one sandbox across a run, or compute= on a LocalAgent for one agent’s tools. See Placement. |
Quick tour of all five layers
- Layer 1 · Prompt
Say it clearly — role, instructions, output format.
- Layer 2 · Context
Put the right thing in the window — memory, knowledge, compression.
- Layer 3 · Harness
Let it act and check it — tools, guardrails, approval.
- Layer 4 · Loop
Decide when to stop — iteration caps, budgets, completion checks.
- Layer 5 · Graph
Wire agents together — routing, parallelisation, orchestration.
The five layers in depth
Layer 1 · Prompt — Did I say it clearly?
Role, instructions, examples, output format.
from praisonaiagents import Agent
agent = Agent(
role="Senior Data Analyst",
goal="Turn raw numbers into decisions",
output="verbose", # markdown-formatted output
)
agent.start("Summarise Q3 revenue trends")Layer 2 · Context — Is the right thing in the window?
Write, select, compress, isolate — the four context operations, one parameter each.
from praisonaiagents import Agent
agent = Agent(
instructions="You are a support engineer.",
memory={"user_id": "u-42"}, # write — persists across runs (needs a user_id)
knowledge=["docs/"], # select — retrieves only what's relevant
context="summarize", # compress — auto-compacts before the limit
)Layer 3 · Harness — Can it act, and be checked?
Agent = Model + Harness. Tool dispatch, plus the guides that steer before acting and the sensors that observe after.
from praisonaiagents import Agent, MCP, tool
@tool
def deploy(env: str) -> str:
"""Deploy the current build to an environment."""
return f"Deployed to {env}"
agent = Agent(
name="ReleaseEngineer",
instructions="You are a release engineer.",
tools=[deploy, MCP("npx -y @modelcontextprotocol/server-filesystem /tmp")],
approval=True, # guide — human gate before risky tools run
)
agent.start("Deploy to staging, then list the files you can read")Learn more: Tools, MCP, Guardrails, Approval, Hooks.
Layer 4 · Loop — When do we stop?
Hard iteration caps, budget ceilings, no-progress detection and completion checks — every brake is explicit.
from praisonaiagents import Agent, ExecutionConfig
agent = Agent(
instructions="Fix the failing tests.",
execution=ExecutionConfig(max_iter=30, max_budget=0.50, on_budget_exceeded="stop"),
autonomy=True, # required to drive the loop with run_autonomous()
)
result = agent.run_autonomous("Refactor the auth module", max_iterations=5)
print(result.completion_reason)
# goal | no_tool_calls | max_iterations | timeout | doom_loop | needs_help | error
# (with on_budget_exceeded="stop", hitting the cap raises BudgetExceededError,
# surfaced here as completion_reason="error")Learn more: Execution, Reflection, Autonomy, Budget, Doom-Loop Detection.
Layer 5 · Graph — Who runs when, and who checks whom?
Topology as a versionable artifact: prompt chaining, routing, parallelisation, orchestrator-worker.
from praisonaiagents import AgentFlow, route, parallel, repeat
flow = AgentFlow(steps=[
classifier,
route({"bug": [bug_agent], "feature": [feature_agent], "default": [triage]}),
parallel([reviewer, tester]), # fan out, join automatically
repeat(editor, until=lambda ctx: "approved" in ctx.previous_result.lower(),
max_iterations=3), # evaluator–optimizer
])
flow.run("Ticket #123: login fails on Safari")Learn more: AgentFlow, Conditions, Process.
⬡ Outside the stack: Managed Agents — Where does it actually run?
The harness is commoditising; where the agent executes is the next multiplier. Rather than burning your laptop’s CPU, hand an agent a short-lived cloud sandbox — repo, tools and tests run there.
from praisonai import Agent, ManagedAgent, LocalManagedConfig
# A. Tools run in a remote sandbox; the agent loop stays local
sandboxed = ManagedAgent(
provider="local", compute="e2b", # or modal | daytona | flyio | docker | tenki | local
config=LocalManagedConfig(model="gpt-4o-mini", name="RemoteTools"),
)
agent = Agent(name="builder", backend=sandboxed)
# B. The entire agent loop runs in the cloud (needs ANTHROPIC_API_KEY;
# with no key set, ManagedAgent() falls back to a local loop)
agent = Agent(name="teacher", backend=ManagedAgent())
agent.start("Write a Python script that prints the first 10 primes, then run it")Learn more: Managed Agents, E2B, Modal, Daytona, Docker, Local.
Which layer is my bug in?
Related
Role, instructions, and output format.
Layer 2 · ContextMemory, knowledge, and compression.
Layer 3 · HarnessTools, guardrails, and approval.
Layer 4 · LoopIteration caps, budgets, and completion checks.
Layer 5 · GraphRouting, parallelisation, and orchestration.
⬡ Managed AgentsWhere the agent actually runs.