Forge Documentation

Getting Started

What is Forge?

Forge is an AI agent platform built on enterprise cloud infrastructure, deployable on AWS, Azure, or GCP. You define a team of specialist agents — a requirements analyst, a security architect, a financial modeller, a bid writer — and describe what you want them to produce. The agents execute in sequence, each one receiving the output of the last, and collectively they produce a structured set of deliverables.

Unlike a single AI chat session, Forge gives every agent a specific role, specific instructions, and access to real data from your company profile. The result is not a single response but a pipeline of specialist outputs that build on each other. A typical run might produce 6–12 documents, decisions, and recommendations in the time it would take to draft one email.

Navigating Forge

The left sidebar is organised into four groups so you can quickly find what you need:

Settings is further organised into four tab groups: Profile (Company Profile, Organisation), Billing & Usage (Billing, Impact Report, Usage), Integrations (API Keys, Webhooks, Secret Vault, MCP Servers), and Data (Knowledge Base, Data & Privacy).

Your first run

Running your first team takes about two minutes:

1. Go to Teams (Work group in the sidebar) and browse the 21 built-in templates. Each card shows the team mission and which agents are included.
2. Click "Use team" on the template you want. This takes you to the new run form with that team pre-selected.
3. Write a brief. The brief is your instructions to the team — what you want them to produce, for what context, and any specific constraints. A few sentences is enough to start.
4. Click Submit. Forge starts the first agent immediately. You will see a live timeline updating as each agent completes its work.

If this is your first time using Forge, the dashboard shows a 3-step onboarding checklist to guide you through setting up your company profile, running your first team, and exploring the output hub. Returning users see a collapsible getting-started checklist in the dashboard sidebar. Both can be dismissed once you are comfortable with the platform.

After your first run completes, check the This month card on the dashboard. It shows how many runs you have completed, an estimate of hours saved (based on the template used), and the EUR equivalent at typical consultant day rates. It updates in real time as runs finish.

Understanding statuses

Each run moves through a sequence of states. You can see the current status on the run page and in your run history.

Setting up your company profile

Go to Settings → Profile → Company Profile. This is one of the most impactful things you can do. Without a profile, agents guess your company name, capabilities, rates, and experience. With a complete profile, every run automatically uses your real data.

Fill in: company name (appears in all documents), tagline, core capabilities (what your company actually does), certifications (ISO 27001, Cyber Essentials, SOC 2, etc.), typical day rates (used in cost estimates), team summary, and reference projects. Save once. Every run from that point forward injects this context into every agent.

Teams and Agents

Built-in templates

Forge ships with 21 production-ready team templates. Each template has been designed with a specific mission, a curated set of agents in the correct execution order, and sensible defaults. You can use them as-is or clone them as a starting point for a custom team.

Available templates: DevSecOps Review, Bid Response, Business Plan, Investor Pitch, Board Report, Compliance Audit, Due Diligence, Marketing Campaign, Sales Intelligence, Content Strategy, Budget Planning, Research Report, Product Discovery, Vendor Evaluation, Process Improvement, Procurement Process, Technical Docs, Security Audit, Hiring Pack, Performance Review, Contract Review.

Building a custom team

Go to Teams → Create team. You will be asked for a team name and a mission statement. The mission is injected into every agent's context as a shared goal — write it clearly and specifically.

Pick agent roles from 100+ options. Roles include Market Researcher, Security Architect, Financial Analyst, Legal Reviewer, Persona Builder, Competitor Analyser, PRD Writer, and many more. Set the execution order — agents run sequentially, and each one receives the output of the previous agent as context.

Per-agent instructions

In the team edit page, click the pencil icon on any agent. This opens the instruction editor for that specific agent. Per-agent instructions override the agent's default behaviour and tell it exactly what to focus on for your use case.

Good instructions answer: what should this agent focus on? What data matters? What format should the output take? What should it ignore? Example instructions for a Market Researcher:

Focus on the European B2B SaaS market. Use EUR for all financial figures.
Prioritise data from the last 12 months. Include competitor pricing where
available. Identify the top 5 competitors with their market share estimates.
Reference any GDPR implications for data handling.

The team mission

The team Description field is not just metadata — it is injected into every agent's context as the team's shared mission. When you write a clear, specific mission, agents stay aligned with the goal even if individual briefs are short.

Example of a good mission: "Produce a comprehensive market entry analysis for a new geography, covering competitive landscape, market sizing, regulatory requirements, and a go-to-market strategy suitable for a Series A SaaS company."

Tools and Integrations

How tools work

Tools come in two types. Data tools (also called PRE-phase tools) run before the agent and inject results directly into the agent's context. The agent sees the fetched data alongside the run brief and uses it in its output. Available data tools: Web Search, Web Fetch, PDF Reader, HTTP GET.

Action tools (POST-phase) run after the agent and use the agent's output to take action in an external system. Available action tools: Slack Message, Jira Create Issue, Email, Webhook POST. Action tools support conditional firing so they only run when certain conditions are met.

Web search

Add a Web Search tool to any agent. Set the query using template variables so the search is tailored to each run. Results are automatically shown to the agent before it generates its output.

# Example query using template variables
{{agent.title}} competitor analysis Europe 2025

# Another example for a market researcher
{{agent.title}} market size TAM SAR SOM {{agent.output}}

Template variables

Use these variables in tool configuration fields:

Secret Vault

Go to Settings → Integrations → Secret Vault to store API keys, tokens, and passwords. Secrets are encrypted at rest and never exposed in the UI after creation. Reference them in any tool config field using {{secret.KEY_NAME}}. Never paste raw credentials into tool config fields.

Connecting Jira

Add a Jira tool to an agent (POST-phase). Required fields: base URL (your Atlassian domain), email ({{secret.JIRA_EMAIL}}), API token ({{secret.JIRA_TOKEN}}), project key. Set fire_condition to outcome == "completed" to only create tickets when the agent succeeds.

Connecting Slack

Add a Slack Message tool to any agent. Set the webhook URL using {{secret.SLACK_WEBHOOK}}. In the message template, use {{agent.output}} to include the agent's full findings. Use fire_condition to control when the message is sent.

# Example Slack message template
*{{agent.title}}*

{{agent.output}}

_Confidence: {{agent.confidence}} | Outcome: {{agent.outcome}}_

Workflow Automation

Run chaining

Run chains let the output of one team automatically trigger a new run on another team. Go to a team's tools page and scroll to Run Chains. Pick a target team, write a brief template using the previous run's data, and save. When this team's run completes, the next run starts automatically.

# Example chain brief: Market Analysis → Investor Pitch
Prepare an investor pitch based on this market analysis:

{{output}}

Focus on the market opportunity, competitive positioning, and
financial projections. Target audience: Series A investors.

Available chain variables: {{output}} (full output of the completed run), {{title}} (run title), {{brief}} (original brief). A common pipeline: Market Analysis → Investor Pitch → Board Report.

Inbound webhooks

Go to a team's tools page and enable the inbound webhook. Copy the unique URL. POST to it from any external system — GitHub, Jira, Zapier, Make, or a custom script — and a run starts automatically.

POST https://forge.shanova.se/api/webhooks/{team-webhook-id}
Content-Type: application/json

{
  "title": "PR #142 — Add OAuth2 support",
  "brief": "Review the security and architecture of this pull request...",
  "source": "github"
}

Conditional routing

Set a fire_condition on any action tool. The action only runs if the condition evaluates to true. Leave blank to always fire. Supported operators: ==, !=, >, >=, AND, OR.

# Only fire when high confidence
outcome == "completed" AND confidence >= 0.85

# Fire on success or when flagged for review
outcome == "completed" OR outcome == "blocked"

# Always fire (leave blank, or use)
outcome != ""

Approval gates

Mark any action tool as "Require approval". When the agent finishes, the action is held in a pending state. You will see a notification and a yellow panel on the run page asking you to approve or reject. Use this when you don't want AI outputs going to external systems without a human check — for example, before creating Jira tickets or sending Slack messages.

Scheduled runs

Go to Scheduled (Work group in the sidebar). Create a schedule: pick a team, write a brief template, and set a cron expression. Forge will fire the run automatically at the scheduled time. Useful for recurring reports — weekly market updates, monthly board summaries, daily risk digests.

# Common cron expressions
0 9 * * 1      # Every Monday at 9am
0 9 1 * *      # First of every month at 9am
0 9 * * 1-5    # Weekdays at 9am

Platform Features

Human checkpoints

Some agents may pause mid-run and ask a clarifying question. You will see an "Answer needed" notification and a yellow panel on the run page. Questions appear when an agent needs specific information it cannot infer from the brief — for example, a budget figure, a preferred vendor, or a binary go/no-go decision.

Answer each question and the run continues from where it left off. The run status shows as awaiting_input while waiting. If you don't answer, the run stays paused indefinitely.

Knowledge base

After each completed run, Forge automatically extracts key facts about your organisation from the outputs — company name, capabilities, market position, pricing signals, reference clients. These are stored in your knowledge base and injected into future runs automatically.

View and manage your knowledge base at Settings → Data → Knowledge Base. You can delete incorrect facts, edit entries, or add facts manually.

Projects

Projects let you group related runs together. Create a project in the Projects page, then create runs from within it. All project runs share context and appear together in one view. Useful for ongoing work — "Q1 market research", "Contract reviews for Client X", "Product launch planning".

Global search

Press Cmd+K (Mac) or Ctrl+K (Windows/Linux) from any page in the dashboard to open the search modal. Type any word from a run title or brief and results appear as you type, showing each run's status, team name, and date. Use arrow keys to navigate, Enter to open a run, and Esc to dismiss. The search button in the sidebar nav and the mobile bottom bar also open the modal. Search is case-insensitive and matches across both run titles and brief content.

Notification bell

The bell icon in the left sidebar shows a live red badge when there are unread notifications. Forge creates a notification whenever a run completes, gets blocked, or needs your input at a human checkpoint. Click the bell to see the last 20 notifications. Clicking any notification navigates directly to that run and marks it as read. Use "Mark all read" to clear the badge at once. If you have enabled push notifications in Settings → Notifications, these events also arrive as push alerts.

Output annotations

On any completed run, each output card in the Output Hub has a small + button. Click it to expand an inline text area and type a private note — for example, "Send this section to legal for review" or "Numbers look off — check against Q3 report". Press Save. The note appears below the output as a quoted block. Notes are private: only you can see them. Delete any note with the × button. Use annotations to flag findings for follow-up, add context for handoffs, or mark sections that need human verification.

Usage insights

The dashboard This month card shows runs completed, hours saved (estimated per template type), and the EUR equivalent at typical consultant rates. It updates in real time as runs complete. For a fuller picture across all time periods, see the Analytics section in the dashboard which shows daily and monthly breakdowns, team usage, and recent failures.

Brief templates

Save any run brief as a named template. On the new run form, click a saved template to pre-fill the brief, team selection, and tone. Useful for recurring tasks where you run the same type of analysis on different subjects. You can also set the default tone per template.

Tone selector

Choose output style per run. Options: Formal (boardroom-ready language), Concise (tighter prose, less detail), Detailed (comprehensive coverage), Executive Summary (top-line findings only), Technical Deep-dive (full technical depth with specs). The tone setting affects all agents on that run.

Run comparison

On any completed run, click "Re-run" to start a new run with the same brief and team. After the new run completes, a "Compare with original" button appears. Click it for a side-by-side diff showing what changed between the two runs. Useful for understanding how a change to your brief or team configuration affected outputs.

Cancelling a run

You can stop a queued or running run before it finishes. Open the run page and click the Cancel run button in the sidebar. A confirmation step appears — click again to confirm. The run stops before the next agent starts and its status changes to cancelled. Any outputs already produced by completed agents are preserved in the Output Hub. You cannot cancel a run that has already completed or failed.

Agent performance analytics

The Analytics page now includes an Agent performance table at the bottom. For each agent role it shows how many runs that role has participated in, the average execution time, and the average confidence score. Use it to identify which agents take the longest, which consistently deliver high confidence, and where your pipelines spend the most time.

Cost & Efficiency

Forge runs are significantly cheaper than the alternatives — both in token cost versus naive prompting and in time cost versus manual work. Here is how the numbers break down.

What does a Forge run cost?

A typical run consumes 150k–400k input tokens and 30k–80k output tokens. At GPT-4o pricing ($0.15/1M input, $0.60/1M output) this works out to €0.02–0.10 in token costs per run. Azure infrastructure (Container App + Function App) adds roughly €0.15–0.20 per run when amortised across all concurrent users. Total Forge cost: €0.20–0.35 per run.

Why is Forge more token-efficient than prompting?

A naive multi-prompt conversation accumulates context — each follow-up carries the full history, doubling or tripling token usage across a session. Forge avoids this with three mechanisms:

• Context routing — Each agent receives only the upstream outputs relevant to its role — not the entire run history. A commercial agent does not need the technical architecture; it receives only the requirements and solution design.
• Parallel execution — Independent agents run concurrently within a layer rather than sequentially, eliminating accumulated context between siblings.
• Structured JSON output — Agents return compact JSON rather than conversational prose. A requirements matrix as JSON is 60–70% smaller than the same information formatted as a paragraph.

Forge vs consulting: the ROI

The consulting equivalent value (hours a qualified professional would need) for each Forge template:

Token usage tracking

Forge records input_tokens and output_tokens for every completed run. You can see your personal ROI breakdown in Analytics → Cost vs Value. Platform admins see the full cost P&L (AI tokens + Azure infra + revenue margin) in the Admin → Costs dashboard.

Organisations & Billing

Every Forge account belongs to an organisation. When you sign up, a personal trial organisation is created automatically. Organisation admins can invite team members, manage seats, and upgrade the plan.

Plans: Trial (3 seats, 10 runs/month — free), Starter (10 seats, 100 runs/month — €29/mo), Pro (25 seats, 500 runs/month — €79/mo), Enterprise (custom). Plans are enforced at run creation and member invite time — you will see a clear error if a limit is reached.

Subscribing: Go to Settings → Billing & Usage → Billing, choose a plan, and complete checkout via Stripe. Your plan upgrades instantly once payment is confirmed. Use Manage Billing to view invoices, update your payment method, or cancel.

Inviting members: Org admins can invite by email from Settings → Profile → Organisation. New users receive a magic-link invite email and land on an acceptance page. Existing users are added directly.

API and Integration

Public REST API

Forge exposes a public REST API for creating runs and reading your run history. Base URL: https://forge.shanova.se/api/v1. All requests require an API key passed as a Bearer token. The full OpenAPI 3.0 spec is available at GET /api/v1/openapi.json.

# Create a run
POST https://forge.shanova.se/api/v1/runs
Authorization: Bearer {your_api_key}
Content-Type: application/json

{
  "team_id": "team_xyz",
  "title": "Market Entry Analysis — DACH",
  "brief": "Analyse the DACH B2B SaaS market..."
}

# List runs
GET https://forge.shanova.se/api/v1/runs
Authorization: Bearer {your_api_key}

# Query parameters: ?limit=20 ?status=completed ?team_id={id}

# Response
{
  "runs": [
    {
      "id": "run_abc123",
      "title": "Market Entry Analysis — DACH",
      "status": "completed",
      "team_id": "team_xyz",
      "created_at": "2026-01-15T09:00:00Z",
      "completed_at": "2026-01-15T09:08:42Z",
      "outputs_count": 8
    }
  ],
  "total": 142
}

API key setup

Go to Settings → Integrations → API Keys. Click "Create key". Give it a descriptive name (e.g. "Zapier integration" or "CI pipeline"). Copy the key — it is shown only once. If you lose it, you will need to rotate it. Keys can be revoked at any time from the API Keys settings page.

Inbound webhook payload

Inbound webhooks accept a JSON body. The minimum required fields are title and brief. Any additional fields are stringified and appended to the brief automatically.

{
  "title": "string",    // Required. Used as the run title.
  "brief": "string",    // Required. Used as the run brief.
  "source": "string"    // Optional. Logged as the trigger source.
}

Outbound webhooks

Go to Settings → Integrations → Webhooks and add a URL. Forge will POST a JSON payload to that URL whenever a run completes, fails, is blocked, or is cancelled. You can register up to 10 webhooks per account and toggle each one on or off independently.

# Example payload
{
  "event":            "run.completed",
  "run_id":           "uuid",
  "run_title":        "Market Entry Analysis",
  "status":           "completed",
  "completed_agents": 8,
  "failed_agents":    0,
  "timestamp":        "2026-05-15T10:00:00Z"
}

Every delivery includes an X-Forge-Signature header. This is an HMAC-SHA256 signature of the raw request body using your webhook's signing secret. Verify it on your server to confirm the payload came from Forge and was not tampered with.

# Python verification example
import hmac, hashlib

def verify_forge_webhook(body_bytes: bytes, signature_header: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), body_bytes, hashlib.sha256).hexdigest()
    received = signature_header.removeprefix("sha256=")
    return hmac.compare_digest(expected, received)

# Node.js / TypeScript
import { createHmac, timingSafeEqual } from "crypto"

function verifyForge(body: string, header: string, secret: string): boolean {
  const sig = createHmac("sha256", secret).update(body).digest("hex")
  return timingSafeEqual(Buffer.from(sig), Buffer.from(header.replace("sha256=", "")))
}

Your signing secret is shown in Settings → Integrations → Webhooks under each webhook entry (click "Reveal"). The delivery log shows the HTTP status code, response time, and any error for every attempt. Click "Replay" on any past delivery to resend it without waiting for the next run.

PWA install and push notifications

Forge works as a native app on mobile and desktop. On iOS Safari: tap the Share button, then "Add to Home Screen". On Android Chrome: tap the "Install app" button in the sidebar. On desktop Chrome or Edge: look for the install icon in the address bar.

Once installed as a PWA, go to Settings → Notifications and enable push. You will receive a push notification when: a run completes, a run is blocked and needs your approval, or an agent asks a clarifying question. Each notification links directly to the relevant run page.

TypeScript SDK

The @forge/sdk package is a zero-dependency TypeScript client for the Forge v1 REST API. It works in Node.js 18+, Deno, Bun, and modern browsers.

Installation

npm install @forge/sdk
# or
pnpm add @forge/sdk

Quick start

import { ForgeClient } from '@forge/sdk'

const forge = new ForgeClient({ apiKey: process.env.FORGE_API_KEY! })

// List teams
const { teams } = await forge.listTeams()
const team = teams.find(t => t.name === 'DevSecOps')!

// Create a run
const run = await forge.createRun({
  team_id: team.id,
  title:   'Q3 Security Audit',
  brief:   'Review our Node.js API for OWASP Top 10 vulnerabilities...',
})

// Stream events until done
for await (const frame of forge.streamRun(run.id)) {
  if (frame.type === 'event')  console.log(frame.data.agent_role, frame.data.title)
  if (frame.type === 'status') console.log(frame.data.completed_agents, '/', frame.data.total_agents)
  if (frame.type === 'done')   console.log('Finished:', frame.data.status)
}

// Pull structured outputs
const { outputs } = await forge.getRunOutputs(run.id)
for (const o of outputs) console.log(o.output_type, ':', o.title)

Methods

All methods return typed Promises. streamRun() returns anAsyncGenerator<StreamFrame> — use it with for await...of.

Error handling

import { ForgeClient, ForgeError } from '@forge/sdk'

try {
  await forge.createRun({ team_id: '...', title: '...', brief: '...' })
} catch (err) {
  if (err instanceof ForgeError) {
    console.error(err.message, err.statusCode, err.body)
    // statusCode 429 → quota exceeded
    // statusCode 403 → team not in consumer app allowlist
    // statusCode 409 → run already terminal (cancelRun)
  }
}

Consumer App keys

Consumer apps use frg_app_… keys instead of user keys. Pass your key the same way — the SDK detects the prefix automatically. Consumer app runs are metered (billed per run via Stripe Billing Meters).

const forge = new ForgeClient({
  apiKey: process.env.FORGE_APP_KEY!, // frg_app_…
})

// Attach your own user ID to the run for filtering / analytics
const run = await forge.createRun({
  team_id,
  title,
  brief,
  external_user_id: currentUserId,
})

Support

Forge has a built-in support centre at Support in the sidebar. It combines an AI assistant for instant answers with a human ticket system for anything more involved.

AI assistant

The AI assistant answers questions about using Forge — templates, custom teams, scheduled runs, integrations, billing, and more. Responses are streamed in real time. If the assistant cannot resolve your issue, click Still need help? Open a ticket to escalate with the conversation context automatically attached.

Support tickets

Click New Ticket to open a ticket directly. Choose a category (General, Billing, Technical, Account, or Feature request), write your subject and description, and submit. The Forge team will reply in-app — you will receive a notification when there is a new reply. You can add follow-up messages from the My Tickets tab.

Org admins see all tickets raised by anyone in their organisation under the Organisation Tickets tab and can reply on behalf of the team.