Limit what an agent may do
By the end of this tutorial you will have an agent whose policy refuses an action it would otherwise take — proven by the same request writing a memory without the policy and being refused with it.
A policy named in an agent's policy_ids limits what the platform does on the
agent's behalf during a turn, whoever calls it. With run_as: caller, the
default this tutorial keeps, the effective permission is the intersection of the
caller's bound (who can do what)
and the policies', so a policy can only narrow. With run_as: agent the
policies are the agent's whole grant
(Execution identity). Here it governs the write_memory tool, which the platform runs for the agent.
For your own http, mcp and pipeline tools it decides only whether the
agent may call one (tools:CallTool); what a call may do is for
guardrails.
Nine steps:
- Create a memory store.
- Let the agent write to it.
- Ask it to remember something.
- See the memory it wrote.
- Write the policy.
- Attach it to the agent.
- Ask again.
- Read the refusal.
- Confirm nothing was written.
Every step is one API call, shown for all three clients. The ids in the responses are examples — copy the ones your own calls return.
Prerequisites
-
A credential. A
nat_sk_…API key (or a session JWT from Auth) exported asNATURALI_TOKEN, and your client set up — the CLI, the SDK or plaincurl. -
A working agent. That is what Your first agent generation builds. Arrive here with both ids exported:
export NATURALI_TOKEN=nat_sk_...export PROJECT=proj_V1StGXR8Z5jdHi6Bexport AGENT=agent_eTYuxl8oeSAnAYSI
Every memory is embedded when it is written, and embeddings are paid from your credit balance on every plan.
1. Create a memory store
A memory store holds the facts the agent writes.
- CLI
- SDK
- curl
naturali create-memory-store \
--project-id "$PROJECT" \
--name customer-notes \
--description "What customers ask the bakery agent to remember."
const { data: memoryStore } = await naturali.memoryStores.createMemoryStore({
path: { project_id: process.env.PROJECT! },
body: {
name: 'customer-notes',
description: 'What customers ask the bakery agent to remember.',
},
});
curl -X POST "https://api.naturali.ai/v1/projects/$PROJECT/memory-stores" \
-H "Authorization: Bearer $NATURALI_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "customer-notes",
"description": "What customers ask the bakery agent to remember."
}'
{
"id": "mstore_Twclt0j3rEdflxiS",
"project_id": "proj_V1StGXR8Z5jdHi6B",
"name": "customer-notes",
"description": "What customers ask the bakery agent to remember.",
"duplicate_threshold": null,
"supersede_threshold": null,
"created_at": "2026-11-11T12:40:52.416Z",
"updated_at": "2026-11-11T12:40:52.416Z"
}
export STORE=mstore_Twclt0j3rEdflxiS
2. Let the agent write to it
write_memory_store_id in
knowledge_config gives the
agent a write_memory tool
for that store; memory_store_ids lets it read the
store back. The instructions tell it when to use the tool.
- CLI
- SDK
- curl
naturali patch-agent \
--project-id "$PROJECT" \
--agent-id "$AGENT" \
--instructions 'You answer customers of a bakery. When a customer asks you to remember something, save it with the write_memory tool, then confirm in one sentence.' \
--knowledge-config "{ \"memory_store_ids\": [\"$STORE\"], \"write_memory_store_id\": \"$STORE\" }"
const { data: agent } = await naturali.agents.patchAgent({
path: { project_id: process.env.PROJECT!, agent_id: process.env.AGENT! },
body: {
instructions:
'You answer customers of a bakery. When a customer asks you to remember something, save it with the write_memory tool, then confirm in one sentence.',
knowledge_config: {
memory_store_ids: [process.env.STORE!],
write_memory_store_id: process.env.STORE!,
},
},
});
curl -X PATCH "https://api.naturali.ai/v1/projects/$PROJECT/agents/$AGENT" \
-H "Authorization: Bearer $NATURALI_TOKEN" \
-H "Content-Type: application/json" \
-d "{
\"instructions\": \"You answer customers of a bakery. When a customer asks you to remember something, save it with the write_memory tool, then confirm in one sentence.\",
\"knowledge_config\": { \"memory_store_ids\": [\"$STORE\"], \"write_memory_store_id\": \"$STORE\" }
}"
{
"id": "agent_eTYuxl8oeSAnAYSI",
"instructions": "You answer customers of a bakery. When a customer asks you to remember something, save it with the write_memory tool, then confirm in one sentence.",
"knowledge_config": {
"memory_store_ids": ["mstore_Twclt0j3rEdflxiS"],
"write_memory_store_id": "mstore_Twclt0j3rEdflxiS"
},
"policy_ids": null,
"run_as": "caller",
"version": 2
}
policy_ids is null and run_as is caller: nothing limits the agent
beyond the caller's own permissions.
3. Ask it to remember something
- CLI
- SDK
- curl
naturali create-agent-generation \
--project-id "$PROJECT" \
--agent-id "$AGENT" \
--wait true \
--messages '[{"role":"user","content":"Please remember that I pick up my order on Fridays."}]'
const { data: first } = await naturali.agents.createAgentGeneration({
path: { project_id: process.env.PROJECT!, agent_id: process.env.AGENT! },
query: { wait: true },
body: {
messages: [
{
role: 'user',
content: 'Please remember that I pick up my order on Fridays.',
},
],
},
});
curl -X POST \
"https://api.naturali.ai/v1/projects/$PROJECT/agents/$AGENT/generate?wait=true" \
-H "Authorization: Bearer $NATURALI_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "messages": [{ "role": "user", "content": "Please remember that I pick up my order on Fridays." }] }'
{
"id": "gen_euaTKZpFiJVzOIFf",
"trace_id": "trace_WMbfgbyId29ZQVgx",
"status": "completed",
"output": {
"model": "claude-haiku-5.5",
"content": "Got it, I've saved that you pick up your order on Fridays.",
"finish_reason": "stop"
}
}
4. See the memory it wrote
GET /v1/projects/{project_id}/memories
lists the store.
- CLI
- SDK
- curl
naturali list-memories \
--project-id "$PROJECT" \
--memory-store-id "$STORE"
const { data: memories } = await naturali.memories.listMemories({
path: { project_id: process.env.PROJECT! },
query: { memory_store_id: process.env.STORE! },
});
curl "https://api.naturali.ai/v1/projects/$PROJECT/memories?memory_store_id=$STORE" \
-H "Authorization: Bearer $NATURALI_TOKEN"
{
"data": [
{
"id": "mem_mzDhtoJldyTFoDRM",
"memory_store_id": "mstore_Twclt0j3rEdflxiS",
"content": "Customer picks up their order on Fridays.",
"source_type": "manual",
"invalidated_at": null,
"version": 1,
"created_at": "2026-11-11T12:40:54.720Z"
}
],
"next_cursor": null
}
The agent called write_memory and the platform stored the fact. This is the
action the policy will take away.
5. Write the policy
POST /v1/projects/{project_id}/policies
creates a policy of the project. This one allows every
action on the project's resources and then denies the two the write_memory
tool needs — memories:CreateMemory for a new fact and memories:UpdateMemory
for one that supersedes an old one.
A Deny always wins over an Allow, and an Allow must name the project's
resources (srn:<project_id>:*:*).
- CLI
- SDK
- curl
naturali create-policy \
--project-id "$PROJECT" \
--name no-memory-writes \
--description "Everything in the project except writing memories." \
--document "{
\"statement\": [
{ \"effect\": \"Allow\", \"action\": [\"*\"], \"resource\": [\"srn:$PROJECT:*:*\"] },
{ \"effect\": \"Deny\", \"action\": [\"memories:CreateMemory\", \"memories:UpdateMemory\"] }
]
}"
const { data: policy } = await naturali.policies.createPolicy({
path: { project_id: process.env.PROJECT! },
body: {
name: 'no-memory-writes',
description: 'Everything in the project except writing memories.',
document: {
statement: [
{
effect: 'Allow',
action: ['*'],
resource: [`srn:${process.env.PROJECT}:*:*`],
},
{
effect: 'Deny',
action: ['memories:CreateMemory', 'memories:UpdateMemory'],
},
],
},
},
});
curl -X POST "https://api.naturali.ai/v1/projects/$PROJECT/policies" \
-H "Authorization: Bearer $NATURALI_TOKEN" \
-H "Content-Type: application/json" \
-d "{
\"name\": \"no-memory-writes\",
\"description\": \"Everything in the project except writing memories.\",
\"document\": {
\"statement\": [
{ \"effect\": \"Allow\", \"action\": [\"*\"], \"resource\": [\"srn:$PROJECT:*:*\"] },
{ \"effect\": \"Deny\", \"action\": [\"memories:CreateMemory\", \"memories:UpdateMemory\"] }
]
}
}"
{
"id": "pol_p2EwedAYmKAuBQHV",
"project_id": "proj_V1StGXR8Z5jdHi6B",
"name": "no-memory-writes",
"description": "Everything in the project except writing memories.",
"document": {
"statement": [
{
"effect": "Allow",
"action": ["*"],
"resource": ["srn:proj_V1StGXR8Z5jdHi6B:*:*"]
},
{
"effect": "Deny",
"action": ["memories:CreateMemory", "memories:UpdateMemory"]
}
]
},
"created_at": "2026-11-11T12:41:07.051Z",
"updated_at": "2026-11-11T12:41:07.051Z"
}
export POLICY=pol_p2EwedAYmKAuBQHV
On its own a policy grants and refuses nothing: it takes effect where a resource names it.
6. Attach it to the agent
policy_ids on the agent names the policies that cap every generation. You
must hold every grant of a policy to attach it, else 403 POLICY_GRANT_NOT_HELD.
- CLI
- SDK
- curl
naturali patch-agent \
--project-id "$PROJECT" \
--agent-id "$AGENT" \
--policy-ids "[\"$POLICY\"]"
const { data: limited } = await naturali.agents.patchAgent({
path: { project_id: process.env.PROJECT!, agent_id: process.env.AGENT! },
body: { policy_ids: [process.env.POLICY!] },
});
curl -X PATCH "https://api.naturali.ai/v1/projects/$PROJECT/agents/$AGENT" \
-H "Authorization: Bearer $NATURALI_TOKEN" \
-H "Content-Type: application/json" \
-d "{ \"policy_ids\": [\"$POLICY\"] }"
{
"id": "agent_eTYuxl8oeSAnAYSI",
"policy_ids": ["pol_p2EwedAYmKAuBQHV"],
"run_as": "caller",
"version": 3
}
policy_ids is part of the agent's configuration, so the change is a
new version, like any other edit.
7. Ask again
The same kind of request as step 3, with a new fact.
- CLI
- SDK
- curl
naturali create-agent-generation \
--project-id "$PROJECT" \
--agent-id "$AGENT" \
--wait true \
--messages '[{"role":"user","content":"Please remember that I prefer rye bread."}]'
const { data: second } = await naturali.agents.createAgentGeneration({
path: { project_id: process.env.PROJECT!, agent_id: process.env.AGENT! },
query: { wait: true },
body: {
messages: [
{ role: 'user', content: 'Please remember that I prefer rye bread.' },
],
},
});
curl -X POST \
"https://api.naturali.ai/v1/projects/$PROJECT/agents/$AGENT/generate?wait=true" \
-H "Authorization: Bearer $NATURALI_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "messages": [{ "role": "user", "content": "Please remember that I prefer rye bread." }] }'
{
"id": "gen_meq4Abzn9a1FBDEm",
"trace_id": "trace_wBUvGsZBhXLTVoEW",
"status": "completed",
"output": {
"model": "claude-haiku-5.5",
"content": "I'm sorry, I couldn't save that your preference for rye bread is stored because the memory system denied the request. Please ask the bakery staff to note it on your account.",
"finish_reason": "stop"
}
}
export GENERATION=gen_meq4Abzn9a1FBDEm
The reply says the save was denied. A reply is the model's words, not a record of what ran — the next step reads what actually happened.
8. Read the refusal
GET /v1/projects/{project_id}/generations/{generation_id}/transcript
shows every tool call of the turn
and its result.
- CLI
- SDK
- curl
naturali get-generation-transcript \
--project-id "$PROJECT" \
--generation-id "$GENERATION"
const { data: transcript } = await naturali.generations.getGenerationTranscript(
{
path: {
project_id: process.env.PROJECT!,
generation_id: process.env.GENERATION!,
},
}
);
curl "https://api.naturali.ai/v1/projects/$PROJECT/generations/$GENERATION/transcript" \
-H "Authorization: Bearer $NATURALI_TOKEN"
{
"generation_id": "gen_meq4Abzn9a1FBDEm",
"agent_version": 3,
"status": "completed",
"step_count": 2,
"steps": [
{
"index": 0,
"finish_reason": "tool-calls",
"tool_calls": [
{
"id": "toolu_01VUymsueuLPYakqnCfKkEie",
"tool_name": "write_memory",
"args": { "content": "Customer prefers rye bread." }
}
],
"tool_results": [
{
"tool_call_id": "toolu_01VUymsueuLPYakqnCfKkEie",
"tool_name": "write_memory",
"result": {
"error": {
"code": "FORBIDDEN",
"message": "Forbidden: agent agent_eTYuxl8oeSAnAYSI's policies deny memories:CreateMemory on srn:proj_V1StGXR8Z5jdHi6B:memory_store:mstore_Twclt0j3rEdflxiS",
"meta": {
"action": "memories:CreateMemory",
"resource": "srn:proj_V1StGXR8Z5jdHi6B:memory_store:mstore_Twclt0j3rEdflxiS",
"denied_by": { "type": "agent", "id": "agent_eTYuxl8oeSAnAYSI" }
}
}
},
"error": null
}
]
},
{
"index": 1,
"text": "I'm sorry, I couldn't save that your preference for rye bread is stored because the memory system denied the request. Please ask the bakery staff to note it on your account.",
"finish_reason": "stop"
}
]
}
The agent tried the same action as in step 3, and the policy refused it
before anything was written: meta.action names the refused action and
meta.denied_by the agent whose policies refused it. The refusal reaches the
model as the tool's result, not as a failed generation — which is why the turn
still completed.
Tell the agent in its instructions what to say when a save is refused if its
reply should be honest about it.
9. Confirm nothing was written
- CLI
- SDK
- curl
naturali list-memories \
--project-id "$PROJECT" \
--memory-store-id "$STORE"
const { data: after } = await naturali.memories.listMemories({
path: { project_id: process.env.PROJECT! },
query: { memory_store_id: process.env.STORE! },
});
curl "https://api.naturali.ai/v1/projects/$PROJECT/memories?memory_store_id=$STORE" \
-H "Authorization: Bearer $NATURALI_TOKEN"
{
"data": [
{
"id": "mem_mzDhtoJldyTFoDRM",
"content": "Customer picks up their order on Fridays.",
"version": 1
}
],
"next_cursor": null
}
Still one memory: the store holds what the agent wrote before the policy and nothing after. That is the value — the agent keeps reading the store, and can no longer change it.
What's next
- Gate a tool with guardrails — the equivalent control for your own tools: execute, ask a person, or refuse.
- Give an agent long-term memory — a memory rule writes facts after each turn, without the agent calling a tool.
- Roll out an agent version —
policy_idsis configuration, so a stricter policy can go out to a slice of traffic first. - Policies — conditions on a resource's tags, and a
trigger's
policy_ids.