Use codemap find "SymbolName" to locate any symbol before reading — it gives exact file + line range and is faster than grep across the whole repo.

Building Tools with lauren-ai

Critical rule — tool annotations must resolve

from __future__ import annotations is supported, but every type used by @tool() must resolve when schema generation runs.

@tool() resolves annotations when it builds the JSON schema. Future annotations are supported, but unresolved forward references and circular imports in function-form tool files still break schema generation.

A safe reminder comment is:

# @tool() resolves parameter annotations when this module is imported.
# Keep tool signature types importable and avoid unresolved forward refs.

Quick start — function-form tool

from lauren_ai import tool

@tool()
async def get_price(item: str) -> dict:
    """Look up an item's current price.

    Args:
        item: Product name to look up.
    """
    return {"item": item, "price": 9.99}

Attach it to an agent:

from lauren_ai import agent, use_tools

@agent(model="claude-opus-4-6", system="You are a helpful shop assistant.")
@use_tools(get_price)
class ShopAgent: ...

Quick start — class-form tool

Use a class when the tool needs injected dependencies. The method must be named run() — not __call__(). The @tool() decorator looks for run; a __call__ is silently ignored and the decorator will raise ValueError.

from lauren_ai import tool, ToolContext

@tool()
class SendEmailTool:
    """Send an email to a recipient.

    Args:
        to: Recipient email address.
        subject: Email subject line.
        body: Email body text (plain text).
    """

    def __init__(self, smtp_client: SmtpClient) -> None:
        self._smtp = smtp_client

    async def run(
        self,
        to: str,
        subject: str,
        body: str,
        ctx: ToolContext | None = None,
    ) -> dict:
        await self._smtp.send(to=to, subject=subject, body=body)
        return {"sent": True, "to": to}

ToolContext — DI injection, not LLM input

ToolContext is never included in the JSON schema sent to the LLM. ToolExecutor injects it automatically at call time. Use it to:

• Access the agent's AgentContext via ctx.agent_context
• Read the authenticated user identity from ctx.execution_context.request.state
• Identify the current turn number via ctx.turn

@tool()
async def whoami(ctx: ToolContext | None = None) -> dict:
    """Return the authenticated user's ID.

    (No additional parameters — all identity comes from context.)
    """
    if ctx is None or ctx.execution_context is None:
        return {"user_id": None}
    state = getattr(ctx.execution_context.request, "state", None)
    user_id = state.get("user_id") if state else None
    return {"user_id": user_id}

The generated schema contains zero parameters:

{
  "name": "whoami",
  "input_schema": {"type": "object", "properties": {}, "required": []}
}

Schema generation rules

Parameter descriptions come from the Args: section of the Google-style docstring. Always document every parameter.

Safety invariants

Reference files