Integrations

This guide describes 0.2.0-rc14 integration contracts. AOS governs requests sent through its API and runtime. It does not acquire a vendor subscription, grant cloud permissions, or make an arbitrary website executable.

Getting started · Environment walkthrough · Identity and governance · Deployment · Security

Choose the right connection

Native cloud SDK operations, provider-specific pagination, long-running jobs and unusual payload formats may need an adapter you operate. Keep that adapter narrow: validate inputs, scope credentials, expose job status, report uncertain effects and avoid blind retries. The local workspace provider is a concrete example of that boundary; it does not provision cloud VMs or GPUs.

1. Prepare your installation and credentials

Use an authenticated AOS server with a ready connector runtime. Obtain its origin, tenant and an appropriately scoped token file from your administrator:

export AOS_URL='https://aos.example.com'
export AOS_TENANT_ID='engineering'
export AOS_TOKEN_FILE="$PWD/operator-token.txt"
chmod 600 "$AOS_TOKEN_FILE"
aos product request GET /v1/identity/me
aos product runtime nodes

Replace these example values. Tokens are issued by your identity provider, not this guide. The caller’s tenant must match the signed token claim. For the local end-user case, use Environment walkthrough, which handles disposable identity and runtime setup.

Put provider credentials in the server/runtime environment where the call runs. Exporting a key only in the operator’s CLI terminal does not configure a separate server. Use mounted mode-0600 secret files or a secret manager; do not put key values in JSON, source control, screenshots, or URLs.

Supported references include:

Cloud secret clients and AWS signing need the optional dependencies installed in each relevant Python environment:

python -m pip install './aos_core-0.2.0rc14-py3-none-any.whl[secrets]'

Use least-privilege workload identities for secret-manager access. Secret retrieval credentials and permission to execute an operation are separate controls. AOS does not continuously obtain or refresh arbitrary SaaS OAuth tokens: supply a currently valid token through your secret system, or operate a narrowly scoped OAuth adapter.

2. Connect a model

UI: Open the installation’s /console/, connect your tenant and token file, choose AI Gateway, then Connect provider. Select the adapter, base URL, secret reference, model IDs and supported operations. Save, then inspect verification status. A successful probe can activate this AI connection; it is not the separate tool-contract review described below.

CLI: Save model-connection.json. Replace YOUR_ENABLED_MODEL_ID with a model enabled in your vendor account; do not assume a model name grants access.

{
  "name": "engineering-model",
  "adapter": "openai-compatible",
  "provider": "openai",
  "endpoint": "https://api.openai.com/v1",
  "credential_ref": "file:///run/secrets/model-key",
  "models": ["YOUR_ENABLED_MODEL_ID"],
  "default_model": "YOUR_ENABLED_MODEL_ID",
  "operations": ["chat.completions"]
}

aos product --output model-connection-result.json request POST /v1/ai/connections --file model-connection.json
aos product request GET /v1/ai/connections

For Anthropic, use adapter: "anthropic", provider: "anthropic", base URL https://api.anthropic.com/v1, and your enabled Claude model. For native Gemini, use adapter: "gemini", provider: "google", base URL https://generativelanguage.googleapis.com/v1beta, and your enabled Gemini model. The adapters use their native authentication and request formats. Do not combine Gemini’s native URL with its separate OpenAI-compatibility path. A compatible service such as Ollama uses its own /v1 base URL; localhost access requires an explicitly local connector/network configuration.

Read the returned connection ID. Save chat-request.json, replacing the ID and model:

{
  "connection_id": "REPLACE_WITH_CONNECTION_UUID",
  "model": "YOUR_ENABLED_MODEL_ID",
  "messages": [{"role": "user", "content": "List three checks before increasing inference capacity."}],
  "max_tokens": 160
}

aos product request POST /v1/ai/chat --file chat-request.json

UI equivalent: choose the active connection in AI Gateway’s chat action, enter the same request and inspect its response, usage and trace. Start with non-sensitive text and a small output limit. Calls can incur vendor charges. Configure real request/token/cost limits in Usage → New budget; the estimated-cost ledger is not a provider invoice, and default zero prices do not mean free provider usage.

Adapter contracts: OpenAI Chat Completions, Anthropic API, Gemini GenerateContent. These vendor documents define their current APIs; compatibility fixtures do not constitute live qualification of every account, model or cloud-hosted variant.

3. Connect a tool or application

Choose one read-only operation in a non-production service first. For HTTP, provide an OpenAPI descriptor with stable operationId, explicit input/output schemas, a correct servers URL and method/path definitions. Declare x-aos-side-effect where needed; read-only GET operations are classified differently from externally effectful writes. Review every advertised operation before approval. Prefer a dedicated scoped facade over registering an entire broad vendor API.

Save capability-connection.json, replacing the service URL and runtime ID with actual configured values:

{
  "endpoint": "https://tools.example.com/openapi.json",
  "protocol": "http",
  "name": "capacity-observations",
  "credential_ref": "file:///run/secrets/tool-token",
  "credential_header": "Authorization",
  "credential_prefix": "Bearer",
  "runtime_id": "engineering-connectors",
  "visibility": "tenant",
  "gateway_only": true,
  "description": "Read permitted capacity observations"
}

aos product --output connection-result.json capability connect --file capability-connection.json
aos product capability list

Add runtime_node_id if only one enrolled node may execute it. The runtime identity must be enrolled and capable of executing connector work. protocol: "mcp" uses MCP discovery; protocol: "a2a" uses the Agent Card. API-key services can use their required header and an empty prefix. Authentication style and security attributes are declarations to review, not certifications supplied by AOS.

UI equivalent: Capabilities → Connect URL. Enter the endpoint, protocol, visibility, runtime, secret reference and authentication options. Inspect the returned manifest, readiness findings, operation schemas, destination and activation state. A connected endpoint is not yet permission to invoke an unapproved contract.

If discovery cannot read a private endpoint, inspect it from the enrolled runtime using aos-runtime capability-connect ENDPOINT --protocol http. Its runtime identity and secrets must be configured first. Use --help for workspace visibility and AWS options. Do not open private networks broadly to make discovery succeed.

4. Review, approve, invoke and revoke

Contract approval and action approval are separate. If the operation requires action approval, the console creates a pending request instead of executing it. A different reviewer approves it under Action Reviews, then the requester chooses Execute approved action. Use aos product action request, decide and execute for the same CLI flow. Follow Action approvals for exact commands and expiry/recovery behavior. Direct invocation remains available for operations whose contract does not require approval.

UI: On the capability row, choose Review & approve. Inspect the exact manifest, Passport findings and activation policy, explicitly confirm and enter a reason. Use Invoke with a declared operation and schema-valid JSON. The result dialog shows the receipt and outcome, including unknown outcomes. Revoke requires confirmation and blocks future requests; existing effects are not undone.

CLI: Replace CAPABILITY_UUID with the registration ID. Export and read the current review before approval:

aos product --output review.json capability review CAPABILITY_UUID
python -m json.tool review.json
aos product capability approve CAPABILITY_UUID --file review.json --reason 'Reviewed operations, credentials and policy'
aos product capability search observations
aos product capability schema CAPABILITY_UUID --operation YOUR_OPERATION_ID
# input.json must match that operation's input schema.
aos product capability invoke CAPABILITY_UUID --operation YOUR_OPERATION_ID --input input.json
aos product runtime workloads
aos product --output tool-audit.json audit

The review contains operations, side effects, input/output schemas, controls, readiness findings and exact approval digests. An operator approves the reviewed version; changed contracts are rejected. Search returns compact summaries. Retrieve only the selected operation’s schema. Discovery does not grant invocation permission.

Provider changed its contract: recheck, inspect the before/after review, accept that exact update, then separately approve the updated contract:

aos product capability verify CAPABILITY_UUID
aos product --output update-review.json capability review-update CAPABILITY_UUID
python -m json.tool update-review.json
aos product capability accept-update CAPABILITY_UUID --file update-review.json --reason 'Reviewed provider schema change'
aos product --output updated-review.json capability review CAPABILITY_UUID
aos product capability approve CAPABILITY_UUID --file updated-review.json --reason 'Approve revised contract'

The server re-inspects before acceptance. A further change produces a conflict. Acceptance imports the new operations and schemas but leaves invocation blocked until approval. The source descriptor must be reachable under the configured network and credential rules. In the console, use Review update and then Review & approve.

Unknown outcome: investigate before retrying:

aos product runtime workloads --status unknown
aos product execution pending
aos product execution reconcile INTENT_UUID

Use the intent ID from the invocation receipt or pending list. Reconciliation reads evidence; it does not repeat the action. In the console use Reconcile evidence, or Platform → Runtime & Fleets. An unknown outcome or retry_permitted: false needs investigation against provider records. Missing evidence is not proof that nothing happened.

Revoke future use:

aos product capability revoke CAPABILITY_UUID --reason 'Integration access withdrawn'

The tool leaves active discovery, schema access is rejected and new invocation is blocked. Revocation does not undo effects or cancel work already admitted. Tool-contract approval is distinct from the separately reviewed tenant-policy process. Restrict direct credentials and network paths separately so callers cannot bypass AOS.

5. Cloud authentication specifics

AWS: the HTTP connector signs with SigV4 when aws_sigv4_service and aws_sigv4_region are both set, for example execute-api and your API Gateway region. An optional aws_role_arn assumes a role through STS. Use the standard botocore workload credential chain in the components making calls; short-lived base and assumed-role credentials are refreshed. Keep credential_ref absent when SigV4 owns Authorization. IAM still controls which resources/actions are allowed. An OpenAPI facade must return usable JSON contracts; listing an AWS account URL does not create an EC2/S3/Bedrock adapter. See AWS signing.

Azure: obtain a token for the correct API audience using your workload identity and store its current value in a managed secret. Use Authorization: Bearer for a supported HTTP/OpenAPI contract. An api-key-based endpoint needs that header and no prefix. Azure model deployment routes, token refresh and API-version parameters must match the configured adapter; do not assume the public OpenAI URL works for an Azure deployment. See Azure REST authentication.

Google Cloud: use a narrowly scoped service/workload identity to obtain the token required by the target API, then expose the current token through your secret system or adapter. Gemini’s API-key adapter is separate from Vertex AI’s account, location and OAuth requirements. GCP Secret Manager support does not itself implement every Google Cloud operation.

Third-party SaaS: start with its supported remote MCP server or a minimal OpenAPI facade. Scope OAuth permissions to the chosen workspace/resources. Refresh rotating tokens outside generic secret resolution, verify both allow and deny paths, and test revocation before enabling writes. No vendor partnership or universal connector compatibility is claimed.

Acceptance checklist

For a LangGraph application, follow the framework integration guide. It connects one explicit action boundary to AOS; the surrounding workflow and private context stay with the application. A paused workflow must still meet current AOS policy and approval requirements when it resumes.

Before expanding an integration, confirm identity/tenant binding, secret resolution in the correct process, ready runtime, explicitly allowed network destinations, schema validation, reviewed contract, passing policy preflight, allowed and denied invocations, unknown-outcome handling, revocation, redacted logs and independently retained evidence. These are deployment checks; the release’s local tests do not replace them.