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 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 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 waxell (from waxell import agent, workflow, tool, router). 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​