7 Deploying and Configuring the Billing Care AI Agent

Learn how to deploy, configure, and use the Billing Care AI Agent using OCI hosted deployment or Kubernetes, with Oracle Cloud Infrastructure (OCI) Generative AI.

Topics in this document:

Deploying the Billing Care AI Agent

You can deploy the Billing Care AI Agent in either of the following ways:

  • Deploying in a Kubernetes Environment

  • Deploying using OCI Generative AI hosted deployment

Deploying the Billing Care AI Agent in Kubernetes

To deploy the Billing Care AI Agent in Kubernetes:

  1. In your values.yaml file, set the following keys:

    • enabled: Set to true for a standard deployment.

    • imageRepository: Specify the container registry and repository prefix, such as <registry>/<repository>. This value is combined with billingcareAgent.container.image.

    • imagePullSecrets: Specify the name of an existing Kubernetes secret containing credentials for accessing your private container registry. Leave empty if a secret is not required.

    • imagePullPolicy: Specify IfNotPresent for an immutable release tag or Always when validating a mutable tag.

    • billingcareAgent.container.image: Specify the agent image name and immutable release tag, in this format - communications/ai/agents/:<release-tag>.

  2. Set the following keys under billingcareAgent.env:

    • BILLING_CARE_MCP_URL: Specify the Billing Care MCP streamable HTTP endpoint. Use HTTPS. If the runtime does not trust the server certificate chain, configure mcpTls as described in the MCP certificate configuration step.

    • OCI_GENAI_MODEL_ID: Specify the OCI Generative AI model identifier.

    • OCI_GENAI_SERVICE_ENDPOINT: Specify the OCI Generative AI inference endpoint for the region.

    • OCI_COMPARTMENT_ID: Specify the OCI compartment OCID authorized to use the model.

    • OCI_AUTH_TYPE: Specify RESOURCE_PRINCIPAL for resource principal authentication or API_KEY for API key authentication. For API key authentication, configure the secret mount under ociConfig as described in the OCI authentication step.

    • OCI_AUTH_PROFILE: Optionally, specify the OCI configuration profile to use for API key authentication.

    • OCI_AUTH_FILE_LOCATION: Normally, leave empty. When ociConfig.enabled is true, the chart sets this value to the mounted OCI configuration file path.

    • BILLING_MCP_HTTP_TIMEOUT_SECONDS: Specify the MCP request timeout, in seconds. The default is 30.

    • MCP_MAX_RETRIES: Specify the maximum number of retry attempts for eligible MCP operations. The default is 2.

    • SESSION_MEMORY_DIR: Specify an absolute writable path for mounted session storage. Set to none to retain session context in process memory only.

    • SESSION_MEMORY_TTL_MINUTES: Specify the idle-session retention period, in minutes. The default is 60.

    • SESSION_MEMORY_MAX_MESSAGES: Specify the maximum number of optimized messages retained per session. The default is 100.

    • SESSION_MEMORY_VERBATIM_TURNS: Specify the number of recent conversation turns retained verbatim before older history is compacted. The default is 5.

    • SESSION_ACCOUNT_HISTORY_LIMIT: Specify the maximum number of accounts retained in a session. Set to 0 to retain all account references for that session.

    • BILL_LOOKUP_MAX_COUNT: Specify the maximum number of bill records considered for a lookup. The default is 50.

    • MAX_FOLLOW_UP_QUESTIONS: Specify the maximum number of follow-up questions generated for an agent response. The default is 3.

    • LOG_DIR: Specify the log directory in the container. This value must match billingcareAgent.logs.mountPath.

    • LOG_FILE: Specify the log filename.

    • LOG_CONFIG_FILE: Optionally, specify the path to the YAML logging configuration file in the container. Configure the logging file mount as described in the logging configuration step.

    Do not include tokens, passwords, private keys, or other secrets under billingcareAgent.env.

  3. Configure OCI authentication by doing one of the following:

    • For resource-principal authentication, set billingcareAgent.env.OCI_AUTH_TYPE to RESOURCE_PRINCIPAL and leave ociConfig.enabled set to false.

    • For API-key authentication, set billingcareAgent.env.OCI_AUTH_TYPE to API_KEY and ociConfig.enabled to true. Set ociConfig.secretName to the name of an existing secret containing the OCI configuration and credential material. Set ociConfig.configFile and ociConfig.mountPath to the configuration filename and mount directory.

  4. Configure session storage by setting the following keys:

    • billingcareAgent.env.SESSION_MEMORY_DIR: Specify an absolute writable path for mounted session storage. Set to none to retain session context in process memory only.

    • persistence.enabled: Set to true to retain session memory across pod restarts.

    • persistence.storageClassName: Specify an existing StorageClass, or leave empty to use the cluster default.

    • persistence.accessMode: Specify the volume access mode.

    • persistence.size: Specify the storage size.

    • billingcareAgent.env.SESSION_MEMORY_TTL_MINUTES: Specify the idle-session retention period, in minutes.

    • billingcareAgent.env.SESSION_MEMORY_MAX_MESSAGES: Specify the maximum number of messages retained per session.

    If the chart must create a StorageClass for session memory, configure the following keys:

    • storageClass.enabled: Set to true to create a StorageClass. The default is false.

    • storageClass.name: Specify the StorageClass name. Leave empty to use <fullname>-session-memory.

    • storageClass.provisioner: Specify the installed CSI provisioner. The default is blockvolume.csi.oraclecloud.com.

    • storageClass.reclaimPolicy: Specify Retain to preserve the backing volume after PVC deletion or Delete to remove it. The default is Retain.

    • storageClass.volumeBindingMode: Specify Immediate or WaitForFirstConsumer. The default is WaitForFirstConsumer, which defers provisioning until pod scheduling.

    • storageClass.allowVolumeExpansion: Set to true to allow volume expansion when supported by the CSI driver. The default is true.

    • storageClass.annotations: Specify annotations for the StorageClass, if required. The default is {}.

    • storageClass.parameters: Specify provisioning parameters supported by the selected provisioner. The default is attachment-type: paravirtualized.

    The chart creates the StorageClass only when storageClass.enabled and persistence.enabled are both true and persistence.storageClassName is empty. The Helm service account must have permission to create StorageClass resources.

    For multiple replicas, use persistent or external session storage, or session-aware routing. Process-local session memory alone is not sufficient.

  5. Configure HTTPS access by doing one of the following:

    • For NGINX Ingress, set nginx.enabled to true. Set nginx.ingressClassName to the ingress class, nginx.host to the agent hostname, and nginx.tlsSecretName to the name of an existing TLS secret.

    • (Recommended) For HTTPS termination directly in the agent, set nginx.enabled to false and configure the following keys:

      • https.enabled: Set to true.

      • https.source: Specify chartFiles or hostPath. The default is chartFiles.

      • https.mountPath: Specify the read-only certificate directory in the container.

      • https.certFile: Specify the certificate-chain filename under the mount directory.

      • https.keyFile: Specify the private-key filename under the mount directory.

      • https.containerPort: Specify the HTTPS listener port in the container.

      • https.servicePort: Specify the HTTPS port exposed by the Kubernetes Service.

      • https.hostPath.path: For hostPath, specify the absolute node directory containing the certificate and private key.

      • https.hostPath.type: For hostPath, specify Directory.

      • https.chartFiles.certPath: For chartFiles, specify the chart-relative certificate-chain path in the helm/billingcare-agent/files/certs/ directory.

      • https.chartFiles.keyPath: For chartFiles, specify the chart-relative private-key path in the helm/billingcare-agent/files/certs/ directory.

    For direct HTTPS, the certificate must include the agent hostname in its subject alternative name. If you use hostPath, the certificate files must exist on every node on which the pod can run and must be readable by UID/GID 10001.

  6. If the HTTPS MCP endpoint uses a certificate authority that the runtime does not trust, configure the following keys:

    • mcpTls.enabled: Set to true to mount a CA bundle for outbound MCP certificate validation. The default is false.

    • mcpTls.source: Specify chartFiles or hostPath. The default is chartFiles.

    • mcpTls.mountPath: Specify the read-only CA directory in the container.

    • mcpTls.caFile: Specify the CA-bundle filename under the mount directory.

    • mcpTls.hostPath.path: For hostPath, specify the absolute node directory containing the CA bundle.

    • mcpTls.hostPath.type: For hostPath, specify Directory.

    • mcpTls.chartFiles.caPath: For chartFiles, specify the chart-relative CA-bundle path in the helm/billingcare-agent/files/certs/mcp directory.

    Do not disable certificate validation. The inbound agent certificate and outbound MCP CA bundle are configured separately.

  7. Configure MCP authentication:

    • For caller-token forwarding, leave mcpOAuth.enabled set to false.

    • For an approved service-to-service token configuration, set mcpOAuth.enabled to true. Set mcpOAuth.secretName to the name of an existing secret and mcpOAuth.secretKey to the key containing the raw token without the Bearer prefix.

  8. If the agent validates incoming bearer tokens, set billingcareAgent.idcs.enabled to true and configure the following keys under billingcareAgent.idcs:

    • identityURI: Specify the identity-provider URI.

    • issuer: Specify the token issuer.

    • audience: Specify the token audience.

    • jwksURI: Specify the signing-key URI.

  9. Configure the workload settings:

    • Set the CPU and memory requests and limits under billingcareAgent.container.resources.

    • Set the service type and port under billingcareAgent.service.

    • Configure autoscaling under billingcareAgent.hpa. If autoscaling is disabled, set the replica count by using billingcareAgent.replicas.

  10. Configure logging under billingcareAgent.logs. Ensure that billingcareAgent.env.LOG_DIR matches billingcareAgent.logs.mountPath and that the log directory is writable by UID/GID 10001.

    To use persistent log storage, set billingcareAgent.logs.enabled to true, set billingcareAgent.logs.hostPath.enabled to false, and configure the following keys:

    • logPersistence.enabled: Set to true to create a log PVC. The default is false.
    • logPersistence.accessMode: Specify the volume access mode supported by the storage provider. The default is ReadWriteOnce.
    • logPersistence.size: Specify the storage size. The default is 1Gi.
    • logPersistence.annotations: Specify annotations for the log PVC, if required. The default is {}.

    The log PVC uses the cluster default StorageClass. No separate StorageClass setting is available for logs. When billingcareAgent.logs.hostPath.enabled is true, node-local storage takes precedence over logPersistence. When log storage is enabled and both billingcareAgent.logs.hostPath.enabled and logPersistence.enabled are false, the chart uses ephemeral emptyDir storage.

    Note:

    Do not include passwords, OCI private keys, OAuth tokens, or certificates directly in the values file. Use the applicable Secret configuration.

  11. Validate the Helm chart by running this command:

    helm lint helm/billingcare-agent

  12. Generate the Kubernetes resource definitions by using helm template with values.yaml. Review the generated deployment, service, Ingress, persistent volume claim, certificate mounts, and environment variables.

  13. Deploy the Helm chart with values.yaml.

Perform checks to ensure that everything is correct leading to a successful deployment:

  • Confirm that the pod starts and that /health returns an OK status.

  • Confirm that /ready returns a ready status and that the MCP URL is configured.

  • Submit a simple bill request to /invoke/chat with a valid authorized token.

  • Verify that session storage, logging, and MCP certificate validation work as configured.

  • Confirm that logs do not contain tokens, credentials, full invoices, payment details, or unnecessary personally identifiable information.

Deploying the Billing Care AI Agent by Using OCI Generative AI Hosted Deployment

To deploy the Billing Care AI Agent by using OCI Generative AI Hosted Deployment:

  1. In the OCI Console, open Generative AI and create a hosted application. Specify the application name, description, and compartment.

  2. Configure the minimum and maximum replica counts, scaling metric, and CPU threshold.

    For multiple replicas, configure session storage or routing so that sessions do not depend on process-local memory.

  3. Enable managed storage only if the agent requires the available PostgreSQL, cache, or Autonomous Database services.

  4. Add the required application environment variables, including:

    • BILLING_CARE_MCP_URL: Specify the Billing Care MCP streamable HTTP endpoint.

    • OCI_GENAI_MODEL_ID: Specify the OCI Generative AI model identifier.

    • OCI_GENAI_SERVICE_ENDPOINT: Specify the OCI Generative AI inference endpoint.

    • OCI_COMPARTMENT_ID: Specify the OCI compartment OCID.

    • OCI_AUTH_TYPE: Specify RESOURCE_PRINCIPAL when using resource principal authentication.

    • IDCS_ENABLED: Set to true when the agent validates incoming bearer tokens. Set to false when the hosted deployment platform performs inbound OAuth validation.

    • IDCS_ISSUER: Specify the expected token issuer when agent-level token validation is enabled.

    • IDCS_AUDIENCE: Specify the expected token audience when agent-level token validation is enabled.

    • IDCS_JWKS_URI: Specify the identity provider’s JSON Web Key Set (JWKS) URI used to validate token signatures.

    • PRINT_LOGS: Set to true to enable log output.

    • MCP_TLS_CA_CERT_BASE64: If the Billing Care MCP endpoint uses a certificate authority that the runtime does not trust, supply the base64-encoded CA certificate through a Vault environment variable.

    • NO_PROXY: If your environment uses a proxy, specify the hosts or domains that the agent must access directly.

    Configure the session-memory, logging, and identity settings for the environment. Use Vault environment variables for secrets. Do not enter credentials, bearer tokens, private keys, or CA material as plain-text environment variables.

  5. Configure network access:

    • For a private enterprise integration, select Custom (user-managed) networking and specify the VCN, subnet, and network security group.

    • Ensure that DNS, route tables, and network security rules allow outbound HTTPS access to OCI Generative AI and the Billing Care MCP server.

    • Select a private endpoint when the application must be reachable only within the VCN. Select a public endpoint only when external access and the required security controls have been approved.

  6. Configure application authentication for the environment.

    The available options include identity-domain bearer-token authentication, OCI IAM request-signature authentication, and no application-layer authentication.

  7. Enable resource logging and select the log group and log category.

  8. After creating the application, open the configuration tab and verify the environment variables.

  9. Open the Deployment tab, review the autoscaling settings, and select Create deployment. Select the Billing Care AI Agent image and an immutable release tag from the approved container repository.

  10. Create the deployment and monitor its work request until it succeeds.

  11. Confirm that the deployment is active and that the application logs show a successful web-server startup.

Perform checks to ensure that everything is correct leading to a successful deployment:

  • Call /health and /ready through the application endpoint.

  • Submit a simple bill request to /invoke/chat with a valid authorized token. Confirm that the agent can reach OCI Generative AI and the Billing Care MCP endpoint.

  • Verify session behavior and error handling.

  • Confirm that logs do not contain sensitive information.

Record the deployed image tag or digest, application name, endpoint type, and environment-specific change record.

Using the Billing Care AI Agent

To use the Billing Care AI Agent:

  1. Send a request to the agent health endpoint:

    curl https://<agent-host>/health

    where <agent-host> is the hostname of the Billing Care AI Agent.

    Confirm that the endpoint returns an OK status.

  2. Send a request to the readiness endpoint:

    curl https://<agent-host>/ready

    Confirm that the endpoint returns a ready status.

  3. Log in to Billing Care using an account that has access to the AI agent.

    Note:

    For the AI Agent in Billing Care, the chat UI is disabled by default. So, ensure that the chat UI is enabled along with the other required tools and resources.

  4. Open a customer account that contains a bill.

  5. Open the AI Agent chat and enter a bill inquiry. For example:

    Explain the charges on my latest bill.

    The agent retrieves the bill information and displays a response.