Add a domain tool

A native tool is a registered Python capability that a model may request. It subclasses Tool, declares ToolSpec, and implements async def run(ctx, args) -> ToolResult.

Generate a slice

In the generated project, inspect the available agents and generator options:

uv run --no-sync cayu inspect --json
uv run --no-sync cayu generate tool --help

Choose the existing agent name and a deliberate effect classification. cayu generate tool NAME --agent AGENT --effect EFFECT generates a schema, implementation, runtime test and eval. Replace the placeholder behavior and expected results before calling the slice complete. Read generator CLI for the exact accepted effect values and planning options.

A complete read-only implementation

Save this as lookup.py to verify the direct tool contract without model credentials:

import asyncio
from cayu import Tool, ToolContext, ToolEffect, ToolResult, ToolSpec


class LookupTool(Tool):
    spec = ToolSpec(
        name="lookup",
        description="Look up a reviewed reference record.",
        input_schema={
            "type": "object",
            "properties": {"query": {"type": "string"}},
            "required": ["query"],
            "additionalProperties": False,
        },
        effect=ToolEffect.NONE,
    )

    async def run(self, ctx: ToolContext, args: dict) -> ToolResult:
        return ToolResult(
            content=f"Found {args['query']}",
            structured={"session_id": ctx.session_id},
        )


result = asyncio.run(LookupTool().run(ToolContext(session_id="test-session"), {"query": "Cayu"}))
assert result.content == "Found Cayu"
assert result.structured == {"session_id": "test-session"}
print(result.content)

Run python lookup.py; the expected output is Found Cayu. A downloadable copy is checked against the released wheel.

What this proves

Calling the tool directly tests caller-supplied arguments and the implementation. To prove schema validation, policy authorization, resource admission and recorded events, invoke it through an actual Cayu session with a deterministic provider. Preserve that generated runtime test seam.

ToolResult.structured and artifacts are recursively read-only after construction. Use model_dump(mode="json") for ordinary JSON serialization. Report expected domain failures with an error result rather than success prose.

Read tool effects before adding mutations and service tools before wrapping a durable service.