Agent Services / Documentation
From a schema to a useful result
Start locally. Keep production providers disabled until their readiness and approval requirements are satisfied.
1. Use a workspace identity
The synthetic reference console has an explicit loopback-only development login. Production account login is unavailable until a provider is configured and verified. Existing Auth.md catalog keys remain read-only and cannot access workspace services.
2. Scope a project key
Issue an als_ key for only the operations and resource access needed. Store its one-time value securely. Never put keys in URLs, screenshots or source code. Browser sessions instead use an HttpOnly cookie and a CSRF token.
3. Submit a bounded job
POST /api/v1/jobs
Authorization: Bearer <SCOPED_SERVICE_KEY>
Idempotency-Key: your-stable-logical-request-id
Content-Type: application/json
{
"service_id": "S02",
"operation": "compare",
"operation_version": "1.0.0",
"parameters": {
"left": {"rows": [{"id": "001", "amount": "10.00"}]},
"right": {"rows": [{"id": "001", "amount": "10.01"}]},
"key_fields": ["id"], "field_map": {"amount": "amount"},
"normalization": {}, "tolerance_policy": {"amount": "0.01"},
"blank_policy": "distinct"
},
"max_units": 10
}The API returns HTTP 202 and a job ID. Reuse the same idempotency key and identical request on retry; changed content with the same key returns 409. Poll the job and event routes for actual progress. No progress percentages are invented.
4. Review coverage and evidence
Completed results distinguish reference, simulation and provider execution. Artifacts require current project authorization. Warnings, unchecked sources and review decisions remain visible. A provider acceptance is not proof of delivery.
5. Keep authority separate
Only a permitted human session can approve an exact, unexpired proposal. Changes to recipients, body, destination, amount or policy invalidate approval. A key, tool annotation or agent-supplied flag cannot approve an action.
Files, retention & deletion
Files enter private quarantine. Checksums, type, resource limits and structural scanning are checked before work. Reference structural scanning is not antivirus. Production scanning and storage must be configured separately. Deletion revokes active access immediately; physical purge and backup expiry are tracked independently.
Actionable errors
| Status | Meaning | Next step |
|---|---|---|
| 400 / 413 | Schema or limit failure | Correct the indicated field or reduce input |
| 401 / 403 | Identity or policy denied | Check current membership, key scope and browser CSRF |
| 404 | Unavailable or not-owned resource | Use the correct authorized project |
| 409 | Idempotency, version, runtime or approval conflict | Review changed inputs; do not broaden approval |
| 429 | Hard budget or rate limit | Respect Retry-After; no automatic overage |
| 503 | Unavailable engine/provider | Use the documented local path or complete setup |
SDK & MCP
Typed SDK and stdio MCP integrations use the same operation policies. Remote MCP OAuth is a separate security boundary, never a renamed anonymous catalog key. See the repository runbooks for current packaging and provider setup.