Quick Start

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

Task stays in 'running' state

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

Authentication errors

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

High costs / token usage

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.

Getting Started

Core Concepts

Guides

Your First Task

Using the REST API

Check Task Status

Stream Events in Real-Time

Using the Python SDK

Installation

Submit and Monitor Tasks

Stream Events

Execution Modes

Cost Control

Multi-Turn Conversations

Using the Desktop App

Example Use Cases

Sentiment Analysis

Research & Summarization

Code Generation

Complex Analysis with Context

What’s Next?

Core Concepts

API Reference

Python SDK Guide

Configuration

Troubleshooting

​Your First Task

​Using the REST API

​Check Task Status

​Stream Events in Real-Time

​Using the Python SDK

​Installation

​Submit and Monitor Tasks

​Stream Events

​Execution Modes

​Cost Control

​Multi-Turn Conversations

​Using the Desktop App

​Example Use Cases

​Sentiment Analysis

​Research & Summarization

​Code Generation

​Complex Analysis with Context

​What’s Next?

Core Concepts

API Reference

Python SDK Guide

Configuration

​Troubleshooting

Your First Task

Using the REST API

Check Task Status

Stream Events in Real-Time

Using the Python SDK

Installation

Submit and Monitor Tasks

Stream Events

Execution Modes

Cost Control

Multi-Turn Conversations

Using the Desktop App

Example Use Cases

Sentiment Analysis

Research & Summarization

Code Generation

Complex Analysis with Context

What’s Next?

Troubleshooting