> ## Documentation Index
> Fetch the complete documentation index at: https://openrouter.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Async Tools

> Run long-running tools in the background or defer them to external systems, while the model keeps working, checks progress, steers, and receives results automatically.

## Overview

A synchronous tool stops the conversation until it returns. That's fine for a weather lookup. It's a problem when the tool renders a video, runs a data pipeline, or waits days for a legal review.

Async tools let the model keep working while the tool finishes:

* The model gets a pending placeholder for the call right away and moves on.
* When the work finishes, the SDK injects the result as a `tool_task_result` message at the next turn boundary. External work resolves whenever another process reports it.
* While a task runs, the model can check progress, read logs, steer, or cancel it through one built-in `task` tool.

## Lifecycles

Every tool is written the same way: a `run` handler (an async function or async generator) plus a `lifecycle` that controls how it executes.

| Lifecycle | Behavior |
| - | - |
| `'sync'` (default) | The round waits for it, exactly like `execute` |
| `'background'` | Runs in the same process without blocking; the result arrives when it finishes |
| `'deferred'` | Hands the call to an external system; the run pauses until some process completes it |

```typescript expandable lines theme={null}
import { OpenRouter, tool } from '@openrouter/agent';
import { z } from 'zod';

const renderVideo = tool({
  name: 'render_video',
  description: 'Render a video from a script. Long-running.',
  lifecycle: 'background',
  inputSchema: z.object({ script: z.string() }),
  outputSchema: z.object({ url: z.string(), durationMs: z.number() }),
  ack: 'Rendering started.',        // model-facing note in the placeholder
  timeoutMs: 300_000,               // whole-task deadline; ctx.signal aborts on breach
  run: async function* ({ script }, ctx) {
    const job = await renderer.start(script, { signal: ctx?.signal });
    ctx?.onMessage((msg) => job.reprioritize(msg));   // steering opt-in
    for await (const pct of job.progress()) {
      yield { pct };                // yields become the task's log
    }
    return job.result();            // return value = result, validated against outputSchema
  },
});
```

If `run` is a generator, each `yield` becomes a log entry. Logs feed check-ins, `tool.preliminary_result` events, and transcripts (optionally validated by `eventSchema`). The `return` value is the tool's result.

If `run` is a plain async function, log with `ctx.log()` instead.

> [!NOTE]
>
> `lifecycle: 'background'` and `'deferred'` require an `outputSchema`. The result arrives later, so the SDK must be able to validate it without the original call.

## Background Tools

A background tool's `run` executes in the same process, but the round doesn't wait for it:

1. If the work finishes within the grace window (`graceMs`, default 250ms), it behaves like a plain sync call and no placeholder is created.
2. Otherwise the model receives a pending placeholder (including a `taskId`) and the loop continues.
3. When the task finishes, the SDK injects the result as a `tool_task_result` message before the next model turn.

```typescript lines theme={null}
const result = openrouter.callModel({
  model: 'openai/gpt-5-nano',
  input: 'Render the intro video, and draft the announcement post meanwhile.',
  tools: [renderVideo, draftPost],
});

// The model drafts the post WHILE the render runs, then incorporates
// the finished video URL when the task settles.
console.log(await result.getText());
```

### When the Run Would End First

If the model finishes its answer while background work is still in flight, `asyncTools.onRunEnd` decides what happens:

```typescript lines theme={null}
const result = openrouter.callModel({
  model: 'openai/gpt-5-nano',
  input: 'Kick off the render.',
  tools: [renderVideo],
  asyncTools: {
    onRunEnd: 'drain',       // default: wait for tasks, run extra no-tool turns
    drainTimeoutMs: 30_000,  // cap the wait
    maxDrainTurns: 2,        // cap the extra turns
  },
});
```

* `'drain'` (default): wait for running tasks and give the model extra no-tool turns so the final answer includes the results.
* `'detach'`: return immediately. Tasks keep running, and results are dropped (persisted as `orphaned` when a `StateAccessor` is configured).
* `'cancel'`: abort in-flight tasks and finish.

## Deferred Tools

Deferred tools hand work to an external system, such as a human review queue, a batch pipeline, or a webhook-driven service. The `run` handler registers the work and returns `ctx.defer(taskId)`. The conversation pauses (`status: 'awaiting_async_tools'`) until any process completes the task.

```typescript lines theme={null}
const legalReview = tool({
  name: 'request_legal_review',
  description: 'Send a contract for legal review. Takes days.',
  lifecycle: 'deferred',
  inputSchema: z.object({ contractId: z.string() }),
  outputSchema: z.object({ approved: z.boolean(), notes: z.string().optional() }),
  run: async ({ contractId }, ctx) => {
    // Typed fast path: returning a plain value resolves immediately.
    const cached = await legal.cachedVerdict(contractId);
    if (cached) return cached;

    const ticket = await legal.open(contractId, {
      conversationId: ctx?.conversationId,   // hand to the webhook for resume
    });
    return ctx!.defer(ticket.id, {
      pollAfterMs: 60_000,
      ack: `Ticket ${ticket.id} opened.`,
    });
  },
});
```

```python title="Python" lines theme={null}
class ReviewInput(BaseModel):
    contract_id: str

class ReviewOutput(BaseModel):
    approved: bool
    notes: str | None = None

def request_review(params, ctx):
    # Fast path: returning a value resolves immediately.
    cached = legal.cached_verdict(params.contract_id)
    if cached:
        return cached

    # Returning None pauses the run with this call pending in state.
    # start_review below opens the ticket once the call's ID is known.
    return None

legal_review = tool(
    name="request_legal_review",
    description="Send a contract for legal review. Takes days.",
    input_schema=ReviewInput,
    output_schema=ReviewOutput,
    on_tool_called=request_review,
)

# The webhook needs the conversation ID and the pending call's ID to resume the
# right call. The handler above only knows the contract, so open one ticket per
# pending call when the run pauses. legal and its methods are application-defined.
async def start_review(conversation_id: str, request: dict):
    result = call_model(client, {**request, "tools": [legal_review], "state": make_accessor(conversation_id)})
    pending = await result.get_pending_tool_calls()  # tool calls still waiting on a result
    for call in pending:
        # One ticket per pending call, so two reviews of the same contract stay distinct.
        # open_for_call reads the contract from the call's arguments and stores
        # conversation_id and the call's ID for the webhook to pass to on_review_done.
        ticket = legal.open_for_call(conversation_id, call)
        print(f"Ticket {ticket['id']} opened.")
```

```go title="Go" lines theme={null}
// Tool definition sent to the model (Chat Completions wire format).
legalReviewTool := map[string]any{
	"type": "function",
	"function": map[string]any{
		"name":        "request_legal_review",
		"description": "Send a contract for legal review. Takes days.",
		"parameters": map[string]any{
			"type":       "object",
			"properties": map[string]any{"contractId": map[string]any{"type": "string"}},
			"required":   []string{"contractId"},
		},
	},
}

// ToolOutcome, Deferral, the legal client, and savePending are application-defined.
// There is no Go SDK, so your own tool loop implements them.
type Deferral struct {
	TaskID    string
	PollAfter time.Duration
	Ack       string
}

type ToolOutcome struct {
	Result   *ReviewOutput // set when the call resolved immediately
	Deferred *Deferral     // set when the work was handed to the external system
}

// Run handler: a plain value resolves immediately; otherwise defer to the external system.
runLegalReview := func(contractID, conversationID string) ToolOutcome {
	if cached, ok := legal.CachedVerdict(contractID); ok {
		return ToolOutcome{Result: &cached}
	}
	ticket := legal.Open(contractID, conversationID) // hand to the webhook for resume
	return ToolOutcome{Deferred: &Deferral{
		TaskID:    ticket.ID,
		PollAfter: 60 * time.Second,
		Ack:       fmt.Sprintf("Ticket %s opened.", ticket.ID),
	}}
}

// Dispatch in your tool loop. Account for every call in the model's response before
// pausing: a result goes back to the model, a deferral is saved as pending.
// toolCalls is application-defined: each entry has the call's ID and its contract ID.
paused := false
for _, call := range toolCalls {
	outcome := runLegalReview(call.ContractID, conversationID)
	if outcome.Deferred != nil {
		// Save this call as pending, keyed by the task ID. The webhook handler below resumes it.
		savePending(conversationID, call.ID, *outcome.Deferred)
		paused = true
		continue
	}
	output, err := json.Marshal(outcome.Result)
	if err != nil {
		log.Fatal(err)
	}
	messages = append(messages, Message{Role: "tool", ToolCallID: call.ID, Content: string(output)})
}
if paused {
	return // stop the loop with the conversation saved
}
```

Deferred tools require a `StateAccessor` (see [Tool Approval & State](https://openrouter.ai/docs/agent-sdk/call-model/tool-approval-state.md)) so the paused conversation can be found and resumed from another process.

### Typed Completion from Any Process

Completion methods live on the tool, so the output is typechecked against its `outputSchema`:

```typescript lines theme={null}
// webhook handler, hours later, in a different process
await legalReview.resolve(client, {
  state: makeAccessor(conversationId),
  taskId: ticketId,
  output: { approved: true },          // ← typechecked against outputSchema
  run: { model: 'openai/gpt-5-nano' }, // continue the conversation immediately
});
```

```python title="Python" lines theme={null}
# webhook handler, hours later, in a different process
# conversation_id and call_id come from the ticket association stored by start_review
async def on_review_done(conversation_id: str, call_id: str):
    result = call_model(client, {
        "model": "openai/gpt-5-nano",  # continue the conversation immediately
        "input": [{
            "type": "function_call_output",
            "call_id": call_id,
            # validated against output_schema before it is sent
            "output": ReviewOutput(approved=True).model_dump_json(),
        }],
        "tools": [legal_review],
        "state": make_accessor(conversation_id),
    })
    return await result.get_state()

```

```go title="Go" lines theme={null}
// webhook handler, hours later, in a different process
// loadConversation, resolveDeferred, and continueRun are application-defined:
// they read the pending call saved by savePending, append the tool result, and rerun the loop.
conv := loadConversation(conversationID)
// ← typechecked: resolveDeferred only accepts a ReviewOutput
if err := resolveDeferred(conv, ticketID, ReviewOutput{Approved: true}); err != nil {
	log.Fatal(err)
}
continueRun(conv, "openai/gpt-5-nano") // continue the conversation immediately
```

* `legalReview.resolve(...)`: deliver a successful result.
* `legalReview.fail(...)`: deliver an error.
* `legalReview.cancel(...)`: cancel the task.
* Omit `run` to record the result only; it's delivered on the next `callModel({ state })`.
* A task settles once. A replayed webhook throws `ToolTaskAlreadySettledError` instead of delivering the result twice.

The lower-level `resumeToolResults(client, { state, results, ... })` covers batches and tools you don't have a reference to.

> [!WARNING]
>
> `.resolve()` injects a value the model treats as a tool result. Authenticate the webhook before calling it; the SDK can't do that for you. Outputs are validated against `outputSchema` at runtime as well as compile time.

## Checking On Running Tasks

When any long-running tool is registered, the SDK adds one built-in `task` tool to the request. It's a single fixed definition no matter how many async tools you register, so your tools' schemas stay untouched and the prompt cost stays flat.

The pending placeholder tells the model how to use it:

```typescript lines theme={null}
task({ taskId: "task_7f3" })                          // status: state, elapsed, last log
task({ taskId, view: "logs", tail: 5 })               // recent progress entries
task({ taskId, view: "transcript" })                  // full detail (agents: child conversation)
task({ taskId, action: "steer", message: "..." })     // send guidance to the running task
task({ taskId, action: "result" })                    // final result if settled, else status
task({ taskId, action: "cancel", reason: "..." })     // stop the task
```

```python title="Python" lines theme={null}
task(taskId="task_7f3")                             # status: state, elapsed, last log
task(taskId=task_id, view="logs", tail=5)             # recent progress entries
task(taskId=task_id, view="transcript")               # full detail (agents: child conversation)
task(taskId=task_id, action="steer", message="...")   # send guidance to the running task
task(taskId=task_id, action="result")                 # final result if settled, else status
task(taskId=task_id, action="cancel", reason="...")  # stop the task

```

```go title="Go" lines theme={null}
task(TaskArgs{TaskID: "task_7f3"})                               // status: state, elapsed, last log
task(TaskArgs{TaskID: taskID, View: "logs", Tail: 5})              // recent progress entries
task(TaskArgs{TaskID: taskID, View: "transcript"})                 // full detail (agents: child conversation)
task(TaskArgs{TaskID: taskID, Action: "steer", Message: "..."})    // send guidance to the running task
task(TaskArgs{TaskID: taskID, Action: "result"})                   // final result if settled, else status
task(TaskArgs{TaskID: taskID, Action: "cancel", Reason: "..."})    // stop the task
```

The SDK intercepts these calls and routes each one to the tool that owns the task. The model sees one tool; each of your tools decides how to answer.

### Custom Check Handlers

Add a `check` config to control what the model sees when it checks on your tool:

```typescript expandable lines theme={null}
const renderVideo = tool({
  name: 'render_video',
  lifecycle: 'background',
  // ...schemas and run as above...
  check: {
    // Validates the model's task({ params }) payload
    schema: z.object({ includeFrames: z.boolean().optional() }),
    execute: async (params, turnContext) => {
      // turnContext.toolCallStatus           → 'working' | 'completed' | ...
      // turnContext.accumulatedYieldedEvents → every run yield so far
      // turnContext.task                     → statusView / tailLogs / transcript / send / cancel
      return {
        state: turnContext.toolCallStatus,
        progressEvents: turnContext.accumulatedYieldedEvents?.length ?? 0,
        ...(params.includeFrames && { lastFrames: turnContext.task?.tailLogs(3) }),
      };
    },
  },
});
```

```python title="Python" lines theme={null}
class RenderCheckParams(BaseModel):
    # Validates the model's task(params=...) payload
    include_frames: bool | None = None

async def check_render_video(params: RenderCheckParams, turn_context: dict) -> dict:
    # turn_context["tool_call_status"]           -> 'working' | 'completed' | ...
    # turn_context["accumulated_yielded_events"] -> every run yield so far
    # turn_context["task"]                       -> status_view / tail_logs / transcript / send / cancel
    view = {
        "state": turn_context.get("tool_call_status"),
        "progressEvents": len(turn_context.get("accumulated_yielded_events") or []),
    }
    if params.include_frames and turn_context.get("task"):
        view["lastFrames"] = turn_context["task"].tail_logs(3)
    return view

# Fragment: a check handler only takes effect once it is registered on the tool.
# This page does not confirm a check parameter on the Python tool() call, so
# pass this config wherever your SDK version accepts a tool's check config.
# Until it is registered, check-ins on render_video use the default views.
render_video_check = {"schema": RenderCheckParams, "execute": check_render_video}

```

```go title="Go" lines theme={null}
renderVideo := BackgroundTool{
	Name: "render_video",
	// ...schemas and run as above...
	Check: &CheckConfig{
		// Validates the model's task({ params }) payload
		Schema: map[string]any{
			"type":       "object",
			"properties": map[string]any{"includeFrames": map[string]any{"type": "boolean"}},
		},
		Execute: func(params CheckParams, turn TurnContext) any {
			// turn.ToolCallStatus           → "working" | "completed" | ...
			// turn.AccumulatedYieldedEvents → every run yield so far
			// turn.Task                     → StatusView / TailLogs / Transcript / Send / Cancel
			out := map[string]any{
				"state":          turn.ToolCallStatus,
				"progressEvents": len(turn.AccumulatedYieldedEvents),
			}
			if params.IncludeFrames && turn.Task != nil {
				out["lastFrames"] = turn.Task.TailLogs(3)
			}
			return out
		},
	},
}
```

Without a custom `check`, the SDK answers the three views itself (`status` / `logs` / `transcript`, truncated to `asyncTools.maxTranscriptChars`, default 20,000 characters).

> [!NOTE]
>
> The SDK treats task-tool calls as internal: they're exempt from doom-loop detection, skip per-tool concurrency and timeout limits, and never fire `PreToolUse`/`PostToolUse` hooks.

Disable check-ins entirely with `asyncTools: { checkins: false }`. Placeholders then tell the model not to call the tool again, and results still arrive automatically.

The name `task` is reserved: `tool({ name: 'task' })` throws. If a tool list built without `tool()` includes a tool named `task`, the SDK disables the built-in and logs a warning.

After a process restart, deferred tasks answer `status` from persisted state (including a bounded `lastLog`). Full logs and transcripts live in memory only, so those views report a short note explaining that instead.

## Steering Running Tasks

Three ways to send guidance into a running task:

```typescript lines theme={null}
// 1. From code: ModelResult.sendToTask
result.sendToTask(taskId, 'Prioritize the intro segment.');

// 2. From the model: the task tool
//    task({ taskId, action: "steer", message: "Prioritize the intro." })

// 3. From a custom check handler
//    turnContext.task.send(message)
```

```python title="Python" lines theme={null}
# 1. From code: ModelResult.send_to_task
result.send_to_task(task_id, "Prioritize the intro segment.")

# 2. From the model: the task tool
#    task(taskId=task_id, action="steer", message="Prioritize the intro.")

# 3. From a custom check handler
#    turn_context["task"].send(message)

```

```go title="Go" lines theme={null}
// 1. From code: ModelResult.SendToTask
result.SendToTask(taskID, "Prioritize the intro segment.")

// 2. From the model: the task tool
//    task(TaskArgs{TaskID: taskID, Action: "steer", Message: "Prioritize the intro."})

// 3. From a custom check handler
//    turn.Task.Send(message)

```

Messages are delivered to the run body's `ctx.onMessage(handler)` and queued until a handler registers, so no messages are lost. Deferred tasks throw on `sendToTask` because their work runs in an external system the SDK can't reach.

## Agent Tools (Subagents)

`tool.agent()` creates a tool whose work is a child `callModel` conversation, running as a background task:

```typescript expandable lines theme={null}
import { tool, stepCountIs } from '@openrouter/agent';

const researcher = tool.agent({
  name: 'research_topic',
  description: 'Deep-research a topic in the background.',
  inputSchema: z.object({ topic: z.string() }),
  outputSchema: z.object({ text: z.string() }),
  agent: ({ topic }) => ({
    model: 'openai/gpt-5-nano',
    instructions: 'You are a thorough researcher. Cite sources.',
    input: `Research: ${topic}`,
    tools: [searchTool, fetchTool] as const,
    stopWhen: stepCountIs(15),
  }),
  // Map the finished child run to this tool's output.
  // Default: the child's last-message text as { text }.
  result: async (child) => ({ text: await child.getText() }),
});
```

Everything above works the same way for agent tools:

* The parent keeps working while children run; several children can run concurrently under the background pool.
* The child's conversation is the check-in transcript, each child turn is a log entry, and `status` reports `turnsCompleted` and `currentActivity`.
* Steering (`sendToTask` or `task({ action: 'steer' })`) lands in the child as a user message at its next turn boundary.
* `cancelTask(taskId)`, parent abort, or `timeoutMs` cancels the child.

By default, the full child transcript stays out of the parent's context. The parent receives the mapped result, and the model pulls transcript detail on demand via the `task` tool.

> [!NOTE]
>
> Children run in-memory (no `StateAccessor`) and don't inherit the parent's hooks; pass child hooks explicitly in the `agent` spec if needed. A child that pauses (HITL, approval, or deferred tools inside it) fails the task with a clear error.

## Observing Async Tasks

### From Code

```typescript lines theme={null}
const result = openrouter.callModel({ /* ... */ });

result.getAsyncTasks();               // snapshot of pending tasks (taskId, status, lastLog, ...)
result.sendToTask(taskId, message);   // steer an in-process task
result.cancelTask(taskId, reason);    // cancel; returns true when a working task was cancelled
```

```python title="Python" lines theme={null}
async def main():
    result = call_model(client, request)

    pending = await result.get_pending_tool_calls()  # tool calls still waiting on a result
    state = await result.get_state()                 # full conversation state, including pending calls

    print("pending tool calls:", pending)
    print("state:", state)
    print(await result.get_text())

asyncio.run(main())

```

```go title="Go" lines theme={null}
result := client.CallModel(CallModelRequest{ /* ... */ })

result.GetAsyncTasks()             // snapshot of pending tasks (TaskID, Status, LastLog, ...)
result.SendToTask(taskID, message) // steer an in-process task
result.CancelTask(taskID, reason)  // cancel; returns true when a working task was cancelled

```

### From the Event Stream

Async tasks emit dedicated events on `getFullResponsesStream()`:

```typescript lines theme={null}
for await (const event of result.getFullResponsesStream()) {
  switch (event.type) {
    case 'tool.async_started':        // task detached past the grace window
      console.log(`started ${event.taskId} (${event.toolName})`);
      break;
    case 'tool.preliminary_result':   // generator yield / ctx.log entry
      console.log(`progress:`, event.result);
      break;
    case 'tool.async_settled':        // result (or error) delivered
      console.log(`settled ${event.taskId}`);
      break;
  }
}
```

## Options Reference

Run-level configuration, all optional:

```typescript lines theme={null}
const result = openrouter.callModel({
  model: 'openai/gpt-5-nano',
  input: '...',
  tools: [renderVideo, legalReview, researcher],
  toolTimeoutMs: 60_000,             // default per-tool deadline
  toolConcurrency: {
    round: 4,                        // max simultaneous calls per round
    background: 8,                   // max detached background tasks
  },
  asyncTools: {
    onRunEnd: 'drain',               // 'drain' | 'detach' | 'cancel'
    drainTimeoutMs: 30_000,
    maxDrainTurns: 2,
    checkins: true,                  // register the universal task tool
    maxTranscriptChars: 20_000,      // transcript view cap
  },
});
```

```python title="Python" lines theme={null}
# The Python agent SDK does not accept the async-tool run options
# (tool_timeout_ms, tool_concurrency, async_tools); passing them raises a TypeError.
# Use the run-level options it supports instead:
result = call_model(client, {
    "model": "openai/gpt-5-nano",
    "input": "...",
    "tools": [render_video, legal_review, researcher],
    "stop_when": step_count_is(5),        # stop after at most 5 steps
    "allow_final_response": True,         # one extra turn for a natural-language answer
})

```

```go title="Go" lines theme={null}
result := client.CallModel(CallModelRequest{
	Model:         "openai/gpt-5-nano",
	Input:         "...",
	Tools:         []Tool{renderVideo, legalReview, researcher},
	ToolTimeoutMs: 60_000, // default per-tool deadline
	ToolConcurrency: &ToolConcurrency{
		Round:      4, // max simultaneous calls per round
		Background: 8, // max detached background tasks
	},
	AsyncTools: &AsyncToolsConfig{
		OnRunEnd:           "drain", // "drain" | "detach" | "cancel"
		DrainTimeoutMs:     30_000,
		MaxDrainTurns:      2,
		Checkins:           true,   // register the universal task tool
		MaxTranscriptChars: 20_000, // transcript view cap
	},
})
```

Per-tool configuration on `tool()` / `tool.agent()`:

| Field | Applies to | Description |
| - | - | - |
| `lifecycle` | all | `'sync'` (default) \| `'background'` \| `'deferred'` |
| `ack` | background, deferred | Model-facing note in the placeholder: string, object, or `(input) => ...` |
| `graceMs` | background, agent | Settles this fast → plain sync output, no placeholder (default 250) |
| `pollAfterMs` | deferred | Poll-interval hint surfaced in the placeholder and status views |
| `timeoutMs` | all | Whole-task deadline; `ctx.signal` aborts on breach |
| `maxConcurrency` | all | Max simultaneous executions of this tool |
| `logLimits` | background, agent | Ring-buffer caps: `maxEntries` (200), `maxBytes` (256k), `maxEntryBytes` (4k) |
| `check` | background, deferred, agent | `{ schema?, execute? }` for custom task-tool handling |

## Next Steps

* **[Tools](https://openrouter.ai/docs/agent-sdk/call-model/tools.md)** - The `tool()` helper, schemas, and tool types
* **[Tool Approval & State](https://openrouter.ai/docs/agent-sdk/call-model/tool-approval-state.md)** - `StateAccessor` setup for deferred tools and cross-process resume
* **[Streaming](https://openrouter.ai/docs/agent-sdk/call-model/streaming.md)** - Consuming the full event stream
* **[Lifecycle Hooks](https://openrouter.ai/docs/agent-sdk/call-model/lifecycle-hooks.md)** - Observing tool execution
