Skip to main content

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:

  1. Create a memory store.
  2. Let the agent write to it.
  3. Ask it to remember something.
  4. See the memory it wrote.
  5. Write the policy.
  6. Attach it to the agent.
  7. Ask again.
  8. Read the refusal.
  9. 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​

  1. A credential. A nat_sk_… API key (or a session JWT from Auth) exported as NATURALI_TOKEN, and your client set up — the CLI, the SDK or plain curl.

  2. 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_V1StGXR8Z5jdHi6B
    export 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.

naturali create-memory-store \
--project-id "$PROJECT" \
--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.

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\" }"
{
"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​

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."}]'
{
"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.

naturali list-memories \
--project-id "$PROJECT" \
--memory-store-id "$STORE"
{
"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>:*:*).

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\"] }
]
}"
{
"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.

naturali patch-agent \
--project-id "$PROJECT" \
--agent-id "$AGENT" \
--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.

naturali create-agent-generation \
--project-id "$PROJECT" \
--agent-id "$AGENT" \
--wait true \
--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.

naturali get-generation-transcript \
--project-id "$PROJECT" \
--generation-id "$GENERATION"
{
"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​

naturali list-memories \
--project-id "$PROJECT" \
--memory-store-id "$STORE"
{
"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​