AI intake pipeline
An existing AI application — with its own tools, session state and streaming UX — gains Forge governance, token attribution and central agent management without rewriting its core code. Register the app as an External App, point its model calls at Forge’s inference endpoint, and let Forge add a thin governance and accounting layer between the app and the model. Tools still run in the app’s process, session state stays in the app’s database, and streaming is unchanged.Goal
For a Next.js app that drives a five-phase requirements conversation (TRIAGE → FLOW_CONFIRMATION → FLOW → REVISION → COMPLETE):
- Every completion call is attributed to a named External App.
- Every agent invocation passes the Trust Fabric before reaching the model.
- The agent’s model and prompt are managed in Forge, so changing them needs no app redeploy.
- The conversation thread is visible in Forge Console for observation and audit.
Two integration tiers
- Tier 1 — inference bridge (lightweight). The app sends every completion to Forge’s
/api/inference/v1/chat/completionsendpoint instead of a vendor endpoint. Forge adds token attribution, a governance check on every invocation, thread continuity keyed byX-Forge-Thread-Id, and central agent config. In the app you repoint the provider URL, obtain a JWT with the External App’s client credentials before each session, and sendX-Forge-AgentandX-Forge-Thread-Idheaders on every call. - Tier 2 — Forge-native (full migration). The conversation runs inside Forge: tools become Forge tools on the agent, working state lives on the run’s blackboard, and durable writes to outside systems go through a governed platform tool. A blackboard lasts only as long as its chat session or workflow run; anything that must outlast the run belongs in agent memory or a knowledge case. This tier is a larger refactor, and gives you workflow graphs, durable agents, full audit and the live Console end to end.
Actors
Preconditions
- The app is in production with its own model provider configured.
- A Forge deployment is running.
- An External App is registered for the application, with a client ID and secret issued.
- A Forge agent definition (for example
intake-agent) is published with the model and prompt you want.
Walkthrough: Tier 1
- Register the External App. In Forge Console, go to Platform → Developers → External Apps and create the app. Copy the client secret — it is shown once. The External App is what every completion is attributed to.
- Set three environment variables in the app:
FORGE_API_URL(the Forge HTTP API base URL),FORGE_CLIENT_IDandFORGE_CLIENT_SECRET. - Swap the provider config. Replace the vendor inference URL with the Forge inference URL. The endpoint speaks the OpenAI-compatible chat-completions format, so most AI SDK call sites need no other change. Replace the app’s current key flow with the OAuth client-credentials flow against
FORGE_API_URL/oauth/token; the returned JWT is the bearer token for every completion. - Add the Forge headers to every completion:
X-Forge-Agent: <agentId>names the agent whose model and prompt Forge applies, andX-Forge-Thread-Id: <sessionId>keeps every call in one conversation in the same Forge thread. In an AI SDK app, send them through the SDK’s per-call header or metadata option. - Run a conversation and verify. After at least one model turn, open Forge Console’s observation view, filter to your External App, and confirm a thread for your session ID appears with every model call and its token usage. If governance requires approval for an action, the call waits at the gate and appears in the approvals queue.
What this proves
- An existing AI app can adopt Forge governance and accounting by swapping its inference endpoint, without a rewrite.
- The inference endpoint is a drop-in for any AI SDK or chat-completions client.
- Token attribution is automatic: every completion lands against the External App that made it.
- One agent definition can power chat, workflows, factories and External App inference.
Org chart draft editor
Org admins design structural changes — new teams, repositioned agents, new reporting lines — in a staged draft that does not touch the live org chart until publish. Changes accumulate, a before-and-after diff is reviewed, orphaned positions are resolved, and publish applies everything at once.Actors and preconditions
The actor is an org admin with theorg:manage permission. At least one org unit must exist in the live org chart.
Success criteria
- A single shared draft is created and visible to every admin in real time.
- Changes — add, move, remove, restore or retype org units; add, assign, move, restore or remove positions — accumulate without affecting the live tree.
- Removing an org unit with active positions blocks publish until each position is moved or removed.
- Publish applies every change atomically and creates a versioned snapshot.
- Discarding the draft returns the org chart to its live state.
Walkthrough
- Enter edit mode. Go to Workforce → Organization, open the Org Chart tab, and click Edit Org Chart. The amber draft banner appears showing “0 changes”.
- Make changes. From a node’s
⋮menu:- Add Child Unit creates a unit with a green New badge.
- Move to… re-parents a unit, which shows an amber Moved badge.
- Remove Unit marks it red Removing. If it has active positions, the Issues panel opens.
- Assign Worker… on a position picks a worker.
- To change a unit’s type, choose the new type in the unit editor; the preview and the publish both use that proposed type.
- Resolve issues. For each orphaned position, click Move… to relocate it or Remove to mark it inactive. Publish stays disabled until every issue is resolved.
- Review and publish. Click Review & Publish →. The dialog shows Current on the left and After publish on the right, with changed nodes badged and a summary such as “2 units added · 1 position moved”. Click Publish Changes. The live chart updates, the banner disappears, and a snapshot is recorded for audit. When a draft restores an ancestor and its descendant, publish restores the ancestor first, then descendants, then their positions; if the dependencies are incomplete or cyclic, publish stops before writing anything and names the blocked operation.
- Discard (optional). Click Discard in the banner and confirm. Every pending change is dropped.
Real-time collaboration
Only one draft is in flight at a time, shared by every admin who holdsorg:manage. Several admins can edit it at once, and each sees the others’ changes immediately without refreshing.
What this proves
- Structural changes can be staged without disturbing the live org.
- Orphaned positions are caught before publish, not after.
- Publish is atomic: there is no partial state where some units moved and others did not.
- Concurrent admins see each other’s work live.
Splunk notable triage
One agent automates first-pass triage of Splunk Enterprise Security notables. It fetches every unreviewed notable, triages the list in one model pass — assigning risk tiers and writing structured notes back to Splunk — and produces a session summary for the on-call team.Shape
One workflow,splunk-notable-triage, with two Agent nodes that both use the secops-triage agent. Per-node prompts give each step its own instructions.
Preconditions
- A
tool_call:splunkcredential (host URL and auth token) is configured in Forge Console. - The
splunk-notable-triageworkflow and thesecops-triageagent are published. - The built-in
security-alert-triageskill is active.
Walkthrough
- Trigger the workflow from Forge Console or the HTTP API.
- Node 1 — fetch. The agent calls
splunk_search_notableswith| search triage_note="" | head 100and returns the unreviewed notables asoutputs.notables. - Node 2 — triage. The agent receives
inputs.notablesand, for each notable, applies the four-stagesecurity-alert-triagemethod, assigns a risk tier (CRITICAL,HIGH,MEDIUMorLOW) and callssplunk_update_notablewith a structured note. It returns asummary(overview, risk breakdown and escalation guidance) andresults, an array of{ notableId, risk, recommendation }. - Review in Splunk. The analyst opens Notable Events; each triaged notable now carries a
triage_note. The analyst escalates, closes or investigates.
Failure modes
What this proves
- One agent with one skill can drive a multi-step flow against an outside system.
- Per-node prompts let one agent play different roles without separate agent definitions.
- Credentials live in Forge’s credential store, not the prompt, so rotating them needs no workflow change.
- One failed notable does not abort the batch.
Catalog commands
The command catalog promotes the most common sandbox operations from free-formbash -c strings into typed commands. Each catalog entry declares an argument schema (malformed input is rejected before governance runs), a risk class and a network policy. The catalog ships read-only commands with a deny-all network policy:
Check Platform → Commands for the current catalog rather than relying on this list. The built-in
software-engineering skill grants the catalog tools, so an agent that resolves that skill sees them next to the free-form sandbox_action tool.
Goal
For an agent dispatched from a workflow Agent node or a factory worker with a sandbox:- The catalog tools are bound at dispatch, each with an input schema that matches its declared arguments.
- Every invocation is audited with its command ID and disposition.
- Arguments reach the sandbox as a structured list (
{ cmd: "echo", args: ["hello world"] }), never as a shell-interpreted string.
Preconditions
- The built-in command sync has run, so the catalog and its skill grants are present.
- The agent’s skills include
software-engineering, directly or through a parent skill. - The Agent node provisions a sandbox — usually because the agent has the free-form sandbox tool.
Walkthrough
- Check the catalog under Platform → Commands. Each built-in command shows its risk class and its
deny-allnetwork policy, and thesoftware-engineeringskill shows one grant per catalog command. Missing grants mean the sync has not run since the catalog changed. - Run a workflow whose agent has
software-engineering. The skill activates implicitly on engineering-related nodes. On a factory worker, the log names the bound tools, for exampleBound 10 catalog tool(s) … git_status, git_diff, …. - Watch an invocation. The first catalog call boots the sandbox if nothing has yet; later calls reuse it. Forge validates the arguments, runs the per-command policy with the command’s declared risk class, builds the argument list and runs it. Read-only commands are allowed; the audit record shows
pass. - Review the audit record under Trust Fabric → Decisions, filtered to the run. Each catalog invocation shows command tier
1, itscommandId, dispositionpass, reasonread_only_auto_allow, severityinfo, and the resolved worker as the agent. There is no hashed command string — the command ID is the proof the call took the catalog path. - Inspect the arguments (optional). The run’s tool log shows the captured command:
echo({ message: "hello world" })becomesecho 'hello world',cat_file({ path: "src/lib/file.ts" })stays unquoted, and paths with spaces or shell characters are single-quoted. - Provoke an argument failure. Ask the agent to call
cat_filewith nopath. The call is refused withcommand_args_invalidbefore governance runs, so it appears in the tool log but not as a Trust Fabric decision. The agent sees the structured refusal and adjusts.
What this proves
- Skill grants, catalog entries and the sync are wired correctly, and dispatch binds catalog tools alongside the free-form tool.
- Argument validation runs before governance; malformed input never reaches the policy.
- Every catalog invocation is governed and audited by command ID.
- Operator-supplied input stays a discrete argument, never an interpolated shell substring.
Per-command governance
Free-form sandbox commands — shell strings sent throughsandbox_action — are governed one by one. Each invocation gets a structured policy decision (allow, hold-for-approval or block), recorded as the disposition pass, hold or block. This is enforcement: a blocked command does not run, and a held command runs only after its approval is released.
Examples
Walkthrough
- Dispatch a workflow with an Agent node whose agent has the free-form sandbox tool, and have it run one of the commands above.
-
Watch the agent turn. On
passthe command runs and the agent continues. Onholdthe turn waits for an operator in the approvals queue. Onblockthe agent receives a structured refusal and adjusts. The policy check adds no noticeable delay. -
Review the decisions under Trust Fabric → Decisions, filtered to the run. Each free-form invocation shows:
A record missing these fields is a platform bug; report it to the platform team.
-
The safety net fails closed. A dispatch path that does not carry the worker’s identity has its first sandbox command refused with
worker_context_missing, before the policy runs and with no decision recorded. A path that forgets the worker is never let through.
Strict enforcement
Enforcement is unconditional; there is no audit-only mode and no setting to switch it off.- Free-form destructive commands hold for approval.
- Free-form privileged commands block unless the worker has an active exec grant, in which case they are allowed with reason
exec_grant_active. - Catalog commands are checked against the agent’s autonomy level using their declared risk class.
What this proves
- Every free-form sandbox command gets a structured, enforced policy decision.
- The decision record is enough to reconstruct intent, decision and outcome for every invocation.
- Missing worker context blocks a dispatch before the policy runs.
- High-volume command hashes are the candidates for promotion into the typed catalog.
Related
- Recipes: end-to-end builds you can follow.
- Approvals and human tasks: the approval lifecycle these commands use.
- Webhooks: react to events outside Forge.

