Optional app integration
Advanced preview routes, generated clients, webhooks, and delegated authorization for agents that need a small deterministic application boundary.
Optional app integration
This surface is not part of the default agent path and does not make Auggy a general application backend. Its API may change before 1.0; pin exact versions and validate authorization and operational boundaries.
Start with the agent path
Optional, not the default scaffold
Most Auggy projects do not need routes or generated clients. Start with tools. Add this surface only when existing software genuinely needs a deterministic HTTP entry point beside the agent.
Software calls a route when the operation is known. The agent calls a tool when conversation or investigation must determine the operation. Both call one domain function.
These are patterns, not built-ins
Your application still owns infrastructure, authorization records, and domain policy. Use an augment when a route and tool would otherwise duplicate those rules.
Three compact patterns
Manage feature flags
- Software path
- An admin console calls PATCH /flags/:key with an explicit rollout percentage, audience, and change reason.
- Agent path
- During an incident, an engineer asks Auggy to compare telemetry and propose reducing new-checkout for a region. The model gathers confirmation before calling the tool.
- Shared operation
updateFeatureFlag()verifies the flag, environment, rollout bounds, audience, authorization, change window, and audit metadata before writing.- Why Auggy
- The admin UI and incident workflow use the same rollout policy.
Provision preview environments
- Software path
- A GitHub webhook calls POST /environments when a pull request receives the preview label.
- Agent path
- An engineer asks for PR 1842 with sanitized production data, a specific region, and a QA notification. The model turns those constraints into typed input.
- Shared operation
provisionEnvironment()selects approved infrastructure, applies data policy, records owner and pull request, sets expiration, and submits one idempotent provisioning job.- Why Auggy
- Conversation gathers options without creating a second provisioning system.
Run a data backfill
- Software path
- An operations dashboard calls POST /backfills after a dry run has identified the job type, tenant scope, affected rows, and rollback plan.
- Agent path
- An engineer asks Auggy to find customers missing invoice totals, estimate impact, and prepare the smallest safe backfill for approval.
- Shared operation
createBackfill()accepts a reviewed plan, validates the registered job definition, tenant scope, dry-run evidence, concurrency ceiling, approval, idempotency, and rollback metadata.- Why Auggy
- Investigation stays flexible; admission stays inside the registered job system.
Implementation shape
PATCH /flags/:key + update_feature_flag
-> updateFeatureFlag()
POST /environments + provision_preview_environment
-> provisionEnvironment()
POST /backfills + prepare_backfill
-> createBackfill()The plus sign does not mean both paths execute. Routes bypass inference; tools run through the model and tool gates. Each still declares its own auth and rate limits.
Choose the right depth
| Situation | Recommended shape |
|---|---|
| Known operation from CI, UI, or webhook | Call the route directly. |
| Missing fields or ambiguous intent | Let the model gather context, then call a typed tool. |
| Read-only investigation | Use narrow read tools; do not expose the write operation yet. |
| Consequential write | Require application authorization or approval in the shared domain operation. |
| No software caller yet | Start with a tool; add a route when software needs the capability. |