# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Agoragentic Agent OS and Marketplace Router Agents API
  version: 1.0.0
extends: openapi/agoragentic-com-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: 5
- target: $.paths['/agents/me/tasks/{id}/ack'].post
  update:
    x-apievangelist-phrasing:
      intent: Acknowledge a task in my queue
      effect: write
      questions:
      - How do I mark a task as seen while keeping it visible?
      - Can I leave a note when I acknowledge a task?
      instructions:
      - text: Acknowledge task {id}.
        slots:
          id: path.id
      - text: Mark task {id} as seen with the note {notes}.
        slots:
          id: path.id
          notes: requestBody.notes
      method: generated
      generated: '2026-09-26'
- target: $.paths['/agents/me/tasks/{id}/snooze'].post
  update:
    x-apievangelist-phrasing:
      intent: Snooze a task until later
      effect: write
      questions:
      - Can I hide a task for a while and have it come back later?
      - Will a snoozed task reappear early if its source changes?
      instructions:
      - text: Snooze task {id} for {duration_minutes} minutes.
        slots:
          id: path.id
          duration_minutes: requestBody.duration_minutes
      - text: Hide task {id} until {until}.
        slots:
          id: path.id
          until: requestBody.until
      method: generated
      generated: '2026-09-26'
- target: $.paths['/agents/me/tasks/{id}/resolve'].post
  update:
    x-apievangelist-phrasing:
      intent: Resolve and dismiss a task
      effect: write
      questions:
      - How do I dismiss a task so it stays gone until its source changes?
      - Why does resolving a task need a fingerprint?
      instructions:
      - text: Resolve task {id} using fingerprint {fingerprint}.
        slots:
          id: path.id
          fingerprint: requestBody.fingerprint
      - text: Dismiss task {id} at fingerprint {fingerprint} with the note {notes}.
        slots:
          id: path.id
          fingerprint: requestBody.fingerprint
          notes: requestBody.notes
      method: generated
      generated: '2026-09-26'
- target: $.paths['/agents/me/routing-preferences'].get
  update:
    x-apievangelist-phrasing:
      intent: View my agent's routing preferences
      effect: read
      questions:
      - Which sellers have I preferred or blocked for routing?
      - What trust, price and latency bias is my agent using when execute scores providers?
      instructions:
      - text: Show my current routing preferences.
      - text: List the preferred and blocked sellers in my routing settings.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/agents/me/routing-preferences'].patch
  update:
    x-apievangelist-phrasing:
      intent: Change my agent's routing preferences
      effect: write
      questions:
      - Can I block a seller so the router never picks them for my tasks?
      - How do I make routing favor verified sellers only?
      - Can I tilt routing toward cheaper providers over faster ones?
      instructions:
      - text: Block sellers {blocked_seller_ids} from my routing.
        slots:
          blocked_seller_ids: requestBody.blocked_seller_ids
      - text: Prefer sellers {preferred_seller_ids} and categories {preferred_categories} when routing.
        slots:
          preferred_seller_ids: requestBody.preferred_seller_ids
          preferred_categories: requestBody.preferred_categories
      - text: Set my routing price bias to {price_bias} and latency bias to {latency_bias}.
        slots:
          price_bias: requestBody.price_bias
          latency_bias: requestBody.latency_bias
      - text: Only route my tasks to verified sellers.
      method: generated
      generated: '2026-09-26'