Core Concepts
Agents
Define agent behavior with AgentDefinition and manage instances with AgentContext.
AgentDefinition
An AgentDefinition is a template that describes how to create agent instances. It specifies the system prompt, engine, tools, hooks, and routing logic.
from zgent import AgentDefinition, AgentEngine, AgentOptions, Dispatcher, DispatchResult, DispatchAction
definition = AgentDefinition(
system_prompt="You are a code review assistant.",
engine_type=AgentEngine.CLAUDE,
dispatcher=Dispatcher(
lambda msg: DispatchResult(key=msg.session_id, action=DispatchAction.ROUTE)
),
options=AgentOptions(
prefix="reviewer",
streaming=True,
allowed_tools=["Read", "Grep", "Glob"],
),
)| Parameter | Description |
|---|---|
system_prompt | Instructions for the agent |
engine_type | Which execution engine to use (AgentEngine.CLAUDE) |
dispatcher | Routes messages to agent instances |
options | Engine-specific options (model, tools, streaming) |
tools | Custom tools the agent can call |
hooks | Lifecycle hooks (before/after tool use, etc.) |
subagents | Nested agent definitions for hierarchical composition |
inbound | Filter or transform incoming messages |
outbound | Filter or transform outgoing messages |
AgentOptions
AgentOptions configures engine behavior:
from zgent import AgentOptions
options = AgentOptions(
prefix="my-agent",
model="claude-sonnet-4-20250514",
streaming=True,
allowed_tools=["Read", "Write", "Bash"],
disallowed_tools=["WebSearch"],
)Message handlers
Inbound and outbound handlers let you filter or transform messages without modifying the agent logic:
from zgent.message import Message
def inbound_filter(msg: Message) -> Message | None:
"""Only accept messages from allowed sessions."""
if msg.session_id.startswith("admin-"):
return msg
return None # drop
definition = AgentDefinition(
system_prompt="Admin assistant.",
engine_type=AgentEngine.CLAUDE,
inbound=inbound_filter,
)SubAgents
Agents can delegate work to sub-agents for complex workflows:
from zgent import SubAgentDefinition
definition = AgentDefinition(
system_prompt="You are a project manager. Delegate coding tasks to your sub-agent.",
engine_type=AgentEngine.CLAUDE,
subagents={
"coder": SubAgentDefinition(
description="Use for focused implementation tasks that need code changes.",
system_prompt="You are a coding assistant.",
model="sonnet",
),
},
)AgentContext
When a message arrives for a new session key, Zgent creates an Agent instance with its own AgentContext. The context tracks:
- Conversation history
- Token usage and budgets
- Snapshot state for persistence
- The current agent lifecycle phase