Skip to main content
neutral

Phase 1: Durable Single-Agent Loop (MVP)

Status: Completed (2026-02-09)

Goal: A minimal agent that survives crashes, retries failures, and runs on Temporal.

Scope:

  • Core AgentRunWorkflow with deterministic loop
  • Activities: LLM decision, tool execution, observe
  • Immutable, versioned tool registry
  • Baseline observability (logs, metrics, OTEL spans)
  • Example project with 3 tools

Tasks and subtasks:

  1. Repository and runtime discovery
    • Identify language, build system, and Temporal SDK version
    • Locate existing app skeleton and config
    • Confirm how workers are started and deployed
  2. Core workflow
    • Define AgentRunInput and AgentConfig
    • Implement deterministic state machine loop (decide -> act -> observe -> repeat)
    • Implement stop conditions (max steps, goal achieved, timeouts, explicit halt)
    • Isolate non-determinism in activities
  3. Activities
    • LLMDecideActivity: accept current state, return structured decision
    • ToolExecuteActivity: strict schema validation, per-tool execution
    • ObserveActivity: update state from tool results
  4. Tool registry
    • Define ToolRegistry, ToolDefinition, versioning, content hash
    • Implement registry storage and lookup
    • Enforce immutability for published versions
  5. Observability
    • Workflow-level attributes (run ID, step count, state hash)
    • Activity-level metrics (latency, tokens, retries)
    • OTEL spans per decision cycle and tool call
  6. Example tools and sample agent
    • Implement http_get, calculator, key_value_store
    • Implement sample “research assistant” agent
    • Demonstrate retries, timeouts, clean shutdown
  7. Validation and test harness
    • Unit tests for decision loop and schema validation
    • Integration test that survives worker restart
    • Trace verification in dev environment

Deliverables:

  • AgentRunWorkflow and associated types
  • Activities for decision, tool execution, observation
  • Immutable tool registry
  • Sample agent + 3 tools
  • Observability instrumentation
  • Tests and minimal docs

Dev environment checks:

  • Start worker and run a sample agent
  • Confirm workflow survives worker restart
  • Verify activity retries with backoff
  • Confirm traces visible in Temporal UI/OTel backend

Run instructions:

  • See README.md for Phase 1 workflow run steps.

Dependencies:

  • Temporal cluster access
  • LLM provider credentials

Files to add/change (TBD after repo discovery) Initial scaffolding created:

  • cmd/worker/main.go
  • cmd/migrate/main.go
  • internal/agent/types.go
  • internal/agent/state.go
  • internal/agent/decision.go
  • internal/agent/activities.go
  • internal/agent/workflow.go
  • internal/config/config.go
  • internal/temporal/client.go
  • docker-compose.yml
  • .env.example
  • migrations/0001_init.up.sql
  • migrations/0001_init.down.sql