Source: docs/integration/reference-implementation.md

HTTP integration reference implementation

This guide describes a minimal server-side adapter for an application that

needs a synchronous Forgium Agent response. It is a development pattern, not a

required framework or deployment model.

Recommended boundary

Keep the Forgium API key and upstream URL behind the host application's

backend:

Client or UI
    │
    │ POST /api/agent/messages
    ▼
Host application adapter
    │  validates input, authenticates the caller,
    │  applies timeout/rate limit, maps errors
    │
    │ POST /v1/channels/http/messages
    ▼
Forgium Agent Public API

Do not call Forgium directly from a browser or mobile client when doing so

would expose FORGIUM_AGENT_API_KEY.

Example adapter contract

The host application may expose a route such as POST /api/agent/messages.

The exact route and framework belong to the host application. A small JSON

contract is sufficient:

{
  "message": "Hello, can you help me?",
  "conversationId": "conv_optional"
}

The adapter maps that request to the public HTTP channel contract:

{
  "user_id": "host-user-id",
  "conversation_id": "conv_optional",
  "message": {
    "type": "text",
    "body": "Hello, can you help me?"
  }
}

The upstream response uses conversation_id; the host adapter may expose the

same value as conversationId to match its own naming conventions. Preserve

that identifier for subsequent messages in the same conversation.

The public OpenAPI contract is authoritative for the

upstream request and response shape. Do not generate a different upstream

payload from this example.

Configuration

Read these values only on the server:

FORGIUM_AGENT_BASE_URL=<value issued for the target environment>
FORGIUM_AGENT_API_KEY=<value issued out of band>

Fail clearly when configuration is absent. A local adapter can return a

configuration error without making an upstream request; this is useful for

local smoke tests. Never include the key in a response, source file, client

bundle, capability manifest, log, or persisted agent context.

Error and resilience behavior

The adapter should make failures actionable without leaking upstream secrets:

Situation	Recommended behavior
Missing configuration	Return a stable configuration error and HTTP `503`; do not call Forgium.
Invalid caller input	Return a validation error and HTTP `4xx`; do not call Forgium.
Forgium rejects authentication	Return a dependency/authentication error, redact the key, and request a matching environment bundle.
Forgium times out or is unavailable	Apply the host retry policy, then return a dependency error with a correlation ID.
Unexpected upstream response	Validate the response before returning it and log only safe diagnostics.

Choose status codes that match the host application's existing API

conventions. Do not retry validation, authentication, or non-idempotent

requests blindly. Follow the idempotency guide when adding

retries or replay protection.

Production checklist

Before exposing the adapter to customer traffic:

[ ] Authenticate the host application's caller.
[ ] Apply rate limiting and an appropriate request body limit.
[ ] Keep FORGIUM_AGENT_API_KEY server-side and store it in a secret manager.
[ ] Configure an explicit timeout and bounded retry policy.
[ ] Redact API keys and message contents from logs unless the product has an
approved data-retention policy.
[ ] Validate both incoming input and the external response.
[ ] Preserve conversation_id only according to the host application's
privacy and retention requirements.
[ ] Add tests for missing configuration, invalid input, upstream 401,
timeout, malformed response, and successful conversation continuation.
[ ] Run the authenticated smoke test against the intended environment.

The host application's authentication and rate limiting are not supplied by

Forgium. They remain required even when the Forgium API key is valid.

Definition of done

A minimal HTTP integration is ready for review when:

local tests pass with mocked upstream responses;
/health or the host equivalent reports dependency configuration without
revealing secrets;
the adapter sends the exact payload described by the public contract;
the response is validated and the conversation identifier is preserved; and
an authenticated smoke test passes for the target environment, or the
access bundle is documented as the remaining blocker.

See Getting started for the first authenticated message

and Contract retrieval when an agent cannot locate the

canonical OpenAPI file.