background_agent_tool

def background_agent_tool(
    agent: "Agent",
    *,
    description: str,
    name: str | None = None,
    stream: StreamFactory | None = None,
    middleware: Iterable[ToolMiddleware] = (),
) -> FunctionTool:
    """Expose ``agent`` as a fire-and-forget background subagent tool.

    The returned tool starts the subagent and immediately returns a task id.
    The parent ``Agent.ask`` loop keeps running and will not return until the
    background task finishes — once it does, its result is delivered to the
    parent LLM as a follow-up turn via ``context.enqueue``.
    """

    tool_name = name or f"background_task_{agent.name}"

    @tool(
        name=tool_name,
        description=description,
        middleware=middleware,
    )
    async def delegate(
        ctx: Context,
        objective: str,
        context: str = "",
    ) -> str:
        task_id = uuid4().hex
        task_stream = stream(agent, ctx) if stream else MemoryStream(storage=ctx.stream.history.storage)

        ctx.spawn_background(
            _run_and_deliver(
                agent,
                objective,
                context=context,
                parent_context=ctx,
                stream=task_stream,
                task_id=task_id,
            )
        )

        return f"Background task started: {task_id}"

    return delegate