API Evangelist conversational phrasing for External Agents API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for External Agents API
  version: 1.0.0
extends: openapi/profound-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: 10
- target: $.paths['/v1/agents'].get
  update:
    x-apievangelist-phrasing:
      intent: List the organization's agents
      effect: read
      questions:
      - Which agents does my organization have in Profound?
      - Can I see only the agents that have never been published?
      - What's the difference between a draft agent and a published one in my agent list?
      instructions:
      - text: List all of my organization's agents.
      - text: Show me only agents with status {statuses}.
        slots:
          statuses: query.statuses
      - text: List the next {limit} agents after cursor {next_cursor}.
        slots:
          limit: query.limit
          next_cursor: query.next_cursor
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/agents'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a new draft agent
      effect: write
      questions:
      - How do I build a new agent from scratch for my organization?
      - Is a newly created agent live right away or does it start as a draft?
      instructions:
      - text: Create a draft agent called {name} in organization {organization_id}.
        slots:
          name: requestBody.name
          organization_id: requestBody.organization_id
      - text: Create agent {name} in org {organization_id} described as {description} with workflow graph {graph}.
        slots:
          name: requestBody.name
          organization_id: requestBody.organization_id
          description: requestBody.description
          graph: requestBody.graph
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/agents/{agent_id}/publish'].post
  update:
    x-apievangelist-phrasing:
      intent: Publish an agent's draft as live
      effect: write
      questions:
      - How do I take my agent's draft live?
      - Why would publishing an agent fail with a 422 validation error?
      instructions:
      - text: Publish the latest draft of agent {agent_id}.
        slots:
          agent_id: path.agent_id
      - text: Promote agent {agent_id}'s draft graph to a new published version.
        slots:
          agent_id: path.agent_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/agents/node-types'].get
  update:
    x-apievangelist-phrasing:
      intent: List node types for building agents
      effect: read
      questions:
      - What building blocks can I use when designing an agent workflow?
      - Which node types are available for agent graphs, and can I cache that list?
      instructions:
      - text: List every node type I can use in an agent graph.
      - text: Show the catalog of available agent node types.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/agents/node-types/{node_type}/schema'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the config schema for a node type
      effect: read
      questions:
      - What configuration fields does a particular agent node type accept?
      - How can I tell when a node type's JSON schema has changed?
      instructions:
      - text: Get the configuration JSON schema for node type {node_type}.
        slots:
          node_type: path.node_type
      - text: Fetch the schema and schema_version for the {node_type} node.
        slots:
          node_type: path.node_type
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/agents/{agent_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an agent's details
      effect: read
      questions:
      - Can I look up one agent's details and status?
      - Is it possible to view an agent's unpublished draft instead of its live version?
      instructions:
      - text: Show me agent {agent_id}.
        slots:
          agent_id: path.agent_id
      - text: Get the {version} version of agent {agent_id} with its schema details.
        slots:
          agent_id: path.agent_id
          version: query.version
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/agents/{agent_id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Replace an agent's draft graph
      effect: write
      questions:
      - How do I fix my agent's workflow without creating a new agent?
      - Does updating an agent re-validate the draft before I publish it?
      instructions:
      - text: Replace the draft graph of agent {agent_id} with {graph}.
        slots:
          agent_id: path.agent_id
          graph: requestBody.graph
      - text: Save this revised workflow {graph} as agent {agent_id}'s draft and tell me if it validates.
        slots:
          agent_id: path.agent_id
          graph: requestBody.graph
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/agents/{agent_id}/graph'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an agent's workflow graph
      effect: read
      questions:
      - Can I export an agent's nodes and edges so I can copy it?
      - Who can see an agent's draft graph versus its published graph?
      instructions:
      - text: Export the nodes and edges of agent {agent_id}.
        slots:
          agent_id: path.agent_id
      - text: Get the {version} workflow graph for agent {agent_id} so I can edit a copy.
        slots:
          agent_id: path.agent_id
          version: query.version
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/agents/{agent_id}/runs'].post
  update:
    x-apievangelist-phrasing:
      intent: Start a run of a published agent
      effect: write
      questions:
      - How do I execute one of my agents?
      - Can I run an agent that has only a draft and was never published?
      instructions:
      - text: Run agent {agent_id} now.
        slots:
          agent_id: path.agent_id
      - text: Kick off a new execution of agent {agent_id}'s live version.
        slots:
          agent_id: path.agent_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/agents/{agent_id}/runs/{run_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check an agent run's status and result
      effect: read
      questions:
      - Has my agent run finished, and what did it return?
      - Can I get verbose detail on an individual agent run?
      instructions:
      - text: Check the status of run {run_id} for agent {agent_id}.
        slots:
          agent_id: path.agent_id
          run_id: path.run_id
      - text: Get verbose={verbose} results for run {run_id} of agent {agent_id}.
        slots:
          agent_id: path.agent_id
          run_id: path.run_id
          verbose: query.verbose
      method: generated
      generated: '2026-10-01'