Complete Workflow Example

A step-by-step walkthrough demonstrating SystemPrompt's architecture: Configure an agent, execute content creation, and review with analytics.

Last updated:

On this page

This walkthrough demonstrates the three architectural pillars working together:

Configure — Create and configure an agent using the CLI
Execute — Send tasks to the agent, watch it research and create
Review — Analyse performance with analytics, optimise based on data

This matches the terminal demo on our homepage. Every command is real and copy-pasteable.

Prerequisites

Before starting, ensure you have:

# Active session
systemprompt admin session show

# Expected output:
# Profile: local
# Tenant: your-tenant-id
# Status: authenticated

If not authenticated:

systemprompt cloud auth login
systemprompt admin session use local

Phase 1: Configure

Goal: Create a blog agent with content creation capabilities.

Step 1.1: Create the Agent

systemprompt admin agents create --name blog --port 9010

See systemprompt admin agents --help for all agent commands.

Expected output:

Agent created: blog
Port: 9010
Status: disabled

Step 1.2: Add Skills

Skills define what the agent can do:

# Research capability
systemprompt admin agents edit blog --skill research_content

# Content creation capability
systemprompt admin agents edit blog --skill content_create

Step 1.3: Connect MCP Server

MCP servers provide tools the agent can call:

systemprompt admin agents edit blog --mcp-server content-manager

Step 1.4: Validate Configuration

systemprompt admin agents validate blog

Expected output:

Validating agent: blog
─────────────────────────────────
Config:      ✓ Valid
Skills:      ✓ 2 skills attached
MCP servers: ✓ 1 server connected
OAuth scopes: ✓ Configured
─────────────────────────────────
Status: Ready to enable

Step 1.5: Enable the Agent

systemprompt admin agents edit blog --enable

Expected output:

Agent enabled: blog
Process started on port 9010
Registry: /api/v1/agents/registry

Step 1.6: Verify Agent is Running

systemprompt admin agents registry

Expected output:

Running Agents
─────────────────────────────────
blog        9010    enabled    healthy

Configuration Summary

# Full sequence (copy-paste ready)
systemprompt admin agents create --name blog --port 9010
systemprompt admin agents edit blog --skill research_content
systemprompt admin agents edit blog --skill content_create
systemprompt admin agents edit blog --mcp-server content-manager
systemprompt admin agents validate blog
systemprompt admin agents edit blog --enable

Phase 2: Execute

Goal: Have the agent research and write a blog post about MCP authentication.

Step 2.1: Read the Playbook

Before interacting with an agent, always read its playbook:

systemprompt core playbooks show content_blog

The playbook explains:

Required context setup
Expected conversation flow
Command syntax
Troubleshooting tips

Step 2.2: Create a Fresh Context

Every new task needs a fresh context:

systemprompt core contexts new --name "blog-mcp-authentication"

Expected output:

Context created: blog-mcp-authentication
ID: ctx_abc123
Status: active

Step 2.3: Start the Dialogue

The blog agent uses Socratic dialogue to refine your idea:

systemprompt admin agents message blog \
  -m "I want to write about MCP authentication. Most tutorials overcomplicate it. Let's define the goal." \
  --blocking

Expected response:

Agent (blog): Good topic. Before researching, let me understand:

1. What's your thesis? What specific claim are you making?
2. What's your contrarian angle? What does conventional wisdom get wrong?
3. What evidence do you have from production experience?
4. What will readers do differently after reading?

Step 2.4: Refine the Goal

Respond to the agent's questions:

systemprompt admin agents message blog \
  -m "THESIS: MCP auth is simpler than people think - OAuth2 is overkill for local dev.
CONTRARIAN: Everyone adds OAuth before they need it. Start with API keys, add OAuth later.
EVIDENCE: I've built 3 MCP servers - OAuth added 2 weeks to each project.
OUTCOME: Readers will ship their first MCP server in a day instead of a week." \
  --blocking --context-id ctx_abc123

Expected response:

Agent (blog): CONFIRMED CONTENT GOAL:
- Thesis: MCP auth simplicity - OAuth2 overkill for local
- Angle: Ship first, secure later
- Evidence: 3 production MCP servers
- Outcome: 1-day instead of 1-week time to ship

Ready to research. Say "Proceed with research" to continue.

Step 2.5: Research

systemprompt admin agents message blog \
  -m "Proceed with research." \
  --blocking --timeout 120 --context-id ctx_abc123

Expected response:

Agent (blog): Researching MCP authentication patterns...

→ research_content: Searching web
→ research_content: Found 7 relevant sources
→ research_content: Analysing patterns

Research complete.
research_id: res_xyz789
Sources: 7 articles, 2 docs, 1 specification

Ready to create content. Say "Create the blog post" with specifics.

Step 2.6: Create Content

systemprompt admin agents message blog \
  -m "Create the blog post using research. Use these specifics:
- slug: 'mcp-auth-simple'
- keywords: ['MCP', 'authentication', 'OAuth2', 'API keys', 'local development']
- Include code examples for both API key and OAuth approaches
- Reference the official MCP spec
- British English, 3500+ words minimum" \
  --blocking --timeout 300 --context-id ctx_abc123

Expected response:

Agent (blog): Creating content...

→ content_create: Structuring article
→ content_create: Writing sections
→ content_create: Adding code examples
→ content_create: Inserting citations

Content created.
content_id: cnt_def456
Title: "MCP Auth: Stop Overengineering It"
Words: 3,847
Citations: 7 inline links

Ready to publish.

Step 2.7: Publish

# Optimise images (converts PNG to WebP)
systemprompt infra jobs run blog_image_optimization

# Publish content
systemprompt infra jobs run publish_content

# Sync to filesystem
systemprompt cloud sync local content --direction to-disk --source blog -y

Step 2.8: Verify

systemprompt core content verify --slug mcp-auth-simple --base-url https://yourdomain.com

Expected output:

Content verification: mcp-auth-simple
─────────────────────────────────
Database:    ✓ Found
Filesystem:  ✓ Synced
Frontmatter: ✓ Valid
Word count:  3,847 (min: 3,500 ✓)
Citations:   7 (min: 5 ✓)
Images:      ✓ Optimised
URL:         https://yourdomain.com/blog/mcp-auth-simple
Status:      ✓ Published

Execution Summary

# Full sequence (copy-paste ready)
systemprompt core playbooks show content_blog
systemprompt core contexts new --name "blog-mcp-authentication"
systemprompt admin agents message blog \
  -m "I want to write about MCP authentication..." \
  --blocking
systemprompt admin agents message blog \
  -m "THESIS: MCP auth is simpler than people think..." \
  --blocking --context-id ctx_abc123
systemprompt admin agents message blog \
  -m "Proceed with research." \
  --blocking --timeout 120 --context-id ctx_abc123
systemprompt admin agents message blog \
  -m "Create the blog post using research..." \
  --blocking --timeout 300 --context-id ctx_abc123
systemprompt infra jobs run blog_image_optimization
systemprompt infra jobs run publish_content
systemprompt cloud sync local content --direction to-disk --source blog -y
systemprompt core content verify --slug mcp-auth-simple

Phase 3: Review

Goal: Analyse content performance and optimise the agent based on data.

Step 3.1: Content Analytics

systemprompt analytics content stats

Expected output:

Content Analytics (last 30 days)
─────────────────────────────────
Total views:      12,847
Unique visitors:  8,392
Avg time on page: 3m 42s
Bounce rate:      18%

Top performing:
  1. mcp-auth-simple      1,247 views  4m 32s  23% bounce
  2. rust-performance     892 views    3m 18s  15% bounce
  3. agent-architecture   743 views    5m 01s  12% bounce

Step 3.2: Agent Analytics

systemprompt analytics agents show blog

Expected output:

Agent: blog
─────────────────────────────────
Success rate:     94%
Avg latency:      12.3s
Total cost:       $4.30 (10 tasks)
Avg cost/task:    $0.43

Top skills used:
  research_content  45 calls
  content_create    12 calls
  generate_image    8 calls

Recent tasks:
  ✓ mcp-auth-simple      3,847 words  $0.52
  ✓ rust-performance     4,102 words  $0.48
  ✗ agent-mesh (timeout)             $0.31

Step 3.3: Cost Analytics

systemprompt analytics costs breakdown --by agent

Expected output:

Cost Breakdown by Agent (last 30 days)
─────────────────────────────────
blog         $4.30   (10 tasks, $0.43/task)
research     $1.20   (15 queries, $0.08/query)
support      $0.85   (22 messages, $0.04/msg)
─────────────────────────────────
Total:       $6.35

Step 3.4: Identify Optimisation Opportunities

From the analytics:

mcp-auth-simple has 23% bounce (higher than average)
The agent-mesh task timed out
Research skill is efficient at $0.08/query

Step 3.5: Investigate High Bounce Rate

systemprompt analytics traffic devices

Expected output:

Device Breakdown
─────────────────────────────────
Desktop:     62%    16% bounce
Mobile:      35%    34% bounce  ← Problem!
Tablet:      3%     12% bounce

Mobile bounce rate is double desktop. The content may not be mobile-friendly.

Step 3.6: Update Playbook

Based on findings, update the blog playbook:

# View current playbook
systemprompt core playbooks show content_blog

# Edit the playbook file
# Add to requirements: "Include mobile-friendly code blocks"
# Add to checklist: "Verify code examples render on mobile"

# Sync changes
systemprompt core playbooks sync --direction to-db -y

Step 3.7: Fix the Timeout Issue

The agent-mesh task timed out. Increase timeout for complex tasks:

# Check agent configuration
systemprompt admin agents show blog

# For long research tasks, use longer timeout
systemprompt admin agents message blog \
  -m "Research agent mesh patterns (complex topic)" \
  --blocking --timeout 300

Step 3.8: Verify Improvements

After implementing changes, track improvement:

# Check trends over time
systemprompt analytics agents trends --days 14

# Compare before/after
systemprompt analytics content trends --days 30

Review Summary

# Full sequence (copy-paste ready)
systemprompt analytics content stats
systemprompt analytics agents show blog
systemprompt analytics costs breakdown --by agent
systemprompt analytics traffic devices
systemprompt core playbooks show content_blog
# (edit playbook)
systemprompt core playbooks sync --direction to-db -y
systemprompt analytics agents trends --days 14

Complete Workflow Reference

Phase 1: Configure (One-time setup)

# Create agent
systemprompt admin agents create --name blog --port 9010

# Add capabilities
systemprompt admin agents edit blog --skill research_content
systemprompt admin agents edit blog --skill content_create
systemprompt admin agents edit blog --mcp-server content-manager

# Validate and enable
systemprompt admin agents validate blog
systemprompt admin agents edit blog --enable

Phase 2: Execute (Per-task)

# Prepare
systemprompt core playbooks show content_blog
systemprompt core contexts new --name "blog-{topic}"

# Dialogue
systemprompt admin agents message blog -m "Topic and goals" --blocking
systemprompt admin agents message blog -m "Refine goals" --blocking --context-id {ctx}

# Research and create
systemprompt admin agents message blog -m "Proceed with research" --blocking --timeout 120 --context-id {ctx}
systemprompt admin agents message blog -m "Create content" --blocking --timeout 300 --context-id {ctx}

# Publish
systemprompt infra jobs run blog_image_optimization
systemprompt infra jobs run publish_content
systemprompt cloud sync local content --direction to-disk --source blog -y
systemprompt core content verify --slug {slug}

Phase 3: Review (Regular)

# Performance
systemprompt analytics content stats
systemprompt analytics agents show blog
systemprompt analytics costs breakdown --by agent

# Optimise
systemprompt analytics traffic devices
systemprompt core playbooks show content_blog
# (update playbook based on findings)
systemprompt core playbooks sync --direction to-db -y

Troubleshooting

Issue	Solution
Agent not responding	`systemprompt admin agents status blog` then `systemprompt infra services restart agent blog`
Context contamination	Create NEW context: `systemprompt core contexts new --name "blog-{new-topic}"`
Content not created	Verify with `systemprompt core content show --slug {slug}`. Agent may claim success falsely.
Timeout on long tasks	Use `--timeout 300` or `--timeout 600` for research-heavy tasks
High bounce rate	Check `systemprompt analytics traffic devices`, update playbook for mobile
Cost too high	Check `systemprompt analytics costs breakdown --by model`, consider smaller models

Next Steps

Architecture — Architecture overview
GitHub CLI Reference — CLI command reference
Features — Full capability list
Deploying — Production deployment

Previous	Next
Building MCP Servers	Authentication