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

# Suggestions Agent

Generate chart type and data preparation suggestions from a dataset. Send a `GraphConfig` and a prompt, receive a list of suggested visualizations.

## Methods

### generateSuggestions

Processes the request and returns the final result. Internally handles streaming and collects the response.

```typescript theme={null}
async generateSuggestions(
  params: GenerateGraphSuggestionsParams,
  onProgress?: (event: ProgressEvent) => void,
  signal?: AbortSignal
): Promise<GenerateGraphSuggestionsResponse>
```

### generateSuggestionsStream

Returns an async iterator that yields events as they arrive.

```typescript theme={null}
async generateSuggestionsStream(
  params: GenerateGraphSuggestionsParams,
  signal?: AbortSignal
): Promise<AsyncIterableIterator<SSEEvent<GenerateGraphSuggestionsResponse>>>
```

## Parameters

```typescript theme={null}
interface GenerateGraphSuggestionsParams {
  config: GraphConfig;
  userPrompt?: string;
  metadata?: Metadata;
  maxSuggestionCount?: 1 | 2 | 3 | 4;
}
```

| Field                | Type                     | Required | Description                                                                                                                                      |
| -------------------- | ------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `config`             | `GraphConfig`            | Yes      | The chart configuration containing the dataset                                                                                                   |
| `userPrompt`         | `string`                 | No       | Natural language description of what to visualize                                                                                                |
| `metadata`           | `Metadata`               | No       | Request tracking information                                                                                                                     |
| `maxSuggestionCount` | `1` \| `2` \| `3` \| `4` | No       | Optional cap (1–4) passed to the model for how many suggestions to aim for. Omitted uses the default (4). Responses are not truncated if longer. |

## Response

```typescript theme={null}
interface GenerateGraphSuggestionsResponse {
  suggestions: Suggestion[];
}
```

| Field         | Type           | Description                    |
| ------------- | -------------- | ------------------------------ |
| `suggestions` | `Suggestion[]` | List of chart type suggestions |

### Suggestion

```typescript theme={null}
interface Suggestion {
  dataPrepPrompt: string;
  chartType: AiChartType;
  summary: string;
}
```

| Field            | Type          | Description                                                                   |
| ---------------- | ------------- | ----------------------------------------------------------------------------- |
| `dataPrepPrompt` | `string`      | Prompt describing how to prepare the data for this chart                      |
| `chartType`      | `AiChartType` | Suggested chart type (see [AiChartType](/agents/reference/types#aicharttype)) |
| `summary`        | `string`      | Short description of what the chart would show                                |

The response is validated with Zod. Invalid responses throw an error.

***

## Basic Usage

```typescript theme={null}
import { GraphyAiSdk } from '@graphysdk/agents-sdk';
import type { GraphConfig } from '@graphysdk/core';

const ai = new GraphyAiSdk({
  apiKey: process.env.GRAPHY_API_KEY,
  baseUrl: 'https://agents.graphy.dev',
});

const config: GraphConfig = {
  type: 'column',
  data: {
    columns: [
      { key: 'month', label: 'Month' },
      { key: 'sales', label: 'Sales' },
      { key: 'region', label: 'Region' },
    ],
    rows: [
      { month: 'Jan', sales: 100, region: 'North' },
      { month: 'Feb', sales: 120, region: 'South' },
      { month: 'Mar', sales: 115, region: 'North' },
    ],
  },
};

const result = await ai.generateSuggestions({
  config,
  userPrompt: 'Show me interesting trends',
});

for (const suggestion of result.suggestions) {
  console.log(`${suggestion.chartType}: ${suggestion.summary}`);
}
```

***

## With Progress Callback

Use the `onProgress` callback to show real-time progress:

```typescript theme={null}
const result = await ai.generateSuggestions(
  {
    config,
    userPrompt: 'What charts would best show this data?',
  },
  (progress) => {
    console.log(progress.message);
  }
);
```

***

## Streaming

For full control over the event stream:

```typescript theme={null}
import { isProgressEvent, isCompleteEvent, isErrorEvent } from '@graphysdk/agents-sdk';

const stream = await ai.generateSuggestionsStream({
  config,
  userPrompt: 'Suggest charts for sales analysis',
});

for await (const event of stream) {
  if (isProgressEvent(event)) {
    console.log(event.message);
  }

  if (isCompleteEvent(event)) {
    console.log('Suggestions:', event.data.suggestions);
  }

  if (isErrorEvent(event)) {
    console.error('Error:', event.error);
  }
}
```

See [Streaming](/agents/sdk/streaming) for cancellation and React patterns.

***

## Error Handling

```typescript theme={null}
import { isGraphyApiError } from '@graphysdk/agents-sdk';

try {
  const result = await ai.generateSuggestions({
    config,
    userPrompt: 'Suggest charts',
  });
} catch (error) {
  if (isGraphyApiError(error)) {
    console.error('API error:', error.message);
  }
}
```

See [Error Handling](/agents/sdk/errors) for retry behavior and error types.