spade-llm 0.3.0

Extension for SPADE to integrate Large Language Models in agents

Documentation | Quick Start | Examples | API Reference

SPADE-LLM: Large Language Model Integration for Multi-Agent Systems

SPADE-LLM is a Python framework that extends SPADE multi-agent platform with Large Language Model capabilities. Build AI agents powered by OpenAI GPT, Ollama, LM Studio, and other LLM providers for multi-agent systems, with communication via XMPP for distributed AI applications.

Keywords: SPADE, LLM, large language models, multi-agent systems, AI agents, OpenAI, GPT, Ollama, chatbot framework, distributed AI, Python AI, agent communication, XMPP agents, AI collaboration

Table of Contents

• SPADE-LLM: Large Language Model Integration for Multi-Agent Systems
  • Table of Contents
  • Key Features
  • Installation instructions
    • Requirements
    • Install
  • Built-in XMPP Server
    • Start the Server
  • Quick Start
    • Step 1: Start the Built-in XMPP Server
    • Step 2: Create and Run Your LLM Agent
  • Examples
    • Multi-Provider Support
    • Tools and Function Calling
    • Structured Outputs
    • RAG (Retrieval-Augmented Generation)
  • Documentation
  • Contributing
  • License

Key Features

• Built-in XMPP Server - No external server setup needed! Start agents with one command
• Multi-LLM Provider Support - Integrate OpenAI models, Ollama local models, LM Studio and more via LiteLLM
• RAG System - Retrieval-Augmented Generation with document loading, text splitting, and vector store retrieval (ChromaDB)
• Structured Outputs - Type-safe LLM responses using Pydantic models; define the schema, get back structured data
• Coordinator Agents - LLM-driven orchestration of SPADE subagents with shared context and automatic routing
• Advanced Tool System - Function calling, async execution, LangChain tool integration, custom tool development
• Smart Context Management - Multi-conversation support, automatic cleanup, sliding window, token-aware context
• Persistent Memory - Agent-based memory, conversation threading, long-term state persistence across sessions
• Intelligent Message Routing - Conditional routing based on LLM responses, dynamic agent selection
• Content Safety Guardrails - Input/output filtering, keyword blocking, content moderation, safety controls
• MCP Integration - Model Context Protocol server support for external tools and services
• Human-in-the-Loop - Web interface for human expert consultation, interactive decision making

Installation instructions

Requirements

• Python 3.11+
• (recommended) uv installation for environment management

Install

# Install with uv (recommended)
uv pip install spade_llm

# Or install with pip
pip install spade_llm

# If working on a project with uv
uv add spade_llm

For optional features:

# RAG support with ChromaDB
pip install spade_llm[chroma]   # or: uv add spade_llm --extra chroma

# LangChain tool integration
pip install spade_llm[langchain]   # or: uv add spade_llm --extra langchain

Built-in XMPP Server

SPADE 4+ includes a built-in XMPP server, eliminating the need for external server setup. This is a major advantage over other multi-agent frameworks like AutoGen or Swarm that require complex infrastructure configuration.

Start the Server

# Start SPADE's built-in XMPP server
spade run

The server automatically handles:

• Agent registration and authentication
• Message routing between agents
• Connection management
• Domain resolution

Agents automatically connect to the built-in server when using standard SPADE agent configuration.

Quick Start

Get started with SPADE-LLM in just 2 steps:

Step 1: Start the Built-in XMPP Server

# Terminal 1: Start SPADE's built-in server
spade run

Step 2: Create and Run Your LLM Agent

# your_agent.py
import spade
from spade_llm import LLMAgent, LLMProvider

async def main():
    provider = LLMProvider(
        model="gpt-5-nano",
        api_key="your-api-key",
    )

    agent = LLMAgent(
        jid="assistant@localhost",  # Connects to built-in server
        password="password",
        provider=provider,
        system_prompt="You are a helpful assistant"
    )

    await agent.start()

if __name__ == "__main__":
    spade.run(main())

# Terminal 2: Run your agent
python your_agent.py

Examples

Multi-Provider Support

# OpenAI
provider = LLMProvider(model="gpt-5-nano", api_key="key")

# Ollama (local)
provider = LLMProvider(model="ollama/llama3.1:8b")

# Any OpenAI-compatible API (LM Studio, vLLM, etc.)
provider = LLMProvider(model="openai/local-model", base_url="http://localhost:1234/v1")

Tools and Function Calling

from spade_llm import LLMTool

async def get_weather(city: str) -> str:
    return f"Weather in {city}: 22°C, sunny"

weather_tool = LLMTool(
    name="get_weather",
    description="Get weather for a city",
    parameters={
        "type": "object",
        "properties": {"city": {"type": "string"}},
        "required": ["city"]
    },
    func=get_weather
)

agent = LLMAgent(
    jid="assistant@localhost",  # Uses built-in server
    password="password",
    provider=provider,
    tools=[weather_tool]
)

Structured Outputs

from pydantic import BaseModel
from spade_llm import LLMAgent, LLMProvider

class WeatherReport(BaseModel):
    city: str
    temperature: float
    conditions: str

provider = LLMProvider(model="gpt-5-nano", api_key="key")
agent = LLMAgent(
    jid="weather@localhost",
    password="password",
    provider=provider,
    system_prompt="Extract weather information",
    output_schema=WeatherReport,
)

RAG (Retrieval-Augmented Generation)

from spade_llm import RetrievalAgent, LLMProvider
from spade_llm.rag import DirectoryLoader, RecursiveCharacterTextSplitter, ChromaVectorStore, VectorStoreRetriever

# Load, split, and index documents
loader = DirectoryLoader("./docs")
splitter = RecursiveCharacterTextSplitter(chunk_size=500)
docs = splitter.split_documents(loader.load())
store = ChromaVectorStore(collection_name="my_docs")
await store.add_documents(docs)

retriever = VectorStoreRetriever(vector_store=store)
agent = RetrievalAgent(
    jid="rag@localhost",
    password="password",
    provider=LLMProvider(model="gpt-5-nano", api_key="key"),
    retriever=retriever,
)

Documentation

• Installation - Setup and requirements
• Quick Start - Basic usage examples
• Providers - LLM provider configuration
• Tools - Function calling system
• RAG - Retrieval-Augmented Generation
• Structured Outputs - Type-safe LLM responses
• Guardrails - Content filtering and safety
• API Reference - Complete API documentation

Contributing

See Contributing Guide.

License

MIT License