Authoring Quickstart

This is the shortest path from agent source to a hosted run.

Minimum Agent

import { defineAgent, step } from '@forge/sdk';
import { z } from 'zod';

const Input = z.object({ value: z.string() });
const Output = z.object({ result: z.string() });

export default defineAgent({
  identity: {
    name: 'transform_text',
    scope: 'dept/ops',
    authority: 'ops',
  },
  triggers: [{ id: 'manual-entry', type: 'manual', enabled: true }],
  workflow: ['transform'],
  trust: { initialTier: 'medium' },
  steps: [
    step('transform', Input, Output, async (input) => {
      return Output.parse({ result: input.value.toUpperCase() });
    }),
  ],
});

Validate Source

Use the same local TypeScript and unit-test workflow you already use for application code. Keep step schemas explicit and parse step outputs so contract failures happen close to the code.

Hosted validation runs when source is saved in Iron Gorilla. Resolve analyzer diagnostics before deploying; diagnostics include stable issue codes and source locations when available.

Deploy

1. Save the agent source in Iron Gorilla.
2. Resolve hosted validation diagnostics.
3. Deploy the validated source.
4. Confirm the deployed version and available triggers.

Deploy signs the validated source and registers the runtime metadata needed for governed execution.

Test A Run

Start with a manual trigger and a small payload:

{
  "value": "pilot"
}

Inspect the run detail for trigger metadata, step output, approvals, policy decisions, and final output. Use webhook, cron, or chat triggers after the manual path is predictable.

Kernel Calls

Use kernel.* inside steps for effects that must be governed by Iron Gorilla:

kernel.* calls require the hosted runtime because policy, approvals, connectors, LLM routing, data access, audit, and replay state live in Iron Gorilla.

Common Failures

SDK and runtime failures expose stable AgentSdkError.code values such as ACTION_DENIED, REPLAY_DIVERGENCE, RATE_LIMITED, and SUBPROCESS_PROTOCOL_ERROR so callers do not need to branch on message text.