# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Testflinger Agents API
  version: 1.0.0
extends: openapi/canonical-agents-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-01'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 8
- target: $.paths['/v1/agents/data'].get
  update:
    x-apievangelist-phrasing:
      intent: List data for all test agents
      effect: read
      questions:
      - Which Testflinger agents are registered and what state is each one in?
      - Can I see the queues and location of every agent at once?
      instructions:
      - text: List the data for every agent.
      - text: Show me the current state of all agents on the server.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/agents/queues'].get
  update:
    x-apievangelist-phrasing:
      intent: List advertised queues
      effect: read
      questions:
      - Which queues does this server advertise as valid to submit to?
      - What is each advertised queue described as?
      instructions:
      - text: List all advertised queues with their descriptions.
      - text: Show me which queue names the server knows about.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/agents/queues'].post
  update:
    x-apievangelist-phrasing:
      intent: Advertise the queues an agent services
      effect: write
      questions:
      - How does an agent tell the server which queues it listens on?
      - Can I publish a description alongside each queue name I advertise?
      instructions:
      - text: Advertise these queue names and descriptions to the server.
      - text: Register the queues this agent services so users can see they are valid.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/agents/images'].post
  update:
    x-apievangelist-phrasing:
      intent: Publish known images for a queue
      effect: write
      questions:
      - How do I record which provisioning images are available on a queue?
      - Can an agent map image names like core22 to provision data for its queue?
      instructions:
      - text: Publish this image-name to provision-data mapping for the queue.
      - text: Tell the server about the images known on my queue.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/agents/images/{queue}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get known images for a queue
      effect: read
      questions:
      - Which images can I provision on a particular queue?
      - What provision data is stored for each image on a queue?
      instructions:
      - text: List the known images for queue {queue}.
        slots:
          queue: path.queue
      - text: Show the provision data for images on queue {queue}.
        slots:
          queue: path.queue
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/agents/data/{agent_name}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one agent's information
      effect: read
      questions:
      - What state is a specific agent in right now?
      - Which job is a named agent currently running?
      instructions:
      - text: Show the information for agent {agent_name}.
        slots:
          agent_name: path.agent_name
      - text: Get the current state and queues of agent {agent_name}.
        slots:
          agent_name: path.agent_name
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/agents/data/{agent_name}'].post
  update:
    x-apievangelist-phrasing:
      intent: Update an agent's reported status
      effect: write
      questions:
      - How does an agent report its state and location back to the server?
      - Can an agent post the job it is working on and a comment about its device?
      instructions:
      - text: Set agent {agent_name} state to {state}.
        slots:
          agent_name: path.agent_name
          state: requestBody.state
      - text: Report agent {agent_name} at location {location} listening on queues {queues}.
        slots:
          agent_name: path.agent_name
          location: requestBody.location
          queues: requestBody.queues
      - text: Record that agent {agent_name} is running job {job_id}.
        slots:
          agent_name: path.agent_name
          job_id: requestBody.job_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/agents/provision_logs/{agent_name}'].post
  update:
    x-apievangelist-phrasing:
      intent: Post an agent's provision log
      effect: write
      questions:
      - How do I record whether provisioning succeeded on an agent?
      - Can an agent attach detail to the exit code of a provisioning attempt?
      instructions:
      - text: 'Post a provision log for agent {agent_name}: job {job_id} exited with {exit_code}.'
        slots:
          agent_name: path.agent_name
          job_id: requestBody.job_id
          exit_code: requestBody.exit_code
      - text: Log provisioning result {exit_code} for job {job_id} on agent {agent_name} with detail {detail}.
        slots:
          exit_code: requestBody.exit_code
          job_id: requestBody.job_id
          agent_name: path.agent_name
          detail: requestBody.detail
      method: generated
      generated: '2026-10-01'