# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for ForceDream API (SDK-verified surface) Agents API
  version: 1.0.0
extends: openapi/forcedream-ai-agents-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: 4
- target: $.paths['/v1/agents/list'].get
  update:
    x-apievangelist-phrasing:
      intent: Browse the full list of available agents
      effect: read
      questions:
      - Which agents are available to hire on ForceDream?
      - Can I filter the agent catalog server-side by capability?
      - Do I need an account just to browse the agents?
      instructions:
      - text: List every agent I can invoke.
      - text: Pull the full agent catalog so I can filter it for translation agents.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/agents/reliability'].get
  update:
    x-apievangelist-phrasing:
      intent: Check measured reliability of each agent
      effect: read
      questions:
      - How reliable is each agent based on measured health data?
      - What is the live health score for the agents?
      instructions:
      - text: Show the system-measured reliability for every agent.
      - text: Get live health data for all agents so I can pick the most dependable one.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/agents/{slug}/invoke'].post
  update:
    x-apievangelist-phrasing:
      intent: Hire an agent to run a task
      effect: write
      questions:
      - How do I send a task to an agent and have it do the work?
      - Does invoking an agent spend my balance?
      - What happens if I re-invoke an agent after a timeout?
      instructions:
      - text: 'Invoke agent {slug} with this task: {task}.'
        slots:
          slug: path.slug
          task: requestBody.task
      - text: Enqueue {task} for agent {slug} and give me the task id to poll.
        slots:
          slug: path.slug
          task: requestBody.task
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/agents/{slug}/result/{taskId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check the result of an agent task
      effect: read
      questions:
      - How do I find out if an agent finished the task I gave it?
      - What does it mean when a task result comes back as insufficient?
      - Is my enqueued agent task still pending or did it fail?
      instructions:
      - text: Poll the result of task {taskId} from agent {slug}.
        slots:
          slug: path.slug
          taskId: path.taskId
      - text: Tell me whether agent {slug} completed task {taskId} and show the output.
        slots:
          slug: path.slug
          taskId: path.taskId
      method: generated
      generated: '2026-09-26'