Skip to main content

Bound an Agent with Its Policies

SOAT forwards the caller's credential into every builtin action an agent performs, so a chain is capped by the caller's token. That cap is not least privilege: a read-only summarizer running under a caller who may write documents executes at the caller's ceiling.

An agent's policy_ids name stored policies that limit what that agent may do, whoever calls it: each builtin action, and every http, mcp or pipeline tool as tools:CallTool. Every generation runs as the caller ∩ those policies, as with API keys.

You give alice broad document permissions, bind an agent to a document-writing tool, watch the agent's write be refused by a read-only policy, then perform the same write directly as alice.

Prerequisites​

export SOAT_BASE_URL=http://localhost:5047

Step 1 — Log in as admin​

Admin bypasses policy evaluation — see IAM — Authentication.

soat login-user --username admin --password Admin1234!
soat configure # paste the token when prompted

Step 2 — Create a project and an AI provider​

A project and a local Ollama AI provider. For other providers see Connect Third-Party LLMs.

PROJECT_ID=$(soat create-project --name "Agent Policies Project" | jq -r '.id')

PROVIDER_ID=$(soat create-ai-provider \
--project-id "$PROJECT_ID" \
--name "Ollama" \
--provider "ollama" \
--default-model "qwen2.5:0.5b" | jq -r '.id')

echo "Project: $PROJECT_ID"
echo "Provider: $PROVIDER_ID"

Step 3 — Create the document the agent will try to overwrite​

Create a document; Step 7 asserts its content is unchanged.

DOC_ID=$(soat create-document \
--project-id "$PROJECT_ID" \
--title "Quarterly Note" \
--content "ORIGINAL CONTENT" \
--path "/notes/quarterly.txt" | jq -r '.id')
echo "Document: $DOC_ID"

Step 4 — Create alice with broad document permissions​

Alice may read and write every document in the project. See Users, Policies and SRNs for the resource scoping.

ALICE_ID=$(soat create-user --username alice-agent-policies --password Alice1234! | jq -r '.id')

POLICY_ID=$(soat create-policy \
--name "alice-agent-policies-full-documents" \
--document '{
"statement": [
{
"effect": "Allow",
"action": [
"documents:*",
"agents:CreateAgentGeneration",
"agents:GetAgent",
"agents:UpdateAgent",
"traces:GetTrace",
"traces:ListTraces"
],
"resource": ["srn:'"$PROJECT_ID"':*:*"]
}
]
}' | jq -r '.id')

soat attach-user-policies \
--user-id "$ALICE_ID" \
--policy-ids '["'"$POLICY_ID"'"]'

soat login-user --username alice-agent-policies --password Alice1234!
soat configure --profile alice

Step 5 — Bind a write tool to the agent​

A builtin tool for update-document, with document_id pinned by preset_parameters. The tool itself is unrestricted.

WRITE_TOOL_ID=$(soat create-tool \
--project-id "$PROJECT_ID" \
--name "docs" \
--type builtin \
--actions '["update-document"]' \
--preset-parameters '{"document_id": "'"$DOC_ID"'"}' | jq -r '.id')
echo "Write tool: $WRITE_TOOL_ID"

Step 6 — Create the agent with a read-only policy​

  • The agent's policy allows documents:GetDocument only. Policies are deny-by-default, so the bound update-document tool is refused.
  • Attaching it needs a caller who holds every grant it carries; admin does.
  • step_rules forces the tool call on step 1 so the refusal does not depend on qwen2.5:0.5b volunteering it. See Step Rules.
READ_POLICY_ID=$(soat create-policy \
--name "summarizer-read-only" \
--document '{
"statement": [
{
"effect": "Allow",
"action": ["documents:GetDocument"],
"resource": ["*"]
}
]
}' | jq -r '.id')

AGENT_ID=$(soat create-agent \
--project-id "$PROJECT_ID" \
--ai-provider-id "$PROVIDER_ID" \
--name "Bounded Summarizer" \
--instructions "You summarize notes. Use your tools when asked." \
--tool-bindings "[{\"tool_id\":\"$WRITE_TOOL_ID\"}]" \
--max-steps 2 \
--step-rules '[{"step":1,"tool_choice":{"type":"tool","tool_name":"docs_update-document"}}]' \
--policy-ids '["'"$READ_POLICY_ID"'"]' | jq -r '.id')
echo "Agent: $AGENT_ID"

:::tip Write agent policies as allow-lists An allow-list stays correct as the agent gains tools: a newly bound builtin action is refused until the policy is widened. A deny-list permits every action nobody thought to deny. :::


Step 7 — Run the agent as alice, and watch the write fail​

The agent's policies are evaluated before dispatch: the tool returns an error result and the generation still completes.

soat --profile alice create-agent-generation --wait true \
--agent-id "$AGENT_ID" \
--messages '[{"role":"user","content":"Replace the note content with: OVERWRITTEN BY THE AGENT."}]' \
| jq '.status'

# The agent's policy refused the write — content is untouched.
soat --profile alice get-document --document-id "$DOC_ID" | jq -r '.content'

# Verify it: this exits non-zero if the agent managed to change anything.
soat --profile alice get-document --document-id "$DOC_ID" \
| jq -r '.content' | grep -qx "ORIGINAL CONTENT"

The tool result the model received:

{
"error": {
"code": "FORBIDDEN",
"message": "Forbidden: agent agent_…'s policies deny documents:UpdateDocument on srn:…",
"meta": {
"action": "documents:UpdateDocument",
"resource": "srn:…",
"denied_by": { "type": "agent", "id": "agent_…" }
}
}
}

Step 8 — Prove the ceiling was the agent's, not alice's​

Same user, token and document, written directly via Documents.

soat --profile alice update-document \
--document-id "$DOC_ID" \
--content "UPDATED BY ALICE DIRECTLY" | jq '.id'

CONTENT=$(soat --profile alice get-document --document-id "$DOC_ID" | jq -r '.content')
echo "Content after alice wrote directly: $CONTENT"

The forwarded credential caps the chain from above; policy_ids cap each agent from below. A prompt injection inherits the agent's ceiling, not alice's.


Step 9 — Attaching a policy needs its grants​

An agent can do no more than whoever attached its policies. Alice may update the agent but does not hold agents:DeleteAgent, so she cannot hand it a policy granting that: 403 POLICY_GRANT_NOT_HELD, with meta.ungranted naming the grant.

WIDE_POLICY_ID=$(soat create-policy \
--name "summarizer-wide" \
--document '{"statement":[{"effect":"Allow","action":["agents:DeleteAgent"]}]}' \
| jq -r '.id')

# → expect-fail
soat --profile alice update-agent \
--agent-id "$AGENT_ID" \
--policy-ids '["'"$WIDE_POLICY_ID"'"]'

A mis-named action is rejected when the policy is written, so a typo'd Deny cannot silently match nothing. Action names: Permissions Reference.


What the agent's policies do and do not cover​

Governed by policy_ids
builtin tools (platform actions)Yes — every action is checked at its route
The built-in write_memory toolYes — fails closed when the policies deny the memory write actions
http, mcp, pipeline toolsWhether the agent may call it (tools:CallTool), not what the server does
client toolsNo — the client runs them

For what a tool's own server does, use Guardrails or Approvals.

The cap applies per hop: a sub-agent called through create-agent-generation resolves its tools under its own policy_ids; the orchestrator's permissions do not widen it.

Next Steps​