# 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-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 in an environment?
      instructions:
      - text: List agents in environment {environment_id} of organization {organization_id}.
        slots:
          environment_id: path.environment_id
          organization_id: path.organization_id
      - text: Show all agents in environment {environment_id}, org {organization_id}, {page_size} per page.
        slots:
          environment_id: path.environment_id
          organization_id: path.organization_id
          page_size: query.page_size
      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 AI agent in a Confluent Flink SQL database?
      - What does an agent spec need, like 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: Define a new agent called {name} on Kafka cluster {kafka_cluster_id} in environment {environment_id}, org {organization_id}.
        slots:
          name: requestBody.name
          kafka_cluster_id: path.kafka_cluster_id
          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/{agent_name}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a Flink SQL agent by name
      effect: read
      questions:
      - What model and prompt is a specific agent configured with?
      - Can I read one agent's definition by its name?
      instructions:
      - text: Get 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: Show the definition of agent {agent_name} on cluster {kafka_cluster_id} (env {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
      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's prompt or model
      effect: write
      questions:
      - Can I change an agent's prompt, model or description after it is created?
      - Which agent fields are mutable?
      instructions:
      - text: Alter agent {agent_name} in database {kafka_cluster_id}, env {environment_id}, org {organization_id} to use 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} on cluster {kafka_cluster_id}, env {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
      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 I no longer need from a Flink database?
      - Can agents be deleted by name?
      instructions:
      - text: Delete agent {agent_name} from database {kafka_cluster_id}, env {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 the agent named {agent_name} on cluster {kafka_cluster_id} in env {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
      method: generated
      generated: '2026-09-26'