Inflow.aiDocs

Optional technical reference. This material is for developers, integration specialists and platform administrators. For the consultant lesson, read the practical guide.

Preserved from source baseline d4587c7c0e073e58c2d430342f65ac55dd701bf4; source/static examples retain their stated scope. They are not new runtime verification or required consultant setup steps.

Agent Catalog

Choose the policy before creating a run

An agent definition describes a named purpose and bounded tool policy. It is not a user account, an enabled model connection, a workspace grant or a completed automation. A consultant normally selects an admitted definition; an authorized operator maintains the XML catalog. At run creation, the service snapshots the selected policy so later catalog edits do not silently rewrite an existing run.

Read this field Use it to decide
name, description, category Whether the purpose fits your business question.
allowedToolIds / allowedConnectorIds Which requested capabilities are admissible; later native authorization still applies.
preferredModelId / modelPolicy How model selection starts; neither creates a provider connection.
maxIterations / timeoutSeconds The deliberate execution bounds copied into a run.
memoryPolicyId / humanHandoffPolicyId Which policy metadata accompanies the run, without replacing native storage/effect guards.

The four cases below use synthetic people-ops data. Source checks describe the contract; no provider or business operation was executed for this manual. Continue to Agent Execution after selecting the definition.

Example UIAI-AGENT_CATALOG-01 — Find a case agent without starting work

Scenario and inputs. Nadia is preparing a leave-review assistant for the fictional request leave-2026-014. She can view the agent catalog, but choosing a definition does not require sending Mohammad's leave details to a model. Her current authenticated session and effective catalog permission remain the authority.

Procedure. Read GET /api/agents, then search GET /api/agents/search?q=case. Read the exact returned ID with GET /api/agents/{agentId}. Compare the active flag, purpose, allowedToolIds and allowedConnectorIds. Select agent.case.worker only if that actual definition is present; a label containing similar words is not a substitute identifier. Record why the permitted tools fit a summary-only goal.

Expected result. You have selected a policy and understand its limits. Search matches catalog metadata case-insensitively; a blank query includes registry entries. No agent run, model response, task decision or connector effect has been created by these reads.

Failure and recovery. An absent definition requires its operator to inspect the admitted catalog/import. A denied catalog view stays unavailable; do not repeatedly request hidden entries or fabricate an ID in a run request. A successful catalog read also does not prove an enabled model exists.

Sources. Catalog controller, definition fields.

Example UIAI-AGENT_CATALOG-02 — Read a bounded XML definition

Scenario and inputs. An authorized operator wants a demonstration agent that summarizes a leave request and hands consequential decisions to a person. The file below contains policy metadata only, with no credential, account grant or live business record. It uses the shipped catalog envelope rather than a lone agent fragment.

Procedure. Review the purpose, explicit tool allowlist and deliberate limits. Deliver the definition through the owned catalog deployment/import process, then inspect the resulting API record. Editing a documentation snippet does not reload a running registry.

<agentCatalog version="1">
  <agents>
    <agent id="agent.leave.reviewer">
      <name>Leave review assistant</name>
      <category>case-management</category>
      <promptTemplate>Summarize the fictional request and list questions for the manager.</promptTemplate>
      <allowedToolIds>ai.summarize,handoff.human</allowedToolIds>
      <maxIterations>4</maxIterations>
      <timeoutSeconds>120</timeoutSeconds>
      <active>true</active>
    </agent>
  </agents>
</agentCatalog>

Expected result. The imported definition retains the reviewed metadata. Missing name falls back to ID, category to general, and allowed lists to empty. Iterations below one normalize to eight; timeout clamps at zero. These defaults do not enable a provider or authorize an unlisted tool.

Failure and recovery. Correct malformed XML, metadata JSON or missing IDs in the owned file. Do not disable XML security or widen capabilities to silence an import failure. Existing run snapshots retain their original policy; inspect the intended new run separately.

Sources. XML loader, definition defaults.

Example UIAI-AGENT_CATALOG-03 — Select an actual enabled model

Scenario and inputs. The leave-review definition exists, but the environment may have no enabled provider. Nadia owns the consulting goal; an administrator owns provider preparation and disclosure policy. An old seeded model name is not assumed to be available.

Procedure. Have the administrator identify an admitted connection and select a vendor model from that connection's actual catalog. Inspect the AI Gateway model list and use the returned platform ID, normally the selected connection key plus -chat. If the agent requires a preferred model, deliver that actual ID through the reviewed catalog process. Otherwise follow the gateway's purpose/default resolution rather than guessing a name.

Expected result. The chosen model coordinate refers to a real connection-backed model. Catalog inspection can explain the relationship without running a prompt. Capability, classification, workspace policy and current provider readiness are still checked when execution is attempted; a policy label alone establishes none of those conditions.

Failure and recovery. When no enabled model is available, leave the AI action unavailable and request administrator preparation. Repair a stale preferred model through its actual owner. Never place provider credentials in agent XML, copy an obsolete seed ID or describe a stored URL as proof of a reachable qualified model.

Sources. Gateway catalog, connection model selection.

Example UIAI-AGENT_CATALOG-04 — Reject an out-of-policy tool request

Scenario and inputs. A demonstration definition allows only ai.summarize and handoff.human. A proposed run also requests payments.transfer. The fictional goal and record do not justify that additional capability; the purpose is to understand admission before attempting any effect.

Procedure. Compare requestedToolIds with the selected definition first. Remove a capability that is unnecessary, or refer a genuinely required capability to the policy owner for a separately reviewed change. The execution service performs this same subset validation at start. Check requestedConnectorIds independently: allowing a tool does not automatically admit its connector or credentials.

Expected result. An unlisted requested tool is refused with AGENT_TOOL_NOT_ALLOWED; an unlisted connector is refused with AGENT_CONNECTOR_NOT_ALLOWED. A valid subset can create a pending policy-snapshotted run, but later tool services still enforce their own authorization and effect boundaries.

Failure and recovery. Do not expand the allowlist to every tool a model suggested, or treat a prompt saying “ask first” as an access-control mechanism. Keep the intended goal and explain the missing capability. A permitted summary-only request is useful when it actually satisfies that goal; it must not masquerade as the prohibited business effect.

Sources. Start admission, policy refusal tests.

Current source reference. The worked examples are source-reviewed documentation; live execution is NOT_RUN.

The agent catalog defines governed AI agents outside Java code. Agents are loaded from XML under:

conf/agents/

Each XML file can contribute one or more <agent> definitions. The platform loads all *.xml files in sorted order and imports them into AgentRegistryService.

Architecture

flowchart TD
    A["conf/agents/*.xml"] --> B["XmlAgentCatalogLoader"]
    B --> C["AgentCatalogImporter"]
    C --> D["AgentRegistryService"]
    D --> E["/api/agents"]
    D --> F["BPMN service.ai.agent.run"]
    F --> G["AI Gateway"]
    G --> H["Model Runtime Plan"]
    F --> I["Allowed Tools / Connectors"]

XML Shape

Since SCRUM-4817 (2026-11-05) the shipped conf/agents/platform-agents.xml names no catalog models. A preferredModelId must name an enabled connection model (<connectionKey>-chat); otherwise the agent run fails with the plain "choose a model" outcome.

<agent id="agent.connector.operator">
  <name>Connector Operator Agent</name>
  <description>Operates approved connectors under strict policy.</description>
  <category>integration</category>
  <modelPolicy>restricted-local-only</modelPolicy>
  <preferredModelId>my-vllm-chat</preferredModelId>
  <promptTemplate>Plan connector operations and ask for approval before side effects.</promptTemplate>
  <allowedToolIds>connector.rest,connector.jdbc.approved-query,handoff.human</allowedToolIds>
  <allowedConnectorIds>n8n,make,postgresql,google-sheets</allowedConnectorIds>
  <memoryPolicyId>agent-memory-tool-audit</memoryPolicyId>
  <humanHandoffPolicyId>agent-handoff-before-side-effect</humanHandoffPolicyId>
  <maxIterations>15</maxIterations>
  <timeoutSeconds>1200</timeoutSeconds>
  <active>true</active>
  <metadata>{"sideEffectsRequireApproval":true}</metadata>
</agent>

API

Authenticated read-only API:

GET /api/agents
GET /api/agents/search?q=data
GET /api/agents/{agentId}

Required permission:

AGENT_CATALOG_VIEW

The development designer and worker roles receive this permission. root has *.

Seed Agents

The seed catalog includes:

  • agent.research.web
  • agent.data.analyst
  • agent.case.worker
  • agent.connector.operator
  • agent.document.reviewer
  • agent.operations.coordinator

These definitions are policy contracts. Runtime execution is handled by the durable agent-run service and ai-worker nodes. The shipped worker can execute through AI Gateway or approved connectors, persist attempts and logs, use agent memory, and pause in WAITING_FOR_HUMAN before a later resume. Tool- and connector-specific authorization is enforced again at execution time rather than trusting catalog metadata alone.

Agent run lifecycle and runtime APIs are documented in agent-execution.md.

Try “document generation”, “integrations” or “first form”.