AI assistant and reference behavior

The Envoy assistant combines product documentation, deployment-specific AI references, current conversation context, and approved API tools. It can explain resources, inspect accessible state, draft YAML, validate definitions, and perform supported operations subject to user permission and confirmation.

Context sources

The assistant may receive:

• product and authoring guidance;
• selected AI references matched by topic and keywords;
• conversation history;
• current application context;
• results returned by approved Envoy API tools.

Live API results take precedence over stale prose.

AI references

Reference records contain:

• unique slug;
• title;
• retrieval keywords;
• Markdown content;
• enabled state.

References are retrieved by relevance; they are not automatically inserted in full into every message. Keep one topic per reference and include terms users are likely to use.

See Manage AI references.

Tool permissions

Assistant tools use the authenticated user's product access. The assistant cannot use a reference to bypass:

• role-based permissions;
• unavailable connector types;
• server feature switches;
• connector credentials;
• confirmation requirements.

A failed authorization should be handled as a permission boundary, not as a prompt to work around the API.

Read and write behavior

Read operations can inspect accessible resources and validation results. Write operations should be:

• explicit about the target and effect;
• bounded in scope;
• confirmed when destructive or externally visible;
• followed by a result summary.

The assistant may draft YAML without saving it. Review generated expressions, connector methods, destination identity, and idempotency before a production run.

Conversation management

Long conversations can be compacted into a summary so work can continue within model context limits. Important identifiers and decisions should still be verified against current product state before an operation.

Prompt caching can reduce repeated context processing but does not change permissions or make an old response authoritative.

Data handling

Do not send or store:

• passwords, API tokens, client secrets, or private keys;
• full sensitive source records;
• unnecessary personal data;
• unrestricted database exports;
• incident data beyond the approved support scope.

Prefer run IDs, resource IDs, schemas, sanitized samples, and narrow log excerpts.

Expected limitations

The assistant can misunderstand an ambiguous request, use stale reference guidance, or generate a syntactically valid expression with incorrect business semantics. Validate:

1. target environment and resource;
2. read versus write intent;
3. connector and account identity;
4. record scope;
5. expected output;
6. rollback or reconciliation plan.

AI assistance does not replace deployment access controls, backups, change review, or destination-side uniqueness constraints.