# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Confluent Cloud Agents (sql/v1) API
  version: 1.0.0
extends: openapi/confluent-the-data-streaming-platform-agents-sql-v1-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-26'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 5
- target: $.paths['/sql/v1/organizations/{organization_id}/environments/{environment_id}/agents'].get
  update:
    x-apievangelist-phrasing:
      intent: List Flink SQL agents in an environment
      effect: read
      questions:
      - Which AI agents are defined in my Flink SQL environment?
      - Can I page through all agents across an environment's databases?
      instructions:
      - text: List all agents in environment {environment_id} of org {organization_id}.
        slots:
          environment_id: path.environment_id
          organization_id: path.organization_id
      - text: Show the next {page_size} agents in environment {environment_id} for org {organization_id}.
        slots:
          page_size: query.page_size
          environment_id: path.environment_id
          organization_id: path.organization_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/sql/v1/organizations/{organization_id}/environments/{environment_id}/databases/{kafka_cluster_id}/agents'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a Flink SQL agent
      effect: write
      questions:
      - How do I create an agent in a Flink SQL database backed by a Kafka cluster?
      - What spec does a new Flink SQL agent need, like its model and prompt?
      instructions:
      - text: Create agent {name} in database {kafka_cluster_id}, environment {environment_id}, org {organization_id} with spec {spec}.
        slots:
          name: requestBody.name
          kafka_cluster_id: path.kafka_cluster_id
          environment_id: path.environment_id
          organization_id: path.organization_id
          spec: requestBody.spec
      - text: Set up a new agent {name} on Kafka cluster {kafka_cluster_id}.
        slots:
          name: requestBody.name
          kafka_cluster_id: path.kafka_cluster_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/sql/v1/organizations/{organization_id}/environments/{environment_id}/databases/{kafka_cluster_id}/agents/{agent_name}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a Flink SQL agent
      effect: read
      questions:
      - What model and prompt is a specific Flink SQL agent using?
      - Can I read one agent's definition by name?
      instructions:
      - text: Show agent {agent_name} in database {kafka_cluster_id}, environment {environment_id}, org {organization_id}.
        slots:
          agent_name: path.agent_name
          kafka_cluster_id: path.kafka_cluster_id
          environment_id: path.environment_id
          organization_id: path.organization_id
      - text: Read the definition of agent {agent_name}.
        slots:
          agent_name: path.agent_name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/sql/v1/organizations/{organization_id}/environments/{environment_id}/databases/{kafka_cluster_id}/agents/{agent_name}'].put
  update:
    x-apievangelist-phrasing:
      intent: Alter a Flink SQL agent
      effect: write
      questions:
      - Can I change an existing agent's model or prompt?
      - Which agent fields can be altered after creation?
      instructions:
      - text: Alter agent {agent_name} in database {kafka_cluster_id}, environment {environment_id}, org {organization_id} with spec {spec}.
        slots:
          agent_name: path.agent_name
          kafka_cluster_id: path.kafka_cluster_id
          environment_id: path.environment_id
          organization_id: path.organization_id
          spec: requestBody.spec
      - text: Update the prompt and model of agent {agent_name} using spec {spec}.
        slots:
          agent_name: path.agent_name
          spec: requestBody.spec
      method: generated
      generated: '2026-09-26'
- target: $.paths['/sql/v1/organizations/{organization_id}/environments/{environment_id}/databases/{kafka_cluster_id}/agents/{agent_name}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a Flink SQL agent
      effect: destructive
      questions:
      - How do I remove an agent from a Flink SQL database?
      - Can I delete a specific agent by its name?
      instructions:
      - text: Delete agent {agent_name} from database {kafka_cluster_id}, environment {environment_id}, org {organization_id}.
        slots:
          agent_name: path.agent_name
          kafka_cluster_id: path.kafka_cluster_id
          environment_id: path.environment_id
          organization_id: path.organization_id
      - text: Remove agent {agent_name}.
        slots:
          agent_name: path.agent_name
      method: generated
      generated: '2026-09-26'