@sdlcagent/agent-sdk

Contract library for Sage platform agents. Provides the HTTP server scaffold, the ContextEnvelope / ResultEnvelope contract types (validated with Zod), structured logging, and error types that every Sage agent runtime is expected to implement against.

Install

npm install @sdlcagent/agent-sdk

Quick start

An agent implements a single handler — (ctx: ContextEnvelope) => Promise<ResultEnvelope> — and hands it to AgentServer, which exposes /invoke, /health, /ready, and /start over HTTP.

import { AgentServer, type AgentHandler } from '@sdlcagent/agent-sdk';
import manifest from './agent.manifest.json';

const handler: AgentHandler = async (ctx) => {
  // ctx is a validated ContextEnvelope
  return {
    status: 'SUCCEEDED',
    summary: 'Did the thing',
    output_data: { result: 42 },
  };
};

AgentServer.start({ manifest, handler });

agent.manifest.json must contain at least agent_id and version.

Endpoints

| Method | Path | Purpose | | ------ | --------- | ------------------------------------------------------------------- | | POST | /invoke | Parses the request body as a ContextEnvelope, runs handler, validates and returns a ResultEnvelope. Never throws over HTTP — failures come back as status: "FAILED" with a 200. | | GET | /health | Returns { status, agent_id, version, image_digest }. | | GET | /ready | Returns { status: "ready" }. | | POST | /start | Injects per-tenant runtime env vars ({ env_vars: {...} }) before the first /invoke. |

Configuration (env vars)

• AGENT_PORT — port to listen on (default 8080)
• AGENT_TIMEOUT_MS — per-invocation handler timeout (default 300000)
• LOG_LEVEL — debug | info | warn | error (default info)

A .env file in the process working directory is loaded automatically on import.

Envelopes

ContextEnvelope

The validated input to every agent invocation (parseContextEnvelope is called internally by AgentServer, but is exported for standalone use):

import { parseContextEnvelope, type ContextEnvelope } from '@sdlcagent/agent-sdk';

const ctx: ContextEnvelope = parseContextEnvelope(req.body);

Key fields: org_id, project_id, team_id, run_id, step_id, workflow_type, run_mode ('CREATE' | 'MODIFY_ENHANCE'), trigger, work_item_context, policy_snapshot, prompt_refs, redaction_profile, memory_refs?, agent_config, log_callback_url, step_token.

Throws ContextEnvelopeParseError (code CONTEXT_INVALID) on validation failure.

ResultEnvelope

The validated output every handler must resolve to:

import { validateResultEnvelope, type ResultEnvelope } from '@sdlcagent/agent-sdk';

Key fields: status ('SUCCEEDED' | 'FAILED' | 'HITL_REQUIRED'), summary, output_data?, action_requests?, artifacts_created?, critic_signal?, hitl_reason?, hitl_options?, remember?, agent_summary?, next_step_hint?, metrics?.

Throws ResultEnvelopeValidationError (code OUTPUT_BUILD_FAILED) on validation failure.

Errors

AgentError is the base error type for agent handlers, carrying a stable code, a retryable flag (derived automatically per code unless overridden), and an optional detail payload:

import { AgentError } from '@sdlcagent/agent-sdk';

throw new AgentError('MODEL_ERROR', 'LLM returned garbage');

Codes: CONTEXT_INCOMPLETE, CONTEXT_INVALID, MODEL_ERROR, MODEL_REFUSED, ACTION_FORBIDDEN, WORK_ITEM_PARSE_ERROR, OUTPUT_BUILD_FAILED, TIMEOUT, UNEXPECTED, and the Model Rail gateway codes INVALID_REQUEST, BUDGET_EXCEEDED, PURPOSE_NOT_ALLOWED, POLICY_NOT_FOUND. Any error thrown out of a handler is caught by AgentServer and turned into a FAILED ResultEnvelope.

Logging

logger writes structured JSON lines to stdout and threads run context (run_id, org_id, project_id, step_id, agent_id) through AsyncLocalStorage, so any log call inside a handler automatically carries it:

import { logger } from '@sdlcagent/agent-sdk';

logger.info({ event: 'DOING_WORK' });

await logger.time('llm_invoke', async () => {
  // logs STEP_START / STEP_END / STEP_ERROR with duration_ms
});

emitLog(ctx, phase, message, opts?) posts a log line to the run's log_callback_url (best-effort, swallows errors) using one of the fixed AGENT_PHASES: context_parse, llm_invoke, llm_complete, critic_tier1, critic_tier2, tool_call, artifact_write, result_emit.

Development

npm run build         # compile to dist/
npm test              # run the jest suite
npm run test:coverage
npm run typecheck