sdk-mono — su-agent SDK (Python)

Thin WebSocket client for su-agent — the multi-client agent app-server. OpenAI-API-like surface — send prompts, stream typed events. No session management. No reconnection logic.

Install

pip install -e /path/to/sdk-mono
# or
pip install websockets  # the only dependency

Quick start

import asyncio
from su_agent import SuAgentClient

async def main():
    async with SuAgentClient(client_id="my-agent") as client:
        async for event in client.prompt("List files"):
            match event:
                case MessageUpdate(delta_type="text_delta", text=text):
                    print(text, end="")
                case ToolExecutionStart(tool_name=name):
                    print(f"\n🔧 {name}")
                case ToolExecutionEnd(tool_name=name):
                    print(f"\n✅ {name} done")

asyncio.run(main())

API

SuAgentClient(url, *, client_id)

Connect to su-agent. Client ID scopes config (packages, model, skills).

Method	Description
prompt(message, *, images, streaming_behavior)	Send prompt → async iterator of events
steer(message)	Queue steering during streaming
follow_up(message)	Queue follow-up after agent finishes
abort()	Abort current operation
get_state()	Model, thinking, streaming status
get_messages()	Full message history
get_session_stats()	Token usage, cost
set_model(provider, model_id)	Switch model
get_available_models()	List models with valid keys
set_thinking_level(level)	Set reasoning level
compact(custom_instructions?)	Manual compaction
set_auto_compaction(enabled)	Toggle auto-compaction
set_auto_retry(enabled)	Toggle auto-retry
bash(command)	Execute shell command
get_config()	Read client settings (requires client_id)
set_config(config_dict)	Write client settings, reload session

Events

All events are @dataclass instances. Pattern-match with isinstance() or match:

Event	Key fields
AgentStart	—
AgentEnd	messages
TurnStart	—
TurnEnd	message, tool_results
MessageStart	message
MessageEnd	message
MessageUpdate	delta_type, text, tool_call
ToolExecutionStart	tool_name, tool_call_id, args
ToolExecutionUpdate	tool_call_id, text
ToolExecutionEnd	tool_name, result_summary, is_error
CompactionStart/End	reason
QueueUpdate	steering, follow_up
AutoRetryStart/End	attempt, max_attempts

MessageUpdate.delta_type values

Type	What
text_start/end	Text block boundaries
text_delta	Streaming text chunk
thinking_start/end	Thinking block boundaries
thinking_delta	Thinking content chunk
toolcall_start	Tool call begins (with tool_call dict)
toolcall_delta	Tool call JSON args chunk
toolcall_end	Tool call complete
done	Message complete
error	Error occurred