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

# Mastra

> Um processador para a chamada ao modelo do agente do Mastra e o kit do histórico como ferramentas do Mastra.

`niadraProcessor()` é um processador de entrada e de saída para o agente do Mastra: reescreve o prompt de cada chamada ao modelo sem tocar na lista de mensagens e registra a resposta final. `niadraTools(session)` devolve o kit do histórico como ferramentas do Mastra. Só em TypeScript.

## Instalar

```sh theme={null}
npm install @niadra/sdk @mastra/core   # @mastra/core 1.x, como peer dependency opcional
```

A integração chega com o `@niadra/sdk` 0.3.0, pronto no ramo `main` e no npm quando for publicado; até lá, o pacote do npm é o 0.1.1.

## As cinco primitivas

| Primitiva   | Como o adaptador liga                                                                                                                                                                                                                         |
| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Contexto    | `processLLMRequest` reescreve o prompt de cada chamada ao modelo sem tocar na lista de mensagens: o contexto vai depois das mensagens de sistema e o sufixo no fim da última mensagem do usuário, então nada disso entra na memória do Mastra |
| Turnos      | A mensagem mais nova do cliente é registrada uma vez; `processOutputResult` registra a resposta final com o uso que o Mastra somou para o run                                                                                                 |
| Ferramentas | `niadraTools(session)`: o kit como ferramentas do Mastra, amarradas ao cliente                                                                                                                                                                |
| Verificação | `conv.verify()` antes de `generate()`                                                                                                                                                                                                         |
| Transbordo  | `conv.handoff()` onde o seu fluxo transfere                                                                                                                                                                                                   |

A sessão vem do request context (`requestContext.set("niadra", convo)`), ou fica fixa quando o processador é construído para uma conversa só.

## Exemplo mínimo

```typescript theme={null}
// A Mastra agent with the customer's context in every model call and the history tools.
import { openai } from "@ai-sdk/openai";
import { Agent } from "@mastra/core/agent";
import { RequestContext } from "@mastra/core/request-context";
import { Niadra, handles } from "@niadra/sdk";
import { niadraProcessor, niadraTools } from "@niadra/sdk/mastra";

const niadra = new Niadra();
const niadraContext = niadraProcessor();

export const support = new Agent({
  id: "support",
  name: "Acme support",
  model: openai("gpt-4.1"),
  instructions: "You are Acme's support agent. Be brief.",
  tools: ({ requestContext }) => niadraTools(requestContext.get("niadra")),
  inputProcessors: [niadraContext],
  outputProcessors: [niadraContext],
});

/** One customer message in; `userId` comes from your session, never from the model. */
export async function reply(userId: string, chatId: string, text: string): Promise<string> {
  const convo = niadra.conversation({ subject: handles.appUserId(userId), channel: "web_chat", conversation_id: chatId });
  const result = await support.generate(text, { requestContext: new RequestContext([["niadra", convo]]), maxSteps: 4 });
  return result.text;
}
```

O mesmo código está em `examples/mastra.ts`.

## Memória do agente

`niadraProcessor({ agentMemory: true })` põe as notas do próprio agente antes do contexto do cliente, e `niadraTools(convo, { agentMemory: { write: true } })` acrescenta as duas ferramentas. Veja [Memória do agente](/concepts/agent-memory).

## Limites

* A `Memory` do Mastra (threads, working memory) continua do Mastra; a Niadra é a memória do cliente compartilhada com os outros agentes da empresa.
* Nada aqui derruba a chamada: sem contexto, o prompt vai como o Mastra o montou.
* Testado contra `@mastra/core` 1.71 com um modelo falso e a Niadra no emulador.

## Próximos passos

<CardGroup cols={2}>
  <Card title="Vercel AI SDK" href="/integrations/ai-sdk">
    o middleware para `wrapLanguageModel`.
  </Card>

  <Card title="SDK de TypeScript" href="/sdk/typescript">
    a conversa, o `suffix` e o `markInjected()`.
  </Card>
</CardGroup>