API Evangelist conversational phrasing for Anthropic 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 Anthropic Agents API
  version: 1.0.0
extends: openapi/anthropic-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: 12
- target: $.paths['/v1/agents/{agent_id}/archive?beta=true'].post
  update:
    x-apievangelist-phrasing:
      intent: Archive an agent (beta-flagged endpoint)
      effect: destructive
      questions:
      - Can I archive an agent through the ?beta=true agents endpoint?
      - Using the beta-query variant, how do I archive an agent?
      instructions:
      - text: Archive agent {agent_id} via the beta-flagged endpoint.
        slots:
          agent_id: path.agent_id
      - text: Call the ?beta=true archive route for agent {agent_id}.
        slots:
          agent_id: path.agent_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/agents/{agent_id}/versions?beta=true'].get
  update:
    x-apievangelist-phrasing:
      intent: Page through an agent's versions
      effect: read
      questions:
      - Can I page through an agent's versions a few at a time?
      - What's the paginated way to read an agent's version list?
      instructions:
      - text: Page through versions of agent {agent_id}, {limit} at a time.
        slots:
          agent_id: path.agent_id
          limit: query.limit
      - text: Get the next page {page} of versions for agent {agent_id}.
        slots:
          page: query.page
          agent_id: path.agent_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/agents/{agent_id}?beta=true'].get
  update:
    x-apievangelist-phrasing:
      intent: Retrieve a specific agent version
      effect: read
      questions:
      - Can I fetch an older version of an agent's configuration?
      - How do I pin a lookup to one particular agent version?
      instructions:
      - text: Get version {version} of agent {agent_id}.
        slots:
          version: query.version
          agent_id: path.agent_id
      - text: Fetch agent {agent_id} as it was at version {version}.
        slots:
          agent_id: path.agent_id
          version: query.version
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/agents/{agent_id}?beta=true'].post
  update:
    x-apievangelist-phrasing:
      intent: Update an agent, version optional
      effect: write
      questions:
      - Can I update an agent's multiagent settings?
      - Is there an agent update where passing the version is optional?
      instructions:
      - text: Turn on multiagent config {multiagent} for agent {agent_id}.
        slots:
          multiagent: requestBody.multiagent
          agent_id: path.agent_id
      - text: Switch agent {agent_id} to model {model} without a version check.
        slots:
          agent_id: path.agent_id
          model: requestBody.model
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/agents?beta=true'].get
  update:
    x-apievangelist-phrasing:
      intent: List agents with date and archive filters
      effect: read
      questions:
      - Which agents were created in a given date range?
      - Can I include archived agents when listing them?
      instructions:
      - text: List agents created after {created_after}.
        slots:
          created_after: query.created_at[gte]
      - text: 'List all agents including archived: {include_archived}.'
        slots:
          include_archived: query.include_archived
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/agents?beta=true'].post
  update:
    x-apievangelist-phrasing:
      intent: Create an agent (beta-flagged endpoint)
      effect: write
      questions:
      - Can I create an agent through the ?beta=true route with metadata attached?
      - Using the beta-query create, can an agent get skills and MCP servers?
      instructions:
      - text: Via the beta-flagged route, create agent {name} on {model} with metadata {metadata}.
        slots:
          name: requestBody.name
          model: requestBody.model
          metadata: requestBody.metadata
      - text: Use ?beta=true to create agent {name} using {model} and skills {skills}.
        slots:
          name: requestBody.name
          model: requestBody.model
          skills: requestBody.skills
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/agents'].get
  update:
    x-apievangelist-phrasing:
      intent: List the workspace's agents
      effect: read
      questions:
      - What agents have been defined in my workspace?
      - How many agents can I get back in one page?
      instructions:
      - text: List the agents in my workspace.
      - text: Show {limit} agents from this workspace.
        slots:
          limit: query.limit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/agents'].post
  update:
    x-apievangelist-phrasing:
      intent: Define a reusable, versioned agent
      effect: write
      questions:
      - How do I define a reusable agent with a system prompt and tools?
      - What does it take to set up a versioned Claude agent?
      instructions:
      - text: Define a reusable agent {name} running {model}.
        slots:
          name: requestBody.name
          model: requestBody.model
      - text: Set up agent {name} on {model} with system prompt {system} and tools {tools}.
        slots:
          name: requestBody.name
          model: requestBody.model
          system: requestBody.system
          tools: requestBody.tools
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/agents/{agent_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an agent's latest version
      effect: read
      questions:
      - What is the current configuration of my agent?
      - How do I see the latest version of an agent?
      instructions:
      - text: Show the latest version of agent {agent_id}.
        slots:
          agent_id: path.agent_id
      - text: Get agent {agent_id}'s current config.
        slots:
          agent_id: path.agent_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/agents/{agent_id}'].post
  update:
    x-apievangelist-phrasing:
      intent: Update an agent with a version lock
      effect: write
      questions:
      - How do I update an agent without clobbering someone else's change?
      - Does changing an agent's fields create a new version?
      instructions:
      - text: Update agent {agent_id} from version {version} with system prompt {system}.
        slots:
          agent_id: path.agent_id
          version: requestBody.version
          system: requestBody.system
      - text: Change the tools of agent {agent_id}, locking on version {version}, to {tools}.
        slots:
          agent_id: path.agent_id
          version: requestBody.version
          tools: requestBody.tools
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/agents/{agent_id}/archive'].post
  update:
    x-apievangelist-phrasing:
      intent: Archive an agent, sessions keep running
      effect: destructive
      questions:
      - Do existing sessions keep running when I archive an agent?
      - How do I retire an agent nobody should start new sessions with?
      instructions:
      - text: Archive agent {agent_id} and let its running sessions finish.
        slots:
          agent_id: path.agent_id
      - text: Retire agent {agent_id}.
        slots:
          agent_id: path.agent_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/agents/{agent_id}/versions'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an agent's full version history
      effect: read
      questions:
      - How has my agent's configuration changed over time?
      - Can I see the complete version history of an agent?
      instructions:
      - text: Show the full version history of agent {agent_id}.
        slots:
          agent_id: path.agent_id
      - text: List every version agent {agent_id} has had.
        slots:
          agent_id: path.agent_id
      method: generated
      generated: '2026-09-26'