Tool-calling agent loop

Use this for agents that loop — model calls tools, tools return results, model calls again — until a stop condition is reached. The run span stays open for the entire loop and closes when the wrapped function returns.

TypeScript
Python

import { registerOTel, agent, tool, llm } from "@uselemma/tracing";

registerOTel();

const executeTool = tool("dispatch", async (name: string, args: Record<string, unknown>) => {
  return await runTool(name, args);
});

const callLLM = llm("gpt-4o", async (history: unknown[]) => {
  return await callModel(history);
});

const wrapped = agent("my-agent", async (input: { userMessage: string }) => {
  const history = [{ role: "user", content: input.userMessage }];

  while (true) {
    const response = await callLLM(history); // span: llm.gpt-4o

    if (response.stopReason === "end_turn") {
      return response.text;
    }

    for (const toolCall of response.toolCalls) {
      const result = await executeTool(toolCall.name, toolCall.args); // span: tool.dispatch
      history.push({ role: "tool", name: toolCall.name, content: String(result) });
    }
  }
});

const { result, runId } = await wrapped({ userMessage: "What is the weather in London?" });

from uselemma_tracing import register_otel, agent, tool, llm, TraceContext

register_otel()


@tool("dispatch")
async def execute_tool(name: str, args: dict) -> str:
    return await run_tool(name, args)


@llm("gpt-4o")
async def call_llm(history: list) -> object:
    return await call_model(history)


async def run_agent(input: dict, ctx: TraceContext) -> str:
    history = [{"role": "user", "content": input["user_message"]}]

    while True:
        response = await call_llm(history)  # span: llm.gpt-4o

        if response.stop_reason == "end_turn":
            return response.text

        for tool_call in response.tool_calls:
            result = await execute_tool(tool_call.name, tool_call.args)  # span: tool.dispatch
            history.append({"role": "tool", "name": tool_call.name, "content": result})


wrapped = agent("my-agent", run_agent)

result, run_id, _ = await wrapped({"user_message": "What is the weather in London?"})

Key points:

Each tool execution gets its own tool.* child span via the tool() helper.
Each LLM call gets its own llm.* child span via the llm() helper.
The run span closes only after the whole loop finishes, so all turns are captured.
Error recording and span lifecycle are handled automatically by the helpers.

Recipes