Overview
Shannon uses Temporal as its workflow engine, providing durable, deterministic execution that survives service restarts and can be replayed for debugging.
Architecture
Workflow Types
Shannon implements several workflow types for different use cases:
OrchestratorWorkflow
The main entry point that routes queries to appropriate strategy workflows based on complexity analysis.
Strategy Workflows
| Workflow | Best For | Patterns Used |
|---|
| DAGWorkflow | Multi-step tasks with clear subtasks | Parallel/Sequential + Reflection |
| ReactWorkflow | Tool-using tasks, iterative solving | Reason-Act-Observe loops |
| ResearchWorkflow | Information gathering, synthesis | React or Parallel + Reflection |
| ExploratoryWorkflow | Open-ended discovery | Tree-of-Thoughts + Debate |
| ScientificWorkflow | Hypothesis testing | CoT + Debate + ToT + Reflection |
SupervisorWorkflow
Advanced workflow for dynamic team management with agent recruitment and retirement.
ScheduledTaskWorkflow
Wrapper workflow for recurring task execution via cron schedules.
Workflow Selection Logic
Reasoning Patterns
Shannon composes these patterns within workflows:
Chain-of-Thought (CoT)
Step-by-step reasoning with confidence tracking for complex problems.
Tree-of-Thoughts (ToT)
Systematic exploration with branching and pruning for problems with multiple solution paths.
ReAct
Reason-Act-Observe loops with tool integration for iterative problem solving.
Debate
Multi-agent debate for exploring perspectives and strengthening answers.
Reflection
Iterative quality improvement through self-evaluation.
Execution Patterns
Parallel Execution
- Concurrent agent execution with semaphore control
- Configurable concurrency limits
- Result aggregation
Sequential Execution
- Step-by-step execution with result passing
- Context accumulation between steps
Hybrid (DAG) Execution
- Dependency graph execution with topological sorting
- Combines parallel and sequential based on dependencies
Configuration
Workflow Options
type WorkflowConfig struct {
ExploratoryMaxIterations int // Max exploration rounds
ExploratoryConfidenceThreshold float64 // Confidence target
ScientificMaxHypotheses int // Number of hypotheses
ScientificMaxIterations int // Max testing rounds
}
Environment Variables
| Variable | Default | Description |
|---|
TEMPORAL_HOST | temporal:7233 | Temporal server address |
AGENT_TIMEOUT_SECONDS | 600 | Agent execution timeout |
DECOMPOSE_TIMEOUT_SECONDS | 30 | Task decomposition timeout |
Temporal UI
Access the Temporal UI at http://localhost:8088 for:
- Workflow Visualization: See workflow execution graphs
- Execution History: Full event history for each workflow
- Replay Debugging: Step through workflow execution
- Worker Status: Monitor worker health and task queues
Deterministic Replay
Temporal ensures workflows are deterministic:
All workflow code must be deterministic - no random numbers, current time, or external calls directly in workflow code. Use activities for non-deterministic operations.
Version Gates
Shannon uses version gates for backward-compatible changes:
v := workflow.GetVersion(ctx, "memory_retrieval_v1", workflow.DefaultVersion, 1)
if v >= 1 {
// New memory retrieval logic
}
Token Budget Management
All workflows respect token budgets through:
- Middleware: Budget enforcement at workflow entry
- Pattern Options:
BudgetAgentMax field limits per-agent tokens
- Activity Budgets: Controlled execution with budget tracking
Best Practices
When to Use Each Mode
| Mode | Use Case | Example |
|---|
simple | Direct questions | ”What is 2+2?” |
standard | Multi-step tasks | ”Summarize this document” |
complex | Deep analysis | ”Compare frameworks” |
supervisor | Dynamic teams | ”Research and implement” |
Pattern Selection
- Use Reflection when quality matters more than speed
- Use Chain-of-Thought for explicit reasoning steps
- Use Debate when multiple perspectives strengthen answers
- Use Tree-of-Thoughts for complex problems with multiple paths
- Use React when environmental feedback is needed
Monitoring
Prometheus Metrics
shannon_workflow_duration_seconds - Workflow execution timeshannon_workflow_status - Success/failure countsshannon_activity_duration_seconds - Activity execution time
OpenTelemetry Tracing
Distributed tracing spans across:
- Workflow execution
- Activity calls
- Agent invocations
- LLM requests
Next Steps
