Skip to main content

SDK Overview

The Waxell SDK provides intent-only definitions for building AI agents. It defines what your agent does, not how it executes.

Core Principle​

The SDK deliberately separates intent from execution:

# SDK: defines WHAT the agent does (intent)
from waxell_runtime import agent, workflow, tool


@agent(name="my_agent", description="Processes inbound records")
class MyAgent:

    @tool
    async def decide(self, ctx, record: dict) -> dict:
        return await ctx.llm.generate(
            prompt=f"Decide what to do with: {record}",
            output_format="json",
        )

    @workflow("process")
    async def process(self, ctx, record: dict):
        # Each ctx.tool(...) is a durable checkpoint.
        return await ctx.tool("decide", record=record)


# Runtime: handles HOW it executes
from waxell_runtime import RuntimeConfig

config = RuntimeConfig.get()

Everything is async, and steps are invoked by name through ctx.tool(...) — that's what makes them checkpointable.

Key Abstractions​

ConceptDecoratorPurpose
Agent@agentTop-level container
Workflow@workflowMulti-step execution flow
Tool@toolA unit of work — external calls, model calls
Router@routerThe model picks which behaviour to run

All four import from either waxell_sdk or waxell_runtime. Reuse comes from declaring tools and workflows once and referencing them by name from any agent.

Dependency Rules​

The SDK has strict import boundaries:

  • MUST NOT import runtime, controlplane, Django, or perform I/O
  • MAY depend on: stdlib, typing, pydantic, attrs, dataclasses

This ensures your agent definitions remain pure and testable.

Next Steps​