> ## 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.

# Overview

<Note>AI Agents is currently in alpha. APIs may change.</Note>

Graphy AI Agents create, transform, and analyze charts using natural language. Most agents take a `GraphConfig` and a prompt and return an updated `GraphConfig` ready to render.

## Architecture

Agents are stateless. Each request contains the full context needed to process it—no sessions, no conversation history.

```mermaid theme={null}
flowchart LR
    A[Your App] -->|GraphConfig + Prompt| B[AI Agent]
    B -->|Updated GraphConfig| A
```

This design simplifies integration:

* No session management or cleanup
* Requests are idempotent and cacheable
* Easy to retry on failure
* Works with any architecture (serverless, edge, traditional)

## Available Agents

| Agent       | Endpoint                   | SDK Method              | Description                                              |
| ----------- | -------------------------- | ----------------------- | -------------------------------------------------------- |
| Chart Maker | `POST /api/v0/generate`    | `generateGraph()`       | Modify chart type, styling, and data transformations     |
| Suggestions | `POST /api/v0/suggestions` | `generateSuggestions()` | Suggest chart types and data preparations                |
| Mutation    | `POST /api/v0/mutate`      | `generateMutation()`    | Transform the dataset — filter, group, derive, sort      |
| Annotation  | `POST /api/v0/annotate`    | `generateAnnotations()` | Add highlights, tooltips, and other annotations          |
| Narrative   | `POST /api/v0/narrate`     | `generateNarrative()`   | Write the chart title, subtitle, and caption             |
| Extract     | `POST /api/v0/extract`     | `extractFromProse()`    | Build a dataset from text, images, PDFs, or spreadsheets |

## Prerequisites

* A Graphy API key — [create one in the console](/agents/api-keys)
* Familiarity with `GraphConfig` ([schema reference](/sdk/reference/graph-config))

## Integration Options

**TypeScript SDK** — Full-featured client with streaming, retries, and type validation.

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

const ai = new GraphyAiSdk({
  apiKey: 'your-api-key',
  baseUrl: 'https://agents.graphy.dev',
});

const result = await ai.generateGraph({
  config: myGraphConfig,
  userPrompt: 'Change to a stacked bar chart',
});
```

**REST API** — Direct HTTP integration for any language. Returns Server-Sent Events for streaming progress.

```bash theme={null}
curl -N https://agents.graphy.dev/api/v0/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"config": {...}, "userPrompt": "Add a trend line"}'
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/agents/quickstart">
    First working call in 5 minutes
  </Card>

  <Card title="TypeScript SDK" icon="js" href="/agents/sdk/installation">
    Install and configure the SDK
  </Card>

  <Card title="REST API" icon="code" href="/agents/rest/authentication">
    Direct HTTP integration
  </Card>

  <Card title="Type Reference" icon="brackets-curly" href="/agents/reference/types">
    Complete type definitions
  </Card>
</CardGroup>