oci-service-operator

Generative AI Agent Onboarding Audit

This audit is the US-105 baseline for onboarding github.com/oracle/oci-go-sdk/v65/generativeaiagent before services.yaml publishes the service.

go.mod remains pinned to github.com/oracle/oci-go-sdk/v65 v65.110.0.
v65.110.0 already contains the generativeaiagent package in the module cache; the repo lacked vendor/github.com/oracle/oci-go-sdk/v65/generativeaiagent only because nothing imported that package yet.
pkg/sdkimports/rollout_services.go now blank-imports github.com/oracle/oci-go-sdk/v65/generativeaiagent so go mod vendor keeps the package in the branch-local inputs.

Full CRUD family is present: CreateKnowledgeBase, GetKnowledgeBase, ListKnowledgeBases, UpdateKnowledgeBase, and DeleteKnowledgeBase.
Additional mutator is present: ChangeKnowledgeBaseCompartment.
GetKnowledgeBaseResponse returns KnowledgeBase.
ListKnowledgeBasesResponse returns KnowledgeBaseCollection.
ListKnowledgeBasesRequest exposes compartmentId, lifecycleState, and displayName, plus page and sort controls.
Lifecycle states are CREATING, UPDATING, ACTIVE, INACTIVE, DELETING, DELETED, and FAILED.
CreateKnowledgeBaseResponse returns the resource body and OpcWorkRequestId.
UpdateKnowledgeBaseResponse and DeleteKnowledgeBaseResponse expose OpcWorkRequestId; update and delete do not return a KnowledgeBase body.
The package also exposes service-local GetWorkRequest, ListWorkRequests, ListWorkRequestErrors, and ListWorkRequestLogs helpers.

Additional full CRUD families are Agent, AgentEndpoint, DataSource, ProvisionedCapacity, and Tool.
DataIngestionJob is create/get/list/delete only and ships with GetDataIngestionJobLogContent as an additional support surface.
All of those non-KnowledgeBase families should stay unpublished initially.

KnowledgeBase is the requested initial kind and it looks viable as the first published resource in the package.
Recommended formalSpec is knowledgebase.
Recommended async classification is workrequest with workRequest.source=service-sdk and phases create, update, and delete.
KnowledgeBase looks viable as a direct controller-backed generated rollout because GET/list expose lifecycle state and the service ships the work-request helpers needed for mutation follow-up.
The required risk callout is explicit here: generativeaiagent/KnowledgeBase must remain clearly distinct from the existing adm/KnowledgeBase rollout. US-115 must keep service-qualified formal rows, docs, catalog entries, and generated package metadata disambiguated so the new group does not overwrite or confuse the existing ADM surface.

Agent is now the second published controller-backed kind in the generativeaiagent package; the remaining AgentEndpoint, DataSource, DataIngestionJob, ProvisionedCapacity, Tool, and work-request helper families remain unpublished.
Agent uses the same recommended formalSpec/async posture as KnowledgeBase: repo-authored formal row plus async.strategy=workrequest with workRequest.source=service-sdk and create, update, and delete phases.
CreateAgent returns an Agent body plus OpcWorkRequestId, while UpdateAgent, DeleteAgent, and ChangeAgentCompartment return work-request headers only. GetAgent and ListAgents project lifecycle directly, so the published runtime uses service-SDK GetWorkRequest follow-up and recovers the created OCID from either the create response body or work-request resources.
The published runtime keeps ChangeAgentCompartment out of scope. The controller-backed contract treats compartmentId as replacement-only drift and confines in-place mutation to displayName, description, welcomeMessage, knowledgeBaseIds, llmConfig, freeformTags, and definedTags.
Agent needs a handwritten create/update body builder even on top of the generated runtime shell because llmConfig.routingLlmCustomization and its nested llmSelection polymorphism need concrete SDK bodies, and the CRD’s zero-value nested structs would otherwise serialize empty objects that the published runtime should omit.

formal/sources.lock pins provider facts to github.com/oracle/terraform-provider-oci@eb653febb1bab4cc6650a96d404a8baf36fdf671.
Matching provider surfaces are oci_generative_ai_agent_knowledge_base as the resource, oci_generative_ai_agent_knowledge_base as the singular data source, and oci_generative_ai_agent_knowledge_bases as the list data source.
The follow-through Agent row uses oci_generative_ai_agent_agent as the resource and singular data source plus oci_generative_ai_agent_agents as the list data source. The checked-in mutability docs fixture is used for that row because the live Terraform Registry resource page currently renders as a JavaScript shell instead of a deterministic argument-reference HTML page.
Provider docs publish the same knowledge-base family as both a resource and singular/list data sources, so the main risk is the repo-local naming collision with ADM rather than missing provider coverage.

This site is open source. Improve this page.