Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/omnigent-ai/omnigent/llms.txt

Use this file to discover all available pages before exploring further.

Session-level policies are the most granular level of governance in Omnigent. They apply only to a single session and are evaluated before agent-spec policies and server-wide default policies. You can attach policies at any time during a session’s lifetime — for example, to restrict what tools are available for a specific task, or to require human approval before sensitive operations.
You can also ask the agent in chat to add a policy. It calls the sys_add_policy built-in tool for you, which is equivalent to POST /v1/sessions/{id}/policies. Asking in chat is often faster for interactive use.

​
List Session Policies


GET /v1/sessions/{session_id}/policies Returns all active policies for a session. Includes both store-persisted policies (added via the API or chat) and spec-declared policies (defined in the agent’s YAML). Spec-declared policies have id: null and cannot be patched or deleted through this API. Path parameter: session_id — the session/conversation identifier. Response: 
{
  "object": "list",
  "data": [
    {
      "id": "pol_abc123",
      "name": "ask_on_os_tools",
      "type": "python",
      "handler": "omnigent.policies.ask_on_os_tools",
      "enabled": true,
      "source": "session",
      "created_at": 1700000000
    },
    {
      "id": null,
      "name": "block_long_sleep",
      "type": "python",
      "handler": "omnigent.policies.block_long_sleep",
      "enabled": true,
      "source": "spec"
    }
  ]
}
​
id
string
Policy identifier, e.g. "pol_abc123". null for spec-declared policies.
​
name
string
Human-readable policy name. Unique within the session.
​
type
string
Handler discriminator: "python" or "url".
​
handler
string
Dotted import path (python) or HTTPS URL (url).
​
enabled
boolean
Whether the policy is currently active.
​
source
string
"session" for API-attached policies; "spec" for agent-spec-declared policies.

​
Attach a Policy


POST /v1/sessions/{session_id}/policies Attaches a new policy to a running session.
​
name
string
required
Human-readable policy name. Must be unique within the session, e.g. "ask_on_os_tools".
​
type
string
required
Handler discriminator: "python" (dotted import path) or "url" (HTTPS endpoint).
​
handler
string
required
The policy callable. For type: "python": a dotted import path, e.g. "omnigent.policies.ask_on_os_tools". For type: "url": an HTTPS endpoint, e.g. "https://policies.example.com/eval".
​
factory_params
object
Optional keyword arguments passed to the handler when it is a factory function. Only valid for type: "python". Example: {"allow_list": ["git", "npm"]}.
Example — attach ask_on_os_tools: 
curl -X POST \
  "http://localhost:6767/v1/sessions/conv_abc123/policies" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ask_on_os_tools",
    "type": "python",
    "handler": "omnigent.policies.ask_on_os_tools"
  }'
Response — the created policy object: 
{
  "id": "pol_abc123",
  "name": "ask_on_os_tools",
  "type": "python",
  "handler": "omnigent.policies.ask_on_os_tools",
  "enabled": true,
  "source": "session",
  "created_at": 1700000000
}
Returns 409 Conflict if a policy with the same name already exists on the session.

​
Get a Session Policy


GET /v1/sessions/{session_id}/policies/{policy_id} Retrieves a single session policy by ID.

​
Update a Session Policy


PATCH /v1/sessions/{session_id}/policies/{policy_id} Updates a policy’s mutable fields. The type field is immutable — delete and re-create to change it.
​
name
string
New policy name. null leaves unchanged.
​
handler
string
New handler path or URL. null leaves unchanged.
​
enabled
boolean
Enable (true) or disable (false) the policy. null leaves unchanged.

​
Remove a Policy


DELETE /v1/sessions/{session_id}/policies/{policy_id} Removes a policy from the session. Idempotent — deleting a missing policy returns 204. 
curl -X DELETE \
  "http://localhost:6767/v1/sessions/conv_abc123/policies/pol_abc123" \
  -H "Authorization: Bearer <token>"
Response: 
{ "deleted": true }

​
Evaluate a Policy


POST /v1/sessions/{session_id}/policies/evaluate Evaluates all policies for a session against a hypothetical action, without executing it. Useful for testing policy configurations before deploying them, or for hook-driven integrations (e.g. Claude Code’s PreToolUse hook). The request body follows the proto-compatible EvaluationRequest envelope: 
{
  "event": {
    "phase": "PHASE_TOOL_CALL",
    "tool_name": "bash",
    "arguments": {"command": "rm -rf /tmp/cache"}
  }
}
Response — EvaluationResponse: 
{
  "result": "ALLOW",
  "reason": null,
  "data": null
}
​
result
string
Policy verdict: "ALLOW", "DENY", or "ASK" (requires elicitation).
​
reason
string
Human-readable explanation of a non-ALLOW verdict.
​
data
object
For content-rewriting policies, the modified request payload. null otherwise.

​
Policy Evaluation Order

Session-level policies are evaluated in this order:
  1. Session policies (attached via POST /v1/sessions/{id}/policies) — most specific
  2. Agent spec policies (declared in the agent’s YAML policies: block)
  3. Server-wide default policies (managed via GET /v1/policies) — most general
The first DENY or ASK verdict in any layer wins. ALLOW continues to the next layer.
For built-in policy handlers and their factory_params schemas, see the Policy Registry and the Built-in Policies reference. For the governance model and policy authoring guide, see Policies guide.

Build docs developers (and LLMs) love

Get started for freeTalk to us