Product Team Integration Spec

General Augment is the agent backend for your app.

This spec is for product, engineering, and partnership teams evaluating General Augment for an existing application. It explains the value, the integration shape, the main product capabilities, and the proof gates to capture before real users rely on the agent.

Executive Pitch

Most product teams can call a model API for a demo. The hard part is turning that demo into a production feature with app identity, user memory, tool permissions, approvals, traces, usage limits, cost controls, channels, support workflows, and security review.

General Augment supplies that missing backend layer. Your team keeps the product, UX, users, app database, business logic, and customer relationship. General Augment provides the managed agent layer around it:

• an Open Responses-compatible /v1/responses backend API for in-app chat and backend workflows;
• durable per-user memory and profile context;
• governed tools generated from app APIs or connected through MCP;
• human approval gates for sensitive writes;
• identity linking across app users and messaging users;
• Telegram, WhatsApp, SMS, and in-app delivery paths;
• usage, traces, audit rows, support bundles, and cost metadata;
• rate limits, budget gates, and plan usage controls;
• GA SDKs, CLI, raw HTTP examples, local mock testing, and dashboard setup surfaces.

The result is not another chatbot. It is the best agent control plane a product team can adopt once and reuse across product chat, backend automations, support workflows, messaging channels, app-owned scheduled or event-driven jobs, and General Augment-managed scheduled jobs.

Availability and maturity

“Open Responses-compatible” means General Augment accepts a Responses-style request and returns a Responses-shaped object on POST /v1/responses; it does not mean every OpenAI API, SDK, model name, hosted file/vector feature, or account-level workflow is implemented by General Augment.

Status	Meaning for an app team
GA-ready	Build against this now for production traffic after project-specific smoke, trace, budget, and support evidence pass.
GA-managed	The capability is available with General Augment-managed setup, quota, channel, or operations support.
Roadmap	Use the app-owned fallback until the public product surface is promoted.
Enterprise terms	Customer-specific commercial, security, support, residency, retention, or regulated-data commitments belong in the accepted customer agreement.

Capability	Current maturity	What a new AI app team should do
Backend agent turns with POST /v1/responses	GA-ready	Call from trusted backend code with a project-scoped key, stable user, metadata, and an idempotency key. Treat it as Responses-style compatibility, not broad OpenAI account compatibility.
Raw HTTP integration path	GA-ready	Use curl or generated backend clients when an SDK is unavailable, especially for mobile apps that must keep General Augment keys server-side.
Stable user scoping and explicit memory lifecycle	GA-ready	Use the same app user id for /v1/responses plus memory store, search, profile, delete, and purge calls. Prove isolation for at least two users before launch.
Local mock and hosted verification	GA-ready	Use genaug mock for offline contract tests, then preserve genaug smoke, genaug verify, and genaug onboarding verify --json evidence for the hosted project.
Technical metering, rate limits, and budget gates	GA-ready	Handle stable 402 and 429 responses in app code and reconcile usage from returned metadata and project usage surfaces.
TypeScript, Python, and CLI package distribution	Partially registry-ready	npm packages @general-augment/sdk and @general-augment/local-imessage are visible at 0.1.1; PyPI currently exposes 0.1.0 for general-augment-sdk and general-augment-cli while source packages target 0.1.1. Use repo-local packages or raw HTTP until PyPI 0.1.1 is visible.
OpenAPI/MCP-generated tools and delegated execution	GA-managed	Start with app-owned execution or low-risk read tools. Delegate writes after tool review, credentials, identity links, allowlists, approval UX, and audit evidence are ready.
Human approval gates	GA-managed	Channel and dashboard/admin approval flows exist. Apps can list pending approvals, approve/deny through admin APIs, and receive signed approval lifecycle webhooks when a project callback URL is configured.
Approval webhooks to the app backend	GA-managed	Configure approval_webhook_url for signed approval.pending, approval.approved, approval.denied, and approval.expired callbacks. Polling/listing approvals remains the fallback and reconciliation path.
App-owned scheduled or event-driven jobs	GA-ready	Run the schedule in the app backend or existing job system, then call /v1/responses with app-scheduled context and the same stable user id.
Managed scheduled-job lifecycle in General Augment	GA-ready	Use the authenticated admin API, genaug jobs, or SDK helpers for the self-serve scheduled-job create/list/pause/resume/delete surface, validation dispatch, and retry history.
Self-serve scheduled-job dashboard UI	Roadmap	Use the API, CLI, or SDK lifecycle while the dashboard management view catches up.
Telegram, WhatsApp, SMS, and identity linking	GA-managed	Use channels included in the launch plan, link channel users back to app users before app-specific tools run, and verify provider webhooks per channel.
Self-serve billing checkout and customer portal	GA-managed	Technical usage, credit, and plan gates exist. Stripe-configured tenants can open hosted Build/Pro/Team Checkout, paid credit top-up Checkout, and Customer Portal sessions. Webhooks can activate plans, record invoice/payment-failure events, and create subscription_included or paid_top_up credit grants. Automatic off-session auto top-up charges require tenant opt-in.
Production billing terms, overages, and support tier	Enterprise terms	Agree commercial terms, included usage, overages, payment path, support owner, and rate window in the customer launch packet.
Healthcare, PHI, HIPAA mode, DPA/BAA, residency, retention, or certification claims	Enterprise terms	Health and care examples are product examples. HIPAA mode is a technical guardrail; regulated commitments are made through signed customer terms.
Production SLA and formal support commitments	Enterprise terms	support@generalaugment.com is the GA support path. Uptime, response-time, incident, deletion, or backup-destruction SLAs are signed customer terms.

What Product Teams Keep

The app keeps	General Augment provides
Product UX and mobile/web surfaces	Agent backend API and managed turn execution
App users, auth, roles, and account model	Project-scoped user resolution and memory scoping
App database and business rules	Agent memory, tool context, and response orchestration
App-owned secrets and user OAuth where preferred	Credential vault and auth proxy for delegated tools
Sensitive side-effect UX where preferred	Approval flows for delegated actions
App support and customer success workflow	Response IDs, trace IDs, usage, logs, audit rows, support bundles
App billing and packaging	Agent-turn metering, budget gates, plan limits, usage exports
Existing API surface	OpenAPI-to-tool generation and MCP tool connections

What It Unlocks

In-App AI Experiences

Add a chat or assistant surface inside an existing product without building the agent platform from scratch. The app calls POST /v1/responses from trusted backend code with a stable app user id, then renders assistant output in the product UI.

Strong first experiences include support triage, onboarding help, account summaries, structured extraction, next-action recommendations, and schema-validated drafts.

Backend Agent Workflows

Your backend can call the same agent from server jobs, workflow handlers, event processors, or admin tools. This adds AI reasoning to existing product workflows without exposing API keys to browser or mobile clients.

User Memory And Continuity

General Augment can store, search, profile, delete, and purge scoped user memory. The same stable user id should be sent on /v1/responses and explicit memory APIs so memory, traces, approvals, and future channel links stay isolated per app user.

Governed Actions And Tool Use

General Augment turns app capabilities into governed agent tools. Teams can import an OpenAPI spec, connect MCP servers, or enable built-ins. Tool execution is controlled by project allowlists, risk metadata, credentials, identity checks, audit rows, and approval policy.

API operation	Default behavior
GET	Read tool, can auto-execute
POST	Write tool, approval required
PUT / PATCH	Write tool, approval required
DELETE	Destructive tool, disabled by default

Human Approval Gates

Sensitive delegated actions can pause before side effects run. Approval rows are scoped to project, user, session, and tool call. Users can approve through supported channels or dashboard/admin flows, depending on the surface.

When approval_webhook_url is configured, General Augment enqueues signed outbound approval events for pending, approved, denied, and expired approvals. Events include a stable event_id, the approval id, project id, user id, session id, tool id, redacted input summary, status, and timestamps. Receivers should verify X-General-Augment-Signature, use event_id for idempotency, and still reconcile with the approval list/admin APIs when needed.

Multi-Surface Delivery

The same project agent can serve product backend calls, in-app chat, Telegram bots, WhatsApp and SMS webhooks, app-owned scheduled workflows, and General Augment-managed scheduled jobs that call the same Responses path. For scheduled work, teams can either keep scheduling app-owned or let General Augment own the generic scheduled-job lifecycle through authenticated API, CLI, and SDK surfaces.

Observability, Support, And Audit

General Augment returns response IDs, request IDs, trace IDs, actual model metadata, token usage, latency, and cost metadata when available. Project APIs and dashboard surfaces expose logs, traces, usage, observability status, support bundles, and PII-redacted tool-call audit rows.

Cost And Abuse Controls

General Augment uses agent-turn metering plus rate and budget controls, including API key rate limits, per-user burst limits, daily plan limits, project/user/feature LLM budget caps, and stable 402 / 429 error reasons.

These controls are the foundation of the customer billing lifecycle. Usage rollups, daily gates, budget caps, threshold notifications, hosted checkout, customer portal, credit grants, reservations, settlement, and billing exports are GA billing controls. Customer-specific rates, purchase orders, and support terms belong in the customer launch packet.

Security And Credential Boundaries

Project API keys stay server-side. Browser and mobile clients call the app backend, and the backend calls General Augment. For delegated tools, credentials are resolved server-side through the auth proxy or app backend; the model sees sanitized tool schemas and sanitized tool results, not raw provider tokens.

Integration Architecture

Browser or mobile app
  -> app backend
  -> POST /v1/responses with project key, stable user id, input, metadata
  -> General Augment project agent
  -> response output, trace id, usage, cost, tool/audit metadata
  -> app backend
  -> app UI or app workflow

When tools are delegated:

General Augment agent
  -> allowed tool schema
  -> approval or credential check when required
  -> auth proxy or app MCP/OpenAPI backend
  -> sanitized tool result
  -> trace, usage, and audit rows

Core Integration Steps

1. Create a General Augment project from dashboard onboarding, genaug projects create, genaug integrate <openapi-url> --auto-deploy, or genaug deploy.
2. Create project-scoped API keys for production, staging, development, and CI. Store raw keys only in backend secret storage.
3. Add the first backend call to the Open Responses-compatible POST /v1/responses API with model, user, input, metadata, and an idempotency key for retry-safe operations. The request is Responses-style and portable for the supported v1 fields, but teams should not assume account-level OpenAI platform compatibility or provider model selection.
4. Store response id, request id, trace id, stable app user id, feature/source metadata, model, token, latency, and cost fields when present.
5. Test offline with genaug mock --host 127.0.0.1 --port 8787 --quiet.
6. Add explicit memory for durable user facts and use the same app user id for memory store/search/profile/delete/purge APIs.
7. Connect app APIs as tools with genaug integrate or MCP, then review generated risk and approval defaults before production.
8. Use approval gates or app-owned execution for sensitive writes.
9. Link channel identities before app-specific tools operate over Telegram, WhatsApp, or SMS.
10. Run genaug smoke, genaug verify, and genaug onboarding verify --json before launch. Treat project_key_execution=PASS as the strongest project-key proof.

Use Case Map

Product category	What General Augment unlocks
Productivity apps	Planning, calendar/email assistants, reminders, meeting prep, follow-up drafting
Support and CRM	Ticket triage, account summaries, next-action recommendations, email drafts, traceable support evidence
Health and care apps	Intake summaries, care-plan guidance, user preference memory, appointment workflows, approval-first writes, and regulated launch packets for PHI, HIPAA, BAA, residency, or production compliance claims
Fintech and operations apps	Workflow copilots, exception triage, policy-aware summaries, approval-controlled actions
Marketplaces and commerce	Buyer/seller support, order summaries, resolution proposals, feature-level budget caps
Consumer apps	In-app assistants, personalized onboarding, durable preferences, channel companions
Developer tools and SaaS	API documentation agents, setup copilots, tenant health checks, usage explanations

Launch Proof Checklist

Capture evidence that:

• the project exists and has the expected slug/name;
• environment keys are separated and server-side only;
• the app backend calls /v1/responses with a project-scoped key;
• project_key_execution=PASS appears in verification output;
• response id, request id, trace id, and idempotency key are stored in app logs;
• local mock contract tests pass in CI;
• memory behavior is proven for the app users in scope;
• generated tools are reviewed, allowlisted, and governed;
• write tools have approval UX or app-owned execution;
• destructive tools are disabled unless explicitly accepted;
• channel identity links are tested before channel users rely on app-specific tools;
• 402 and 429 responses are handled in app code;
• dashboard project, tools, integration, analytics, users, and observability surfaces open for the same project;
• returned trace IDs can be retrieved through trace or support-bundle surfaces;
• commercial, compliance, residency, retention, and support terms are accepted for the planned traffic and data type.

Current Readiness Boundary

The GA-ready core is a backend-owned app integration that calls /v1/responses with a project-scoped key, stable user id, trace metadata, budget handling, local mock tests, and hosted verification evidence.

GA-managed surfaces include generated tools, delegated tool execution, channels, approval workflows, and signed approval lifecycle webhooks. GA-ready scheduled-job management is available through API/CLI/SDK surfaces. Roadmap or Enterprise-term surfaces include dashboard scheduled-job management, customer-selectable residency, DPA/BAA workflows, compliance attestations, and formal SLA/support commitments. Use the availability matrix above when deciding whether a partner can launch now, should keep a capability app-owned, or should attach Enterprise terms.

Recommended First GA Launch

Pick one narrow app surface, keep sensitive writes app-owned for V1, call /v1/responses from the backend with stable user ids and trace metadata, add explicit memory only for durable facts, use local mock tests in CI, run hosted smoke and onboarding verification, then review traces, usage, costs, and support evidence after internal dogfood traffic.

Useful next reads: Quickstart, Add chat to your app, Integration examples, Connect your API, SDK reference, Security, Compliance and Security Pack, and Status and Readiness.