Criar um agente com armazenamentos de memória

Use armazenamentos de memória quando precisar de contexto durável, utilizável entre usuários, sessões e agentes, e acessível por aplicações externas. Os armazenamentos de memória são úteis para guardar anotações de contas, manuais de suporte, relatórios de bugs ou qualquer conteúdo que você queira reutilizar em várias execuções de agentes. Referência da API:

1. Crie o armazenamento de memória

Crie um armazenamento para um corpo de conhecimento durável. Use instructions para descrever como as entradas devem ser escritas e mantidas.

mka1 llm memory-stores create --body '{
  "name": "Acme support memory",
  "description": "Durable support notes for Acme Corp.",
  "instructions": "Keep entries concise. Use one file per durable fact, customer preference, or open issue.",
  "visibility": "workspace",
  "metadata": {
    "account_id": "acct_acme"
  }
}' \
  -H 'X-On-Behalf-Of: <end-user-id>'

import { SDK } from "@meetkai/mka1";

const sdk = new SDK({
  bearerAuth: "Bearer <mka1-api-key>",
});

const store = await sdk.llm.memoryStores.create({
  xOnBehalfOf: "<end-user-id>", // optional — attribute the request to one of your end users
  createMemoryStoreRequest: {
    name: "Acme support memory",
    description: "Durable support notes for Acme Corp.",
    instructions:
      "Keep entries concise. Use one file per durable fact, customer preference, or open issue.",
    visibility: "workspace",
    metadata: {
      account_id: "acct_acme",
    },
  },
});

console.log(store.id);

const storeResponse = await fetch("https://apigw.mka1.com/api/v1/llm/memory_stores", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer <mka1-api-key>",
    "X-On-Behalf-Of": "<end-user-id>",
  },
  body: JSON.stringify({
    name: "Acme support memory",
    description: "Durable support notes for Acme Corp.",
    instructions:
      "Keep entries concise. Use one file per durable fact, customer preference, or open issue.",
    visibility: "workspace",
    metadata: {
      account_id: "acct_acme",
    },
  }),
});

const store = await storeResponse.json();
console.log(store.id);

curl https://apigw.mka1.com/api/v1/llm/memory_stores \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>' \
  --data '{
    "name": "Acme support memory",
    "description": "Durable support notes for Acme Corp.",
    "instructions": "Keep entries concise. Use one file per durable fact, customer preference, or open issue.",
    "visibility": "workspace",
    "metadata": {
      "account_id": "acct_acme"
    }
  }'

A resposta inclui um ID de armazenamento de memória, como mem_store_.... A visibility determina se esse armazenamento de memória pode ser usado somente para um X-On-Behalf-Of específico (private) ou se qualquer usuário, independentemente de X-On-Behalf-Of, pode acessá-lo (workspace). Consulte a referência da API Create memory store para ver o esquema completo.

2. Adicione entradas de memória

As entradas são endereçáveis por path. Use caminhos previsíveis para que o agente possa encontrar arquivos no armazenamento montado.

mka1 llm memory-stores create-entry \
  --memory-store-id mem_store_123 \
  --body '{
    "path": "accounts/acme/preferences.md",
    "content": "# Acme preferences\n\n- Prefer concise weekly status summaries.\n- Escalate production incidents to the on-call channel before creating a ticket.",
    "metadata": {
      "kind": "customer-preferences"
    }
  }' \
  -H 'X-On-Behalf-Of: <end-user-id>'

const entry = await sdk.llm.memoryStores.createEntry({
  memoryStoreId: "mem_store_123",
  xOnBehalfOf: "<end-user-id>",
  createMemoryEntryRequest: {
    path: "accounts/acme/preferences.md",
    content:
      "# Acme preferences\n\n- Prefer concise weekly status summaries.\n- Escalate production incidents to the on-call channel before creating a ticket.",
    metadata: {
      kind: "customer-preferences",
    },
  },
});

console.log(entry.id, entry.contentHash);

const entryResponse = await fetch(
  "https://apigw.mka1.com/api/v1/llm/memory_stores/mem_store_123/entries",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: "Bearer <mka1-api-key>",
      "X-On-Behalf-Of": "<end-user-id>",
    },
    body: JSON.stringify({
      path: "accounts/acme/preferences.md",
      content:
        "# Acme preferences\n\n- Prefer concise weekly status summaries.\n- Escalate production incidents to the on-call channel before creating a ticket.",
      metadata: {
        kind: "customer-preferences",
      },
    }),
  },
);

const entry = await entryResponse.json();
console.log(entry.id, entry.content_hash);

curl https://apigw.mka1.com/api/v1/llm/memory_stores/mem_store_123/entries \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>' \
  --data '{
    "path": "accounts/acme/preferences.md",
    "content": "# Acme preferences\n\n- Prefer concise weekly status summaries.\n- Escalate production incidents to the on-call channel before creating a ticket.",
    "metadata": {
      "kind": "customer-preferences"
    }
  }'

A resposta da entrada inclui um ID de entrada e um hash de conteúdo. Salve ambos quando sua aplicação puder atualizar a entrada posteriormente.

3. Crie o agente salvo

Crie um agente com uma ferramenta shell e monte o armazenamento de memória no ambiente de shell. O objeto de montagem usa:

store_id: o ID do armazenamento de memória a montar
label: o nome do diretório em /mnt/memory
access: read_only ou read_write
description e instructions: contexto opcional sobre como o agente deve usar o armazenamento montado

Use read_only para materiais de referência. Use read_write somente quando o agente deve ter permissão para atualizar a memória pelo sistema de arquivos montado. Quando o agente grava, edita ou exclui arquivos dentro de uma montagem read_write, o sandbox sincroniza essas alterações de volta ao armazenamento de memória após a conclusão do comando de shell.

mka1 agents create --body '{
  "name": "account-support-agent",
  "description": "Answers support questions with durable account context.",
  "model": "meetkai:functionary-pt",
  "instructions": "Use the mounted Acme support memory for durable account context. Read files under /mnt/memory/acme_support before answering account-specific questions. When you learn a durable Acme fact, write or update the relevant markdown file under /mnt/memory/acme_support. Do not invent account facts that are not present in memory.",
  "tools": [
    {
      "type": "shell",
      "environment": {
        "type": "container_auto",
        "memory_stores": [
          {
            "store_id": "mem_store_123",
            "label": "acme_support",
            "access": "read_write",
            "description": "Durable support notes for Acme Corp.",
            "instructions": "Use these files as account context. Prefer specific files under accounts/acme/. Write durable account learnings back as concise markdown."
          }
        ]
      }
    }
  ],
  "tool_choice": "auto",
  "metadata": {
    "memory_store_id": "mem_store_123",
    "account_id": "acct_acme"
  }
}' \
  -H 'X-On-Behalf-Of: <end-user-id>'

const agent = await sdk.agents.createAgent({
  xOnBehalfOf: "<end-user-id>",
  createAgentRequest: {
    name: "account-support-agent",
    description: "Answers support questions with durable account context.",
    model: "meetkai:functionary-pt",
    instructions:
      "Use the mounted Acme support memory for durable account context. Read files under /mnt/memory/acme_support before answering account-specific questions. When you learn a durable Acme fact, write or update the relevant markdown file under /mnt/memory/acme_support. Do not invent account facts that are not present in memory.",
    tools: [
      {
        type: "shell",
        environment: {
          type: "container_auto",
          memoryStores: [
            {
              storeId: "mem_store_123",
              label: "acme_support",
              access: "read_write",
              description: "Durable support notes for Acme Corp.",
              instructions:
                "Use these files as account context. Prefer specific files under accounts/acme/. Write durable account learnings back as concise markdown.",
            },
          ],
        },
      },
    ],
    toolChoice: "auto",
    metadata: {
      memory_store_id: "mem_store_123",
      account_id: "acct_acme",
    },
  },
});

console.log(agent.id);

const agentResponse = await fetch("https://apigw.mka1.com/api/v1/agents", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer <mka1-api-key>",
    "X-On-Behalf-Of": "<end-user-id>",
  },
  body: JSON.stringify({
    name: "account-support-agent",
    description: "Answers support questions with durable account context.",
    model: "meetkai:functionary-pt",
    instructions:
      "Use the mounted Acme support memory for durable account context. Read files under /mnt/memory/acme_support before answering account-specific questions. When you learn a durable Acme fact, write or update the relevant markdown file under /mnt/memory/acme_support. Do not invent account facts that are not present in memory.",
    tools: [
      {
        type: "shell",
        environment: {
          type: "container_auto",
          memory_stores: [
            {
              store_id: "mem_store_123",
              label: "acme_support",
              access: "read_write",
              description: "Durable support notes for Acme Corp.",
              instructions:
                "Use these files as account context. Prefer specific files under accounts/acme/. Write durable account learnings back as concise markdown.",
            },
          ],
        },
      },
    ],
    tool_choice: "auto",
    metadata: {
      memory_store_id: "mem_store_123",
      account_id: "acct_acme",
    },
  }),
});

const agent = await agentResponse.json();
console.log(agent.id);

curl https://apigw.mka1.com/api/v1/agents \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>' \
  --data '{
    "name": "account-support-agent",
    "description": "Answers support questions with durable account context.",
    "model": "meetkai:functionary-pt",
    "instructions": "Use the mounted Acme support memory for durable account context. Read files under /mnt/memory/acme_support before answering account-specific questions. When you learn a durable Acme fact, write or update the relevant markdown file under /mnt/memory/acme_support. Do not invent account facts that are not present in memory.",
    "tools": [
      {
        "type": "shell",
        "environment": {
          "type": "container_auto",
          "memory_stores": [
            {
              "store_id": "mem_store_123",
              "label": "acme_support",
              "access": "read_write",
              "description": "Durable support notes for Acme Corp.",
              "instructions": "Use these files as account context. Prefer specific files under accounts/acme/. Write durable account learnings back as concise markdown."
            }
          ]
        }
      }
    ],
    "tool_choice": "auto",
    "metadata": {
      "memory_store_id": "mem_store_123",
      "account_id": "acct_acme"
    }
  }'

Consulte a referência da API Create an agent para ver a estrutura completa da solicitação de agente salvo.

4. Execute o agente e atualize a memória

Execute o agente salvo com a entrada específica da tarefa. O agente pode inspecionar os arquivos de memória montados pela ferramenta de shell quando precisar de contexto durável. Se o armazenamento montado for read_write, o agente também poderá atualizar a memória gravando arquivos em /mnt/memory/<label>. O sandbox restaura os arquivos montados antes da execução do comando de shell, cria um instantâneo deles e sincroniza os arquivos alterados de volta ao armazenamento após a conclusão do comando.

mka1 agent-runs create \
  --agent-id agt_123 \
  --body '{
    "input": "Draft a support update for Acme about the production incident response plan. Use the mounted Acme memory before answering. Also remember that Acme now wants customer-facing incident summaries by 4 PM Central.",
    "metadata": {
      "memory_store_id": "mem_store_123",
      "source": "docs-recipe"
    }
  }' \
  -H 'X-On-Behalf-Of: <end-user-id>'

const run = await sdk.agentRuns.createAgentRun({
  agentId: "agt_123",
  xOnBehalfOf: "<end-user-id>",
  createAgentRunRequest: {
    input:
      "Draft a support update for Acme about the production incident response plan. Use the mounted Acme memory before answering. Also remember that Acme now wants customer-facing incident summaries by 4 PM Central.",
    metadata: {
      memory_store_id: "mem_store_123",
      source: "docs-recipe",
    },
  },
});

console.log(run.id);

const runResponse = await fetch("https://apigw.mka1.com/api/v1/agents/agt_123/runs", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer <mka1-api-key>",
    "X-On-Behalf-Of": "<end-user-id>",
  },
  body: JSON.stringify({
    input:
      "Draft a support update for Acme about the production incident response plan. Use the mounted Acme memory before answering. Also remember that Acme now wants customer-facing incident summaries by 4 PM Central.",
    metadata: {
      memory_store_id: "mem_store_123",
      source: "docs-recipe",
    },
  }),
});

const run = await runResponse.json();
console.log(run.id);

curl https://apigw.mka1.com/api/v1/agents/agt_123/runs \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>' \
  --data '{
    "input": "Draft a support update for Acme about the production incident response plan. Use the mounted Acme memory before answering. Also remember that Acme now wants customer-facing incident summaries by 4 PM Central.",
    "metadata": {
      "memory_store_id": "mem_store_123",
      "source": "docs-recipe"
    }
  }'

Use Retrieve an agent run para consultar o status. Use Stream agent run events para acompanhar o progresso em tempo real. O agente deve usar a ferramenta de shell para ler os arquivos montados e gravar atualizações duráveis diretamente na montagem read_write.

5. Inspecione a memória após a execução

Após a conclusão da execução, use a API Memory Stores para inspecionar o que mudou. Os mesmos arquivos que o agente grava em /mnt/memory/acme_support ficam disponíveis como entradas de memória.

mka1 llm memory-stores list-entries \
  --memory-store-id mem_store_123 \
  --limit 20 \
  -H 'X-On-Behalf-Of: <end-user-id>'

const entries = await sdk.llm.memoryStores.listEntries({
  memoryStoreId: "mem_store_123",
  limit: 20,
  xOnBehalfOf: "<end-user-id>",
});

console.log(entries.data.map((entry) => entry.path));

const entriesResponse = await fetch(
  "https://apigw.mka1.com/api/v1/llm/memory_stores/mem_store_123/entries?limit=20",
  {
    headers: {
      Authorization: "Bearer <mka1-api-key>",
      "X-On-Behalf-Of": "<end-user-id>",
    },
  },
);

const entries = await entriesResponse.json();
console.log(entries.data.map((entry) => entry.path));

curl 'https://apigw.mka1.com/api/v1/llm/memory_stores/mem_store_123/entries?limit=20' \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>'

Consulte a referência da API List memory entries e a referência da API Retrieve memory entry para detalhes da resposta.

Observações operacionais

Use montagens read_only para memória de referência e montagens read_write para agentes confiáveis para editar memória durável.
Permita que os agentes atualizem a memória durável gravando arquivos em montagens read_write pela ferramenta de shell.
Use atualizações diretas da API Memory Stores para semeamento, fluxos de revisão, correções administrativas ou importações.
Mantenha as entradas de memória pequenas o suficiente para que o agente inspecione somente os arquivos relevantes durante uma execução.
Use valores path estáveis para que sua aplicação possa mapear objetos do produto para entradas de memória.
Armazene IDs de objetos externos em metadata quando precisar reconciliar a memória com seu banco de dados.
Exclua entradas obsoletas com o endpoint Delete memory entry.

Primeiros passos

Respostas

Recursos

Computação

CLI

Receitas

Benchmarks

Infraestrutura

Criar um agente com armazenamentos de memória

1. Crie o armazenamento de memória

2. Adicione entradas de memória

3. Crie o agente salvo

4. Execute o agente e atualize a memória

5. Inspecione a memória após a execução

Observações operacionais

​1. Crie o armazenamento de memória

​2. Adicione entradas de memória

​3. Crie o agente salvo

​4. Execute o agente e atualize a memória

​5. Inspecione a memória após a execução

​Observações operacionais

1. Crie o armazenamento de memória

2. Adicione entradas de memória

3. Crie o agente salvo

4. Execute o agente e atualize a memória

5. Inspecione a memória após a execução

Observações operacionais