Source: docs/integration/agent-policy.md

Configure an agent policy

An agent policy is an optional account-wide configuration that defines

how the agent should behave, not how users should express themselves.

It is managed with the Public API key and applies to new runs on every

channel, including the next message in an existing conversation.

The policy regulates agent behavior across these dimensions:

• Language: Response language, tone, and formality level.
• Topic scope: Which subjects the agent can address.
• Natural interpretation: How to understand user intent regardless of
  phrasing, typos, or colloquialisms.
• Ambiguity handling: When to ask for clarification vs. proceed with
  reasonable assumptions.
• No invention: Never fabricate data, names, amounts, or capabilities
  that don't exist.
• Privacy: What information to protect and how to handle sensitive data.

> Important: The policy should describe agent behavior, not restrict

> how users express their requests. Users will phrase things naturally,

> with typos, abbreviations, and colloquialisms. The agent must interpret

> these flexibly.

The API key is the only source of account ownership. Do not put an account ID

in the URL or manifest.

Policy structure

PUT /v1/agent-policy creates or fully replaces the one active policy.

Fields

At least one of instructions or allowed_topics must be present.

Topic names are compared case-insensitively after trimming.

Unknown fields, empty values, incompatible fields, and bodies larger than

16 KiB are rejected.

Behavioral instructions examples

The instructions field should describe how the agent behaves, not

how users should ask. Focus on:

{
  "version": 1,
  "instructions": "Respondé en español rioplatense. Interpreta las consultas de forma natural: si el usuario dice 'listar consorcios', 'mis consorcios', 'qué consorcios tengo' o 'mostrame los consorcios', todas significan lo mismo. Nunca inventes datos que no devuelvan las capabilities. Si una consulta es ambigua, pedí aclaración en lugar de asumir. Protegé datos sensibles: nunca expongas IDs internos, hashes, o información de autenticación.",
  "allowed_topics": [
    {
      "name": "consorcios",
      "description": "Gestión de consorcios: listado, unidades, gastos, pagos y liquidaciones."
    },
    {
      "name": "cuenta_corriente",
      "description": "Saldos, deudas y movimientos de cuenta corriente."
    }
  ],
  "out_of_scope_response": "No puedo ayudarte con esa consulta."
}

What to put in instructions

Topic scope examples

Use allowed_topics to define which subjects the agent can address.

Each topic needs a name (unique, case-insensitive) and a description

that helps the model match user requests:

{
  "allowed_topics": [
    {
      "name": "gastos",
      "description": "Consulta, creación y pago de gastos del consorcio."
    },
    {
      "name": "unidades",
      "description": "Listado y consulta de unidades funcionales."
    },
    {
      "name": "liquidaciones",
      "description": "Liquidaciones mensuales y expensas."
    }
  ]
}

When allowed_topics is present, the agent only responds to requests

matching at least one topic. Requests outside the allowlist use the

out_of_scope_response or the platform default:

No puedo ayudarte con esa consulta.

Manage the policy

Create or update

curl -X PUT "$FORGIUM_AGENT_BASE_URL/v1/agent-policy" \
  -H "Authorization: Bearer $FORGIUM_AGENT_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @agent-policy.json

The response is 201 for the first policy and 200 for a replacement:

{
  "revision": 2,
  "updated_at": "2026-08-05T14:03:10.123Z",
  "policy": {
    "version": 1,
    "instructions": "Respondé en español rioplatense. Interpreta las consultas de forma natural..."
  }
}

Read current policy

$ curl "$FORGIUM_AGENT_BASE_URL/v1/agent-policy" \
  -H "Authorization: Bearer $FORGIUM_AGENT_API_KEY"

Returns 404 POLICY_NOT_FOUND when no policy exists.

Delete policy

$ curl -X DELETE "$FORGIUM_AGENT_BASE_URL/v1/agent-policy" \
  -H "Authorization: Bearer $FORGIUM_AGENT_API_KEY"

Returns 204 on success, 404 POLICY_NOT_FOUND if nothing to remove.

Deleting the policy restores platform defaults for subsequent runs.

Error responses

Runtime behavior and limitation

The runtime places the validated policy after the platform system prompt

and before the capability-availability instruction. The policy tells the

model how to behave, not how users should express themselves.

User content, images, converted documents, and tool output are untrusted

data and cannot modify the policy.

Allowlist matching is model-instruction behavior in this release. It is

best-effort and is not a deterministic moderation service, content filter,

or safety boundary. Do not rely on it as the only authorization or safety

control for sensitive operations. Capabilities remain independently scoped and

protected by their normal approval and execution safeguards.

Common mistakes