Quick Start — build an extension in 5 min

python -c "import imperal_sdk; print(imperal_sdk.__version__)"

mkdir hello-world && cd hello-world
touch app.py imperal.json

from imperal_sdk import Extension, ChatExtension, ActionResult, sdl
from pydantic import BaseModel, Field

# Pydantic params model — typed, auto-validated, schema sent to the agent.
class GreetParams(BaseModel):
    name: str = Field(description="Person to greet")

# Typed return model. A read tool returns a typed SDL entity, so the
# platform reads the result as structured data (id / title / kind are the
# core SDL fields) and can resolve downstream chain references against it.
# The decorator declares it via data_model= (V23 — Typed Return Contract).
class Greeting(sdl.Entity):
    text: str = Field(description="The greeting message")

# Your extension instance. The first positional argument is the app_id;
# display_name + description (≥40 chars) + icon + actions_explicit are
# all required by the federal extension contract (V14, V15, V19, V21).
ext = Extension(
    "hello-world",
    version="1.0.0",
    display_name="Hello World",
    description="Demo extension that greets people by name with a friendly message.",
    icon="icon.svg",
    actions_explicit=True,
    capabilities=["hello-world:read"],
)

# A ChatExtension wraps your extension's chat surface — one per ext.
# tool_name= is the canonical registration key for this chat surface.
chat = ChatExtension(
    ext,
    tool_name="hello_world",
    description="Hello World — friendly greetings.",
)

# Your handler — the agent calls this. Pydantic params are auto-detected
# from the type annotation, so no extra parameter is needed. The handler
# returns a typed ActionResult (V18) carrying an SDL entity, and a read
# tool declares its data_model (V23).
@chat.function(
    "greet",
    action_type="read",
    description="Greet someone by name with a friendly message.",
    data_model=Greeting,
)
async def greet(ctx, params: GreetParams) -> ActionResult:
    return ActionResult.success(
        Greeting(id=params.name, title=params.name, text=f"Hello, {params.name}! 🐝"),
        summary=f"Greeted {params.name}",
    )

imperal build

{
  "manifest_schema_version": 3,
  "name": "Hello World",
  "display_name": "Hello World",
  "description": "Demo extension that greets people by name with a friendly message.",
  "icon": "icon.svg",
  "actions_explicit": true,
  "tools": [
    {
      "name": "greet",
      "description": "Greet someone by name with a friendly message.",
      "action_type": "read",
      "params_schema": {
        "type": "object",
        "properties": {
          "name": { "type": "string", "description": "Person to greet" }
        },
        "required": ["name"]
      },
      "return_schema": {
        "x-sdl": "entity",
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "title": { "type": "string" },
          "kind": { "type": "string" },
          "text": { "type": "string", "description": "The greeting message" }
        }
      }
    }
  ]
}

imperal test