---
title: stream
description: API Reference for streaming.
---

# `stream()`

Similar to `text()` but returns a stream of responses instead of waiting for completion

```ts showLineNumbers copy
const agent = new Agent({...});

// Stream responses
const stream = await agent.stream({
  messages: ["Write a long story about..."]
});

// Handle the stream
for await (const chunk of stream.textStream) {
// Write each chunk without a newline to create a continuous stream
  process.stdout.write(chunk);
}

// With step tracking
const stream = await agent.stream({
  messages: ["Complex task requiring multiple tools..."],
  onStepFinish: (step) => {
    console.log(`Step completed: ${step}`)
  },
  maxSteps: 3
});
```

#### Key differences between text() and stream():

##### 1. Response Format

- text(): Returns complete response when finished
- stream(): Returns chunks of response as they're generated

##### 2. Use Cases

- text(): Better for short responses or when you need the complete result
- stream(): Better for long responses or when you want to show progress

##### 3. Memory Usage

- text(): Holds complete response in memory
- stream(): Processes response in chunks, more memory efficient

##### 4. Both methods share:

- Same input parameters
- Tool execution capabilities
- Rate limit handling
- Logging
- Error handling

## API Signature

### Parameters

<PropertiesTable
  content={[
    {
      name: "messages",
      type: "Array<string>",
      description: "An array of messages to generate process",
    },
    {
      name: "onStepFinish",
      type: "(step: string) => void;",
      isOptional: true,
      description:
        "Callback function called after each step. Receives step details as a JSON string",
    },
    {
      name: "maxSteps",
      type: "number",
      isOptional: true,
      description:
        "Maximum number of tool execution steps allowed. (Defaults to 5)",
    },
  ]}
/>

### Returns

<PropertiesTable
  content={[
    {
      name: "text",
      type: "string",
      isOptional: true,
      description: "The generated text response",
    },
    {
      name: "textStream",
      type: "AsyncIterableStream<string>",
      isOptional: true,
      description:
        "Text stream of the generated response. It contains text chunks. ",
    },
    {
      name: "toolCalls",
      type: "Array<ToolCall>",
      isOptional: true,
      description: "The tool calls made during the text generation process",
      properties: [
        {
          type: "ToolCall",
          parameters: [
            {
              name: "toolName",
              type: "string",
              description: "The name of the tool",
            },
            {
              name: "args",
              type: "any",
              description: "The arguments passed to the tool",
            },
          ],
        },
      ],
    },
    {
      name: "error",
      type: "string",
      isOptional: true,
      description: "Error message if the tool execution fails",
    },
  ]}
/>
