Skip to main content

​
Your First Task

Let’s submit a simple task to Shannon and see it in action. This guide assumes you’ve completed the installation.

​
Using the REST API

The simplest way to interact with Shannon is through its REST API: 
curl -X POST http://localhost:8080/api/v1/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Analyze the sentiment of: Shannon makes AI agents simple and reliable!"
  }'
You’ll receive a response like: 
{
  "task_id": "task-dev-1730000000",
  "status": "TASK_STATUS_RUNNING",
  "message": "Task submitted",
  "created_at": "2024-10-22T10:30:00Z"
}

​
Check Task Status

Use the task_id to check the status: 
curl http://localhost:8080/api/v1/tasks/task-dev-1730000000
Response: 
{
  "task_id": "task-dev-1730000000",
  "status": "TASK_STATUS_COMPLETED",
  "response": { "result": "The sentiment is overwhelmingly positive..." },
  "error": "",
  "query": "Analyze the sentiment of: Shannon makes AI agents simple and reliable!",
  "session_id": "...",
  "mode": "EXECUTION_MODE_STANDARD",
  "created_at": "2024-10-22T10:30:00Z",
  "updated_at": "2024-10-22T10:30:25Z"
}

​
Stream Events in Real-Time

Shannon supports Server-Sent Events (SSE) for real-time updates: 
curl -N http://localhost:8080/api/v1/stream/sse?workflow_id=task-dev-1730000000
You’ll see events as they happen: 
event: LLM_PROMPT
data: {"message":"Analyzing sentiment..."}

event: WORKFLOW_COMPLETED
data: {"result":"The sentiment is positive..."}

​
Using the Python SDK

For a better developer experience, use the Python SDK:

​
Installation

pip install shannon-sdk

​
Submit and Monitor Tasks

from shannon import ShannonClient

# HTTP client (default: http://localhost:8080)
client = ShannonClient()

handle = client.submit_task(
    query="Analyze the sentiment of: Shannon makes AI agents simple!"
)
print("Task submitted:", handle.task_id)

# Wait for completion
final = client.wait(handle.task_id, timeout=60)
print("Result:", final.result)

​
Stream Events

# Stream events in real-time
for event in client.stream(handle.workflow_id):
    print(f"{event.type}: {event.message}")

​
Execution Modes

Shannon auto-selects execution modes based on task complexity. You can override this by passing the mode parameter (simple, standard, complex, supervisor) in your task submission.

​
Cost Control

Budget controls are managed by Shannon. Explicit per‑request budget settings are not yet available via REST.

​
Multi-Turn Conversations

Shannon supports session-based conversations: 
session_id = "my-conversation-123"

# First message
handle1 = client.submit_task(
    query="What is the capital of France?",
    session_id=session_id
)

# Follow-up message (Shannon remembers context)
handle2 = client.submit_task(
    query="What's the population?",
    session_id=session_id
)

# Shannon knows you're asking about Paris's population

​
Using the Desktop App

For a graphical view of tasks and sessions, use the Shannon Desktop Application (Tauri-based client). See Desktop Application for installation and usage details.

​
Example Use Cases

Shannon automatically selects the appropriate execution mode and cognitive strategy based on query complexity. You don’t need to specify these parameters.

​
Sentiment Analysis

client.submit_task(
    query="Analyze sentiment: The product exceeded my expectations!"
)

​
Research & Summarization

client.submit_task(
    query="Research quantum computing breakthroughs in 2024 and create a summary"
)

​
Code Generation

client.submit_task(
    query="Write a Python function to calculate Fibonacci numbers with memoization"
)

​
Complex Analysis with Context

client.submit_task(
    query="Compare the pros and cons of microservices vs monolithic architecture",
    context={
        "domain": "software_architecture",
        "depth": "comprehensive",
        "include_examples": True
    }
)

​
What’s Next?

Core Concepts

Learn about agents, workflows, and cognitive patterns

API Reference

Explore all API endpoints and parameters

Python SDK Guide

Deep dive into SDK features and async usage

Configuration

Customize Shannon for your needs

​
Troubleshooting

Check the logs for errors:
docker compose logs orchestrator
docker compose logs agent-core
Common causes:
  • Invalid LLM API key
  • LLM provider rate limiting
  • Network connectivity issues
Shannon runs with authentication disabled by default (GATEWAY_SKIP_AUTH=1). If you’ve enabled auth, include an API key:
curl -H "X-API-Key: sk_test_123456" \
  http://localhost:8080/api/v1/tasks
Budget limits are configured at the platform level via environment variables:
# In .env file
MAX_TOKENS_PER_REQUEST=10000
MAX_COST_PER_REQUEST=0.50

# Restart services for changes to take effect
docker compose restart
For per-task monitoring, check costs via the status endpoint or streaming events.