---
title: "Mastra"
description: "Construisez des agents Mastra TypeScript pour la recherche de tweets, les profils, les tendances et les écritures X revues via TwexAPI MCP."
---

Construisez un agent Twitter API Mastra via le serveur MCP de TwexAPI. Recherchez des tweets, inspectez des profils, lisez les tendances et revoyez les actions d'écriture. Préservez les ID de tweet, les curseurs et les noms de route en JSON typé plutôt que des résumés uniquement dans le chat.

## Pourquoi utiliser Mastra avec TwexAPI ?

Mastra est un framework d'agents TypeScript. TwexAPI fournit la découverte d'endpoints et les appels authentifiés via `explore` et `twexapi_request`.

| Tâche agent | Route TwexAPI | Préserver pour l'étape suivante |
| --- | --- | --- |
| Rechercher des tweets | `POST /twitter/advanced_search/page` | Requête, ID de tweet, auteurs, `created_at`, curseur |
| Inspecter un profil | `GET /twitter/{screen_name}/about` | ID utilisateur, username, biographie, nombre d'abonnés |
| Lire les tendances | `GET /twitter/global-trending/tweets` | Pays, sujet, lignes de tweet |
| Publier ou répondre | `POST /twitter/tweets/create` | ID de tweet, route, approbation humaine, confirmation cookie |

Utilisez Mastra pour les apps TypeScript qui utilisent déjà les modèles Vercel AI SDK. Utilisez le [SDK TypeScript](/sdks/typescript) ou le [CLI](/sdks/cli) pour les jobs planifiés sans modèle.

## Prérequis

- Node.js 20 ou plus récent
- Une [clé API TwexAPI](https://twexapi.io/dashboard)
- Une clé de fournisseur de modèle supporté par Mastra
- Un cookie Twitter ou `auth_token` pour les actions d'écriture — consultez

Les lectures X publiques ne nécessitent pas des identifiants X Developer. Authentifiez avec TwexAPI.

## Installation

```bash
npm install @mastra/core @mastra/mcp @ai-sdk/openai dotenv
```

```txt .env
TWEXAPI_API_KEY=YOUR_API_KEY
OPENAI_API_KEY=sk-...
```

## Connecter TwexAPI MCP

```ts
import "dotenv/config";
import { MCPClient } from "@mastra/mcp";

export const twexapiMcp = new MCPClient({
  servers: {
    twexapi: {
      url: new URL("https://api.twexapi.io/mcp"),
      requestInit: {
        headers: {
          "x-api-key": process.env.TWEXAPI_API_KEY!,
        },
      },
    },
  },
});
```

Le serveur expose `explore` pour la découverte et `twexapi_request` pour les appels authentifiés. Les requêtes MCP non authentifiées renvoient `401`.

## Exemple complet

```ts
import { openai } from "@ai-sdk/openai";
import { Agent } from "@mastra/core/agent";
import { writeFile } from "node:fs/promises";
import { twexapiMcp } from "./mcp";

type TweetRow = {
  tweet_id: string;
  text: string;
  author_username?: string;
  created_at?: string;
};

type TweetSearchHandoff = {
  query: string;
  route_used: string;
  tweets: TweetRow[];
  has_more: boolean;
  next_cursor: string | null;
  stop_reason: "complete" | "requested_limit" | "cursor_stalled" | "page_cap";
};

const tools = await twexapiMcp.listTools();

export const twexapiAgent = new Agent({
  name: "twexapi-agent",
  instructions: `
    Use TwexAPI MCP for Twitter API requests.
    Call explore before twexapi_request.
    Preserve exact IDs and cursors. Never invent missing tweet fields.
    Ask for confirmation before read_only: false actions.
    Return only valid JSON matching the handoff contract.
  `,
  model: openai("gpt-4o-mini"),
  tools,
});

const result = await twexapiAgent.generate(
  `Search 25 recent tweets about Mastra MCP.
Return JSON with query, route_used, tweets[{tweet_id,text,author_username,created_at}],
has_more, next_cursor, and stop_reason.`
);

const handoff = JSON.parse(result.text) as TweetSearchHandoff;
await writeFile(
  "twexapi-mastra-handoff.json",
  JSON.stringify(handoff, null, 2),
  "utf8"
);
```

Validez le JSON avant qu'un autre workflow le consomme. L'historique de conversation n'est pas une base de données de jobs.

## Préserver le contrat de réponse MCP

Passez uniquement les champs `query` et `body` documentés de `explore` dans `twexapi_request`.

Arrêtez la pagination lorsqu'une condition devient vraie :

- L'agent collecte le total demandé.
- `has_more` ou `has_next_page` devient false.
- `next_cursor` est absent ou se répète.
- Le plafond de page configuré est atteint.

Dédupliquez les tweets et utilisateurs par `tweet_id` ou `user_id`.

## Maintenir un handoff agent résilient

<CardGroup cols={2}>
  <Card title="Pages de tweets" icon="message-square">
    Stockez `tweet_id`, `text`, `author_username`, `created_at`, `has_more`, `next_cursor` et la requête originale.
  </Card>
  <Card title="Lignes de profil" icon="user-round">
    Stockez `user_id`, `username`, `name`, `description`, les compteurs d'abonnés et l'entrée de lookup.
  </Card>
  <Card title="Lignes de tendances" icon="radio">
    Stockez le pays, le sujet, les ID de tweet et les métriques d'engagement.
  </Card>
  <Card title="Actions d'écriture" icon="send">
    Stockez la route, le texte de prévisualisation et l'approbation humaine. Gardez les cookies hors du fichier de handoff. Consultez.
  </Card>
</CardGroup>

Consultez [Agent MCP Handoff](/mcp/agent-handoff) pour la checklist complète.

## Construire la gestion des erreurs

| Statut | Signification | Décision agent |
| --- | --- | --- |
| `400` | Route ou paramètres invalides | Corrigez la requête avant de réessayer |
| `401` | Clé API manquante ou invalide | Arrêtez et remplacez l'identifiant |
| `403` | Accès refusé ou crédits | Pausez les écritures ; consultez [Get Balance](/api-reference/balance-endpoints/get-balance-api-balance-get) |
| `429` | Limite de débit atteinte | Ralentissez, puis reprenez le même curseur |
| `5xx` | Défaillance serveur temporaire | Appliquez un backoff borné aux lectures sûres |

Ne jamais réessayer une écriture après un timeout sans vérification de lecture. Consultez [Gestion des erreurs](/guides/error-handling) et [Limites de débit](/guides/rate-limits).

## Exiger une approbation avant les actions X

```txt
Call explore with include_writes true only when the user asked to post, like, follow, or DM.
Stop before any read_only: false call.
Show method, path, tweet text or target username, and media URLs.
Do not send cookie values in the model output.
```

Prévisualisez avec le [CLI](/sdks/cli) `--dry-run`, puis exécutez via REST ou le SDK TypeScript après approbation.

## Connecter plusieurs serveurs MCP

```ts
export const mcp = new MCPClient({
  servers: {
    twexapi: {
      url: new URL("https://api.twexapi.io/mcp"),
      requestInit: {
        headers: { "x-api-key": process.env.TWEXAPI_API_KEY! },
      },
    },
    twexapiDocs: {
      url: new URL("https://docs.twexapi.io/mcp"),
    },
  },
});
```

Gardez le nom du serveur TwexAPI stable. Donnez à l'agent uniquement les outils requis pour le job actuel.

## Versions des packages

| Package | Plage supportée |
| --- | --- |
| Node.js | `>=20` |
| `@mastra/core` | `>=0.10` |
| `@mastra/mcp` | `>=0.10` |

## Prochaines étapes

- [Outils MCP](/mcp/tools)
- [Agent MCP Handoff](/mcp/agent-handoff)
-
- [SDK TypeScript](/sdks/typescript)
- [Advanced Twitter Search](/api-reference/search-endpoints/get-data-page-twitter-advanced-search-page-post)