← Agent Memory / agent-memory / api

HTTP API

Pro volání Agent Memory ze služeb, které neběží uvnitř Cloudflare Workers. Pro aplikace Workers použijte Workers API prostřednictvím agent_memory binding.

HTTP API pracuje se jmennými prostory a profily. Jmenný prostor vymezuje profily pro vaši aplikaci a každý profil představuje izolované úložiště paměti. Profily se vytvářejí automaticky při prvním zápisu do nich.

Ověřování

Všechny požadavky vyžadují API token s příslušnými oprávněními Agent Memory.

Zahrňte svůj API token do Authorization hlavičku:

Authorization: Bearer <API_TOKEN>

Informace o volání Cloudflare API najdete v Volání API.

Správa jmenných prostorů

A namespace je kontejner nejvyšší úrovně, který vymezuje profily paměti pro vaši aplikaci.

Vytvoření jmenného prostoru

Vytvoří nový jmenný prostor pro daný účet.

curl -X POST "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/agent-memory/namespaces" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"name": "support-agent"}'

Odpověď obsahuje název jmenného prostoru, který použijete ve Worker bindings a při voláních HTTP API.

{
	"result": {
		"id": "01JSGCEXAMPLE000000000000",
		"name": "support-agent",
		"created_at": "2026-04-21T00:00:00.000Z",
		"updated_at": "2026-04-21T00:00:00.000Z"
	},
	"success": true,
	"errors": [],
	"messages": []
}

Seznam jmenných prostorů

Vypíše všechny jmenné prostory daného účtu. Výsledky jsou stránkované.

curl "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/agent-memory/namespaces?per_page=50" \
  -H "Authorization: Bearer <API_TOKEN>"

{
	"result": [
		{
			"id": "01JSGCEXAMPLE000000000000",
			"name": "support-agent",
			"created_at": "2026-04-21T00:00:00.000Z",
			"updated_at": "2026-04-21T00:00:00.000Z"
		}
	],
	"success": true,
	"errors": [],
	"messages": [],
	"result_info": {
		"cursor": "next-cursor",
		"per_page": 50,
		"count": 1
	}
}

Získat jmenný prostor

Načte jeden jmenný prostor podle názvu.

curl "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/agent-memory/namespaces/<NAMESPACE_NAME>" \
  -H "Authorization: Bearer <API_TOKEN>"

{
	"result": {
		"id": "01JSGCEXAMPLE000000000000",
		"name": "support-agent",
		"created_at": "2026-04-21T00:00:00.000Z",
		"updated_at": "2026-04-21T00:00:00.000Z"
	},
	"success": true,
	"errors": [],
	"messages": []
}

Smazat jmenný prostor

Označí jmenný prostor ke smazání. Po smazání se název jmenného prostoru uvolní pro další použití.

curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/agent-memory/namespaces/<NAMESPACE_NAME>" \
  -H "Authorization: Bearer <API_TOKEN>"

{
	"result": null,
	"success": true,
	"errors": [],
	"messages": []
}

Profily

Ke správě profilů a práci s pamětí uloženou v pojmenovaném profilu používejte endpointy profilu. Profily se vytvářejí automaticky při prvním zápisu do nich.

Smazat profil

Označí profil a všechny jeho paměťové záznamy a zprávy ke smazání.

curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/agent-memory/namespaces/<NAMESPACE_NAME>/profiles/<PROFILE_NAME>" \
  -H "Authorization: Bearer <API_TOKEN>"

{
	"result": null,
	"success": true,
	"errors": [],
	"messages": []
}

Smazat relaci

Označí ke smazání všechny paměťové záznamy a zprávy v profilu, které jsou opatřeny daným ID relace. Záznamy z jiných relací ve stejném profilu zůstanou nedotčené. Operace je idempotentní: smazání ID relace, ke kterému neexistují žádné záznamy, nemá žádný účinek (no-op).

curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/agent-memory/namespaces/<NAMESPACE_NAME>/profiles/<PROFILE_NAME>/sessions/<SESSION_ID>" \
  -H "Authorization: Bearer <API_TOKEN>"

{
	"result": null,
	"success": true,
	"errors": [],
	"messages": []
}

Přijmout zprávy

Zpracuje konverzaci a extrahuje z ní strukturované paměťové záznamy. Agent Memory automaticky rozpoznává fakta, události, pokyny a úkoly, takže nemusíte určovat, co si má zapamatovat.

curl -X POST "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/agent-memory/namespaces/<NAMESPACE_NAME>/profiles/<PROFILE_NAME>/ingest" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "I prefer concise answers.",
        "timestamp": "2026-04-21T00:00:00.000Z"
      }
    ],
    "sessionId": "chat-2026-04-21"
  }'

{
	"result": null,
	"success": true,
	"errors": [],
	"messages": []
}

ingest je idempotentní. Opakovaný import stejné konverzace nevytváří duplicitní záznamy paměti.

Uložení paměťového záznamu

Explicitně uloží jeden paměťový záznam. Použijte remember když vaše aplikace nebo agent již ví, co se má uložit.

curl -X POST "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/agent-memory/namespaces/<NAMESPACE_NAME>/profiles/<PROFILE_NAME>/remember" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "The user prefers concise answers.",
    "sessionId": "chat-2026-04-21"
  }'

{
	"result": {
		"id": "01JSGCEXAMPLE000000000000",
		"type": "instruction",
		"summary": "The user prefers concise answers.",
		"content": "The user prefers concise answers.",
		"sessionId": "chat-2026-04-21",
		"createdAt": "2026-04-21T00:00:00.000Z",
		"updatedAt": "2026-04-21T00:00:00.000Z"
	},
	"success": true,
	"errors": [],
	"messages": []
}

Vyhledání paměťových záznamů

Prohledá paměťové záznamy uložené v profilu a vrátí syntetizovanou odpověď založenou na uloženém obsahu.

curl -X POST "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/agent-memory/namespaces/<NAMESPACE_NAME>/profiles/<PROFILE_NAME>/recall" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "How should I answer this user?",
    "thinkingLevel": "low",
    "responseLength": "medium"
  }'

{
	"result": {
		"answer": "The user prefers concise answers.",
		"count": 1,
		"candidates": [
			{
				"id": "01JSGCEXAMPLE000000000000",
				"summary": "The user prefers concise answers.",
				"sessionId": "chat-2026-04-21",
				"score": 0.87
			}
		]
	},
	"success": true,
	"errors": [],
	"messages": []
}

Pokud dotazu neodpovídá žádný paměťový záznam, recall vrátí prázdnou odpověď.

Výpis paměťových záznamů

Vypíše paměťové záznamy uložené v profilu.

curl "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/agent-memory/namespaces/<NAMESPACE_NAME>/profiles/<PROFILE_NAME>/memories?per_page=50" \
  -H "Authorization: Bearer <API_TOKEN>"

{
	"result": [
		{
			"id": "01JSGCEXAMPLE000000000000",
			"type": "instruction",
			"summary": "The user prefers concise answers.",
			"sessionId": "chat-2026-04-21",
			"createdAt": "2026-04-21T00:00:00.000Z",
			"updatedAt": "2026-04-21T00:00:00.000Z"
		}
	],
	"success": true,
	"errors": [],
	"messages": [],
	"result_info": {
		"cursor": "next-cursor",
		"per_page": 50,
		"count": 1
	}
}

Položky výpisu neobsahují content. Pro načtení celého záznamu paměti použijte endpoint get memory.

Chcete-li filtrovat paměťové záznamy, použijte session_id a type parametry dotazu.

Získat paměťový záznam

Načte paměťový záznam podle ID.

curl "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/agent-memory/namespaces/<NAMESPACE_NAME>/profiles/<PROFILE_NAME>/memories/<MEMORY_ID>" \
  -H "Authorization: Bearer <API_TOKEN>"

{
	"result": {
		"id": "01JSGCEXAMPLE000000000000",
		"type": "instruction",
		"summary": "The user prefers concise answers.",
		"content": "The user prefers concise answers.",
		"sessionId": "chat-2026-04-21",
		"createdAt": "2026-04-21T00:00:00.000Z",
		"updatedAt": "2026-04-21T00:00:00.000Z"
	},
	"success": true,
	"errors": [],
	"messages": []
}

Smazat paměťový záznam

Smaže paměťový záznam podle ID. Odstraní paměťový záznam i všechny zdrojové zprávy, které jsou s ním propojené. Vrátí smazaný paměťový záznam.

curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/agent-memory/namespaces/<NAMESPACE_NAME>/profiles/<PROFILE_NAME>/memories/<MEMORY_ID>" \
  -H "Authorization: Bearer <API_TOKEN>"

{
	"result": {
		"id": "01JSGCEXAMPLE000000000000",
		"type": "instruction",
		"summary": "The user prefers concise answers.",
		"content": "The user prefers concise answers.",
		"sessionId": "chat-2026-04-21",
		"createdAt": "2026-04-21T00:00:00.000Z",
		"updatedAt": "2026-04-21T00:00:00.000Z"
	},
	"success": true,
	"errors": [],
	"messages": []
}

Získat souhrn

Vygeneruje strukturovaný souhrn v Markdownu se vším, co je uloženo v paměťovém profilu. Použijte ho ke kontrole toho, co si Agent Memory o daném profilu pamatuje.

curl -X POST "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/agent-memory/namespaces/<NAMESPACE_NAME>/profiles/<PROFILE_NAME>/summary" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{}'

{
	"result": {
		"summary": "## Summary\n\nThe user prefers concise answers."
	},
	"success": true,
	"errors": [],
	"messages": []
}

Chcete-li omezit rozsah sekce „Last Session“ v souhrnu, zahrňte sessionId pole v těle požadavku.

Chybové odpovědi

Všechny endpointy při selhání vrací standardní chybové odpovědi Cloudflare V4:

{
	"result": null,
	"success": false,
	"errors": [
		{
			"code": 10008,
			"message": "Namespace name already exists"
		}
	],
	"messages": []
}

Mezi běžné chybové scénáře patří:

Scénář	Stav HTTP
Neplatný formát názvu jmenného prostoru	`400`
Selhání ověření	`401`
Název jmenného prostoru již existuje	`409`
Jmenný prostor nebyl nalezen	`404`
Profil nebyl nalezen	`404`