Skip to main content

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.10.1#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)

Type Description
TEXT Transcribed user speech or typed text
INTERRUPT User interrupted (barge-in)
SESSION_START Session starting with configuration
SESSION_END Session ending
CONFIG Runtime configuration update

Output (from agent to server)

Type Description TTS?
TEXT_CHUNK Streaming text chunk Buffered
TEXT_FINAL Complete text response Yes
STATUS Processing status update No
METADATA Plan/deliverable update No
ERROR Error message No

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

Variable Description
LIVEKIT_URL LiveKit server WebSocket URL
ROOM_NAME LiveKit room to join
AGENT_IDENTITY Agent participant identity
LIVEKIT_API_KEY LiveKit API key (not needed with LIVEKIT_TOKEN)
LIVEKIT_API_SECRET LiveKit API secret (not needed with LIVEKIT_TOKEN)
LIVEKIT_TOKEN Ready-made token for the agent's room; when set, it is used instead of signing one. Uploaded agents get only this.

Optional

Variable Default Description
STT_SERVICE_ADDRESS stt-service:50051 STT gRPC service address
TTS_SERVICE_ADDRESS tts-service:50052 TTS gRPC service address
TTS_ENABLED true Set to false to disable TTS entirely. The agent will still receive speech input and send text responses, but no audio will be synthesized — effectively turning it into a text chatbot.
STT_WARMUP_ENABLED true Warm up STT model before first utterance
STELLA_TTS_PLAYBACK auto auto (and unset) starts in stream and switches once to sentence if synthesis measures slower than real time for 3 consecutive sentences — never back. stream plays each sentence as it synthesizes; sentence synthesizes the whole sentence first, then plays it. Unknown values log a warning and use auto
STELLA_TTS_PREROLL_MS auto Audio buffered before an utterance starts playing in stream mode. Unset, it adapts to the measured synthesis speed (200 ms to 3 s); set, it is pinned
SESSION_SERVER_URL http://session-management-server:3000 Session management HTTP URL
GRPC_SERVER session-management-server:50051 Session management gRPC address
SESSION_ID (falls back to ROOM_NAME) Database session UUID
AGENT_NAME Agent Display name for the agent
AGENT_ID (falls back to AGENT_IDENTITY) Unique agent identifier
AGENT_ICON 🤖 Display icon for the agent
AGENT_CONFIG Session config JSON; typed as self.session (SessionConfig, schema in contracts/agent-session-config.schema.json)
AGENT_TYPE (class name) Type the agent registers under; STELLA sets it to the agent.yaml slug
AGENT_VERSION 1.0.0 Version the agent registers with
STATE_MACHINE_ADDRESS session-management-server:50051 State machine used by self.plan_runtime
TRANSCRIPT_DEBOUNCE_MS 0 Aggregate rapid successive finals within this window (ms). Off by default: STT endpointing already guarantees a >1s gap between finals, so any window this size is unreachable. Set it only for an STT provider that can fragment faster than that.
INTERRUPT_MODE none Barge-in behavior: none (strict gating) or smart

The voice-pipeline tuning variables above (and the rest of BARGE_IN_*, TTS_*, STELLA_TTS_*) are owned by the SDK: the full list with defaults is stella_agent_sdk.platform_env.PLATFORM_ENV, exported as contracts/sdk-platform-env.json. An agent does not need to declare them in its agent.yaml.

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.10.1
git push origin sdk-v0.10.1

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

Metadata

Release files for stella-ai-agent-sdk 0.10.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for stella-ai-agent-sdk 0.10.1
File Size Uploaded Provenance Actions
stella_ai_agent_sdk-0.10.1.tar.gz 324.2 kB With provenance Details for stella_ai_agent_sdk-0.10.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for stella-ai-agent-sdk 0.10.1
File Interpreter ABI Platform Actions
stella_ai_agent_sdk-0.10.1-py3-none-any.whl Python 3 none any Details for stella_ai_agent_sdk-0.10.1-py3-none-any.whl

Total release size: 585.1 kB

Release files / stella_ai_agent_sdk-0.10.1.tar.gz

Download URL stella_ai_agent_sdk-0.10.1.tar.gz
Size 324.2 kB
Tags Source
SHA-256 checksum
How to use checksums
9ca7f15bf649dc8076032e25bf719a5c03a30630a330e2a697c4acbbf649a2cc
BLAKE2b-256 checksum
How to use checksums
dea085ef623315544942e0598d2b5d22473c4a65ad08379b7e65208950f888ec
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Release files / stella_ai_agent_sdk-0.10.1-py3-none-any.whl

Download URL stella_ai_agent_sdk-0.10.1-py3-none-any.whl
Size 260.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
08edf97687e9eb0966a4d73282ab661fb5b3f44e7de82b47961d5649f1af679e
BLAKE2b-256 checksum
How to use checksums
8d956789b393d1a1547839b266f2ea143385f58b401b88085874fcc1a12ef526
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Security for stella-ai-agent-sdk 0.10.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for stella_ai_agent_sdk-0.10.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page