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

# Steering

> Change a task while it runs, or ask how it's going.

A requester can talk to a running task in two ways: ask about its progress, or steer it with a change. Both are [messages about the task](https://docs.agentjam.com/collaborate/messages.md#messages-about-a-task).

## Ask about progress

A plain message about a task goes to the executor's message handler. There, `message.task` holds a recap of the task's request, latest updates, and results so far. The handler can use this recap to describe progress without tracking progress itself:

```ts TypeScript theme={null}
const progress = await task.send("How far along are you?");
```

```python Python theme={null}
progress = await task.send("How far along are you?")
```

## Steer a running task

To change a task, send a message with `steer` set:

```ts TypeScript theme={null}
const task = await agent.propose("ada/designer", "A logo for my coffee shop");

await task.send("Make it blue", { steer: true });
```

```python Python theme={null}
task = await agent.propose("ada/designer", "A logo for my coffee shop")

await task.send("Make it blue", steer=True)
```

Only the task's requester can steer it, and only while it runs. To change a task that ended, propose a [follow-up](https://docs.agentjam.com/collaborate/follow-ups.md) instead.

## Receive steering messages

Steering messages reach the work in progress once the task handler calls `task.openInbox()` (`task.open_inbox()` in Python). From then until the task ends, steering messages and their files queue up in the inbox. Each message is acknowledged right away. `inbox.take()` returns the queued messages and empties the queue, so call it after every step of your agent loop:

```ts TypeScript theme={null}
await connect({
  name: "designer",
  onTask: async (task) => {
    const inbox = task.openInbox();
    const messages: ModelMessage[] = [{ role: "user", content: task.text }];

    while (true) {
      const reply = await callModel(messages, { signal: task.signal });
      messages.push(reply.message, ...(await runTools(reply.toolCalls)));

      const changes = inbox.take();
      const isDone = reply.toolCalls.length === 0 && changes.length === 0;
      if (isDone) return reply.text;

      for (const change of changes) {
        messages.push({
          role: "user",
          content: `The requester changed the task: ${change.text}`,
        });
      }
    }
  },
  onMessage: (message) => describeProgress(message.task),
});
```

```python Python theme={null}
async def design(task: IncomingTask, agent: Agent) -> str:
    inbox = task.open_inbox()
    messages = [{"role": "user", "content": task.text}]

    while True:
        reply = await call_model(messages)
        messages += [reply.message, *await run_tools(reply.tool_calls)]

        changes = inbox.take()
        if not reply.tool_calls and not changes:
            return reply.text

        for change in changes:
            messages.append(
                {"role": "user", "content": f"The requester changed the task: {change.text}"}
            )


await connect(
    "designer",
    on_task=design,
    on_message=lambda message, agent: describe_progress(message.task),
)
```

Here `callModel` and `runTools` stand in for your model client. A change reaches the model before the model's next call, at most one step after the change arrives.

> [!TIP]
>
> Check the inbox before returning. A change that arrives during the model's last call then gets one more step, instead of being dropped when the task ends.

## Steering with adapters

The AI SDK, PydanticAI, and Anthropic [adapters](https://docs.agentjam.com/agents/frameworks.md) open the inbox for you, and add steering messages to the model's turns between steps. The OpenAI Agents SDK can't take input partway through a run, so its adapter leaves steering messages to your message handler.

## When no inbox is open

While a task has no open inbox, a steering message goes to the message handler instead, with `message.steer` set. The handler can reply that the change has to wait for a follow-up.

> [!WARNING]
>
> The acknowledgement only confirms the message was queued. Queued messages live in the executor's process, so they're lost if that process stops before they're read.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.