STELLA Agent SDK

A communication SDK for building agents that integrate with the STELLA platform.

Overview

The SDK defines the communication protocol - agents implement whatever logic they want internally. It provides:

• Message types (AgentInput, AgentOutput) - Standardized formats for agent communication
• BaseAgent - Abstract class that agents implement
• gRPC client - Handles connection to session-management server

What the SDK does NOT include: LLM services, RAG, expert pools, or any processing logic. Those are your agent's implementation details.

Installation

Requires Python 3.10 or newer.

pip install stella-ai-agent-sdk

To work against unreleased changes, install from source:

git clone https://github.com/c4dhi/STELLA.git
pip install -e STELLA/agents/stella-ai-agent-sdk

Or pin directly to a tag without cloning:

pip install "stella-ai-agent-sdk @ git+https://github.com/c4dhi/STELLA.git@sdk-v0.5.0#subdirectory=agents/stella-ai-agent-sdk"

Quick Start

import asyncio
from typing import AsyncIterator
from stella_agent_sdk import BaseAgent, AgentInput, AgentOutput, run_agent_from_env

class MyAgent(BaseAgent):
    async def on_session_start(self, session_id: str, config: dict) -> None:
        # Initialize your agent with configuration
        self.model = config.get("model", "gpt-4")

    async def process(self, input: AgentInput) -> AsyncIterator[AgentOutput]:
        # Process user input and yield responses
        yield AgentOutput.thinking(input.session_id)

        # Your LLM/processing logic here
        response = await my_llm_call(input.text)

        yield AgentOutput.text_final(input.session_id, response)

    async def on_interrupt(self, session_id: str) -> None:
        # Handle user interrupt (barge-in)
        self.cancel_current_task()

    async def on_session_end(self, session_id: str) -> dict:
        # Cleanup and return final data
        return {"messages": self.message_count}

# run_agent_from_env() is the ONLY entry point. It reads all connection config
# (LiveKit room, STT/TTS addresses, AGENT_CONFIG, ...) from environment variables
# set by the session-management-server, connects everything, and runs the agent.
if __name__ == "__main__":
    asyncio.run(run_agent_from_env(MyAgent()))

Architecture

LiveKit Server (WebRTC audio/video)
        │
        │ Audio tracks
        │
        ▼
    Your Agent (uses SDK)
        │
        ├─ STT Service ← Transcribes user speech
        ├─ TTS Service ← Synthesizes agent responses
        ├─ Receives: AgentInput (text from user)
        └─ Sends: AgentOutput (text responses)
        │
        │ gRPC (SDK protocol)
        │
        ▼
Session-Management-Server (session state, plans, deliverables)

The agent is a black box from session-management's perspective:

1. Agent joins a LiveKit room and subscribes to user audio
2. STT service transcribes user speech into text
3. Agent processes input (using whatever LLM/logic you want)
4. Agent streams text responses back
5. TTS service synthesizes agent text into audio (unless disabled)

Message Types

Input (from server to agent)

Output (from agent to server)

Prompt Compiler

The SDK ships a shared, versioned prompt compiler that resolves {{placeholder}} tokens in an authored prompt (from the Configurator or a plan) against live runtime state. Agents call one entry point:

from stella_agent_sdk import prompts

final = prompts.compile(
    "Helping with: {{current_focus}}\n\n{{history_8}}\n\n{{user_message}}",
    version="1.0.0",                 # required — no implicit "latest"
    sm_context=sm_context,
    conversation_history=history,
    user_input=text,
)

The version is mandatory so an SDK upgrade can never silently change how an agent's prompts compile. Pin the version your agent was tested against (PROMPT_COMPILER_VERSION), and let a deployment override it via config["compiler_version"].

Add a new version by subclassing PlaceholderPromptCompiler (or PromptCompiler), bumping VERSION, and calling register_compiler — older versions stay registered so existing prompts keep compiling.

See the full guide — placeholders, versioning, manifest declaration, and adding a compiler — in SDK Reference → Prompt Compiler.

Environment Variables

Required

Optional

Examples

Both examples are runnable as-is once the environment variables below are set. They are not shipped inside the installed package, so read them on GitHub:

• echo_agent.py — the smallest possible agent (echoes input back)
• openai_agent.py — an LLM-backed agent that streams its reply token by token, and stops generating when the user barges in

Development

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Generate gRPC stubs
python -m grpc_tools.protoc \
    -I proto \
    --python_out=src/stella_agent_sdk/_grpc/generated \
    --grpc_python_out=src/stella_agent_sdk/_grpc/generated \
    proto/agent.proto

Changelog

See CHANGELOG.md. The SDK versions independently of the STELLA platform.

Releasing

Releases are published to PyPI by .github/workflows/publish-sdk.yml, which is triggered by pushing a sdk-v<version> tag:

# 1. Bump `version` in agents/stella-ai-agent-sdk/pyproject.toml, then commit it to main.
# 2. Tag the commit. The tag version must match pyproject.toml or the workflow fails.
git tag sdk-v0.6.0
git push origin sdk-v0.6.0

The workflow builds the sdist and wheel, installs the wheel into a clean environment and runs the test suite against it, publishes to PyPI via trusted publishing (OIDC — no API token is stored in the repo), and creates a GitHub release with the distributions attached.

Run the workflow manually (workflow_dispatch) to build and verify without publishing. Note that a version number can never be reused on PyPI, even after a release is deleted.

License

MIT