Agents
The core execution unit — a configured AI assistant with a system prompt, model, and tools.
An agent is the smallest independently executable unit in UnderOcean. It bundles together everything needed to have a model respond to input:
- A system prompt (versioned — editing it creates a new agent version)
- A provider configuration (which model, via which provider)
- Generation parameters: temperature, max tokens
- Optional reasoning effort (
none|low|medium|high) — when set on a model that supports extended thinking/reasoning, its reasoning trace is streamed and persisted alongside the answer; see Executions & Streaming - Optional response format — make every answer JSON that follows a JSON Schema; see Executions & Streaming
- Optional tool assignments (see MCP)
- Optional memory configuration (see Context Management)
- Optional knowledge base access for Agentic-RAG
Configuration rules
Agent writes are validated, so a bad value is a 422 that names the problem instead
of a failure at run time:
nameis trimmed and cannot be empty;system_promptis at most 100,000 characters.llm_provider_config_idmust be an LLM provider of the agent's project or organization (not an embedding provider, not another organization's).knowledge_config.knowledge_base_idsandmcp_server_idsmust exist in the agent's own project and cannot repeat.memory_configacceptsstrategy(summarization|hybrid),max_tokens_before_summary,max_summary_tokens,enable_key_extraction,extraction_intervalandmemory_retrieval_k;guardrails_configaccepts the guardrail switches as real booleans. Unknown keys are refused. Fields you leave out take their default on create and keep their current value on update.- Switching on
toxic_content_filterneeds an OpenAI provider (on api.openai.com, no custom base URL) in the agent's project or organization; without one the write is a422withcode: "guardrail_unavailable"(see Guardrails). - Unknown top-level fields are refused too.
response_formatis{"type": "json_schema", "json_schema": {"name", "schema", "strict"}}(or{"type": "text"}/nullfor free text). The schema must be a valid JSON Schema whose root is an object, at most 32,000 characters, with$refs that stay inside it (#/...); withstrict: trueevery object also needsadditionalProperties: falseand all its properties inrequired.PATCHwithnullclears it. It is part of an agent's version history.
Versioning
Agents are versioned rather than mutated in place. Updating the system prompt creates a new version; past versions remain available for rollback and for correlating historical executions with the prompt that produced them.
Beyond the prompt, every agent also has a bounded version history of its
whole configuration (the last 10 versions, with the same merging, sealing and
restore behavior as flows). The
agent page has a History button, updates accept expected_revision to
avoid overwriting concurrent edits (409 revision_conflict), and an
execution can run a saved version with the version parameter.
The agent page is also kept in step with changes made elsewhere, such as by the AI assistant or in another tab: while the form has no unsaved edits it reloads the newer content by itself, and a save always carries the revision the form was loaded with, so a stale form can never silently overwrite newer work — you get the revision-conflict dialog instead.
Execution
An agent is executed by creating an execution resource. Every execution runs on the same orchestration engine, so streaming, checkpointing, and reasoning-step visibility apply uniformly whether you're running a single agent or a multi-step flow. See Executions & Streaming.
Guardrails
Guardrails are switches on the agent (guardrails_config, all off by default). They follow the
OWASP guidance for LLM applications (LLM01 prompt injection, LLM02 sensitive information
disclosure, LLM05 improper output handling) and the "fail securely" principle: a guardrail that
is on but cannot work never skips silently. Guardrails are one layer of defence, not a
guarantee — keep tools least-privileged and treat model output as untrusted.
| Switch | Checks | Notes |
|---|---|---|
prompt_injection_shield | user input, before the model call | Phrase patterns in English, Turkish, German, French and Spanish, matched after normalization: invisible characters removed, Unicode folded (full-width, look-alike Cyrillic/Greek letters, accents), spaced-out letters, leetspeak, Base64/hex payloads decoded. Catches known phrasings, not every paraphrase. |
toxic_content_filter | user input, before the model call | OpenAI omni-moderation-latest (multilingual). Needs an OpenAI provider. |
pii_redaction | answer, and the stored run input | Fixed-format identifiers with checksums, see below. |
data_leakage_prevention | answer | API keys and tokens (OpenAI/Anthropic, GitHub, Slack, Stripe, Google, AWS, JWT, Bearer/Basic), password=/secret=, private-key blocks, credentials inside URLs and secrets in URL query strings. |
sensitive_topic_guard | answer | Appends a medical/legal/financial disclaimer. |
garbled_output_filter, output_injection_guard | answer | See below. |
When a guardrail cannot run. The toxic filter calls the OpenAI moderation endpoint, so it
needs an OpenAI provider without a custom base URL (custom endpoints, Azure and other vendors do not serve
it); the agent's own provider is used when it qualifies, otherwise the oldest OpenAI provider of
the project or organization. Saving an agent with the filter on, or starting a run, without such
a provider is a 422 with code: "guardrail_unavailable" (toxic_content_filter requires a moderation-capable provider). If the provider disappears or the moderation endpoint cannot be
reached while a run is in progress, the request is blocked with that reason rather than
answered unchecked (fail-closed). The agent page shows a notice next to the switch.
Observability. Whenever a guardrail blocks a request or changes a response, the run carries a
step event with phase: "guardrail", action (blocked | changed), guardrails (the
switch names) and content. The same step is kept in the stored run (reasoning.steps), and
for flows in the step trace of the Agent node. Comparing a run with a switch on and off therefore
shows exactly what it did.
With PII redaction on, e-mail addresses, phone numbers, card numbers (Luhn-checked), IBANs,
IP addresses, Turkish national IDs (checksum-checked) and Turkish tax numbers (checksum-checked,
only when labelled, e.g. Vergi No:; a bare 10-digit number is too ambiguous) are masked in the
response, and in the stored run input once the run ends. This also holds for a flow run whose
Agent node uses an agent with the switch on: the flow's stored input and step trace are masked, and so is the
Agent node's session memory: it is stored masked, with the original values kept encrypted beside it, so later
turns still see them and nothing has to be asked again.
Names and places are deliberately not masked. Detecting them needs a language-specific model, and
the ones available to us are unreliable on Turkish: on ordinary Turkish sentences they labelled a person or
place in sentences that contained none ("Garanti Belgesi", "Haftaya Salı", "nasıl sıfırlayabilirim") and
rewrote "bu isteği yerine getiremiyorum" as <PERSON>. Masking those would
corrupt answers while still missing real names, so they are left alone until a Turkish-capable
model with an acceptable false-positive rate is available. If you must not store names, do not
rely on this switch for them.
The garbled output filter blocks a response that looks corrupted. It checks the prose of the
answer (code blocks are exempt) for: raw model control tokens, several writing systems mixed in
one passage or inside single words, long runs of the same character or phrase, replacement or
unassigned characters, template syntax such as {{ }}, and an abnormal share of symbols
(digits, emoji, tables, URLs and valid JSON do not count). The typical catch is the multilingual
noise a model produces at temperature 2.0. A blocked response is replaced by a short
"Response blocked" message that says why. Independently of this filter, model control tokens and
invisible characters are always removed from answers, see
Output normalization.
The output injection guard checks the answer for injected-instruction markers (a pattern layer, always on) and, when your administrator has enabled the optional prompt-injection classification model, with that model as well. Without it the guard runs the pattern layer only.
Related
- Flows — orchestrate multiple agents together
- Providers — how model access is configured
- Guides → Build your first agent