Architecture
How Zgent's components fit together.
Zgent sits between your application and AI agent execution engines. It handles scheduling, state, and coordination so you can focus on what the agent should do.
┌─────────────────────────────────────────────────────────────┐
│ Your application │
└────────────────────────┬────────────────────────────────────┘
│
┌────────────────────────▼────────────────────────────────────┐
│ Zgent SDK │
│ ┌─────────────┐ ┌──────────────┐ ┌────────────────────┐ │
│ │ Channels │ │ Context │ │ Hooks & Tools │ │
│ │ (When) │ │ (State) │ │ (Extend & Control)│ │
│ └─────────────┘ └──────────────┘ └────────────────────┘ │
│ ┌─────────────┐ ┌──────────────┐ │
│ │ Dispatcher │ │ Agent │ │
│ │ (Route) │ │ (Define) │ │
│ └─────────────┘ └──────────────┘ │
└────────────────────────┬────────────────────────────────────┘
│
┌────────────────────────▼────────────────────────────────────┐
│ Agent execution engines │
│ Claude Code SDK │ Codex │ Future providers │
└─────────────────────────────────────────────────────────────┘Message flow
When a message enters Zgent, it follows this path:
Channel receives a message
A Channel (HTTP, WebSocket, Cron, etc.) produces a UserMessage and places it in the Context's receive queue.
Context broadcasts to definitions
The Context passes the message through each registered AgentDefinition's inbound handler. A handler can accept, transform, or drop the message.
Dispatcher routes to an instance
The definition's Dispatcher decides which agent instance should handle the message by returning a session key and action (route, create, or drop).
Agent processes the message
The Agent instance sends the message to the execution engine (e.g., Claude). The engine streams back text, tool calls, and a final result.
Output flows through senders
Agent output passes through the definition's outbound handler, then gets sent to all registered senders (channels).
Key design decisions
Don't re-invent the agent. Zgent wraps battle-tested engines like Claude Code SDK instead of reimplementing LLM orchestration, tool execution, or reasoning loops.
Proactive by default. Channels enable agents that act on schedules, events, and webhooks — not only user messages.
State is first-class. Context manages conversation history, snapshots, and token budgets across sessions. Agent instances persist state between turns.
Hooks for control. Intercept any point in the agent lifecycle (before/after tool use, on error, on exit) without modifying core logic.