Add Chat to Your App

General Augment is the agent backend for your app. Your product keeps the user interface, auth, billing, and source of truth. General Augment runs the managed agent turn with memory, tools, identity resolution, usage tracking, and observability.

Integration shapeOne backend call per user message.

Your UI talks to your own app backend. Your backend attaches the signed-in user id, calls General Augment, then returns assistant text to the client.

POSThttps://api.generalaugment.com/v1/responses

Request Path

Your chat UIYour app backendGeneral AugmentHermes runtime

Use one stable user value per signed-in app user. That lets General Augment attach memory, tool approvals, usage, and future channel identity links to the same person.

Integration Steps

Create or open a project in the General Augment dashboard.
Generate a project-scoped API key and store it as GENERAL_AUGMENT_PROJECT_API_KEY.
Add a backend route in your app that accepts a user message and calls /v1/responses.
Pass your signed-in app user id as user.
Render the returned output_text in your existing chat UI.

Backend Route Contract

Expose a small route in your own app. The browser or mobile client should only know about your route, not the General Augment project-scoped key.

Client to backendmessage

The latest user message.

Backend to General AugmentuserId

Use your signed-in app user id.

Backend to General Augmentmetadata.source

Set a stable source such as app-chat, support-chat, or mobile-chat.

General Augment to backendresponse.id

Store in logs for debugging, audit, and support.

Backend to clientoutput_text

Render this in your chat UI.

type ChatInput = {
  userId: string;
  message: string;
};

export async function generalAugmentChat({ userId, message }: ChatInput) {
  const response = await fetch("https://api.generalaugment.com/v1/responses", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.GENERAL_AUGMENT_PROJECT_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "balanced",
      user: userId,
      input: message,
      metadata: {
        source: "app-chat",
      },
      stream: false,
    }),
  });

  if (!response.ok) {
    throw new Error(await response.text());
  }

  const payload = await response.json();
  return extractOutputText(payload);
}

function extractOutputText(payload: any): string {
  return (
    payload.output
      ?.flatMap((item: any) => item.content ?? [])
      ?.find((part: any) => part.type === "output_text")
      ?.text ?? ""
  );
}

import os

import httpx


def general_augment_chat(user_id: str, message: str) -> str:
    response = httpx.post(
        "https://api.generalaugment.com/v1/responses",
        headers={
            "Authorization": f"Bearer {os.environ['GENERAL_AUGMENT_PROJECT_API_KEY']}",
            "Content-Type": "application/json",
        },
        json={
            "model": "balanced",
            "user": user_id,
            "input": message,
            "metadata": {"source": "app-chat"},
            "stream": False,
        },
        timeout=30,
    )
    response.raise_for_status()
    payload = response.json()
    return extract_output_text(payload)


def extract_output_text(payload: dict) -> str:
    for item in payload.get("output", []):
        if item.get("type") != "message":
            continue
        for part in item.get("content", []):
            if part.get("type") == "output_text":
                return part.get("text", "")
    return ""

What To Send

user

A stable app user id, such as your database user id. Avoid email addresses when a durable opaque id is available.

input

The latest user message, or a typed Responses-style input array when you need richer conversation context.

metadata

App-specific routing and diagnostics, such as source, workspace_id, plan, or environment.

previous_response_id

Optional continuity when your app wants to resume from a specific stored response.

Response Shape

General Augment returns a Responses-compatible object. For a normal text reply, read the first output_text part from the output list.

{
  "id": "resp_abc123",
  "object": "response",
  "status": "completed",
  "output": [
    {
      "type": "message",
      "content": [
        {
          "type": "output_text",
          "text": "Here is the plan..."
        }
      ]
    }
  ]
}

Production Checklist

SecretsStore GENERAL_AUGMENT_PROJECT_API_KEY in your backend secret manager.

IdentityPass a stable user id for every signed-in user.

LimitsAdd your own app rate limits before forwarding requests.

ToolsKeep tool credentials in General Augment credentials, not prompts.

MetadataSend useful metadata.source values for analytics and debugging.

LogsLog the returned response id in your app request logs.

Connect your API Generate governed tools from an OpenAPI spec.

Identity linking Map channel users back to your app users.

Security model Review tenant, credential, and tool execution boundaries.