# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for One AI Agents API
  version: 1.0.0
extends: openapi/integration-os-ai-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: 15
- target: $.paths['/v1/ai-agents'].get
  update:
    x-apievangelist-phrasing:
      intent: List my AI agents
      effect: read
      questions:
      - Which AI agents do I have in my account?
      - Why don't my test agents show up when I use a live key?
      instructions:
      - text: List my AI agents.
      - text: Show {limit} of my personal agents on page {page}.
        slots:
          limit: query.limit
          page: query.page
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/ai-agents'].post
  update:
    x-apievangelist-phrasing:
      intent: Create an AI agent
      effect: write
      questions:
      - How do I create an AI agent in my own account with a chosen model and skills?
      - Can a new agent have guardrails, triggers and memory set at creation?
      instructions:
      - text: Create a personal agent named {name} on model {model} with tools {tools}.
        slots:
          name: requestBody.name
          model: requestBody.model
          tools: requestBody.tools
      - text: Make an agent {name} using {model}, skills {tools}, that wakes on triggers {triggers}.
        slots:
          name: requestBody.name
          model: requestBody.model
          tools: requestBody.tools
          triggers: requestBody.triggers
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/ai-agents/organizations/{org_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: List an organization's AI agents
      effect: read
      questions:
      - What AI agents does my organization own?
      - Can I page through org-level agents shared across projects?
      instructions:
      - text: List AI agents owned by organization {org_id}.
        slots:
          org_id: path.org_id
      - text: Show page {page} of org {org_id}'s agents.
        slots:
          org_id: path.org_id
          page: query.page
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/ai-agents/organizations/{org_id}'].post
  update:
    x-apievangelist-phrasing:
      intent: Create an organization AI agent
      effect: write
      questions:
      - How do I create an agent that every project in my organization can see?
      - Does creating an org agent count against my organization's plan quota?
      instructions:
      - text: Create organization agent {name} in org {org_id} on model {model} with tools {tools}.
        slots:
          name: requestBody.name
          org_id: path.org_id
          model: requestBody.model
          tools: requestBody.tools
      - text: Add an org-wide agent {name} to {org_id} using {model}, skills {tools}, channels {channels}.
        slots:
          name: requestBody.name
          org_id: path.org_id
          model: requestBody.model
          tools: requestBody.tools
          channels: requestBody.channels
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/ai-agents/organizations/{org_id}/projects/{project_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: List a project's AI agents
      effect: read
      questions:
      - Which AI agents live inside a specific project?
      - Can I list only the agents scoped to one project?
      instructions:
      - text: List AI agents in project {project_id} of organization {org_id}.
        slots:
          project_id: path.project_id
          org_id: path.org_id
      - text: Show {limit} project agents per page for project {project_id}, org {org_id}.
        slots:
          limit: query.limit
          project_id: path.project_id
          org_id: path.org_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/ai-agents/organizations/{org_id}/projects/{project_id}'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a project AI agent
      effect: write
      questions:
      - How do I create an agent isolated to a single project?
      - Is a project-scoped agent limited by the project's plan quota?
      instructions:
      - text: Create project agent {name} in project {project_id}, org {org_id}, on model {model} with tools {tools}.
        slots:
          name: requestBody.name
          project_id: path.project_id
          org_id: path.org_id
          model: requestBody.model
          tools: requestBody.tools
      - text: Add agent {name} to project {project_id} (org {org_id}) using {model}, skills {tools}, guardrails {guardrails}.
        slots:
          name: requestBody.name
          project_id: path.project_id
          org_id: path.org_id
          model: requestBody.model
          tools: requestBody.tools
          guardrails: requestBody.guardrails
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/ai-agents/organizations/{org_id}/projects/{project_id}/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a project AI agent's configuration
      effect: read
      questions:
      - How is a particular project agent configured?
      - What model and skills does a given project-scoped agent use?
      instructions:
      - text: Get project agent {id} in project {project_id}, org {org_id}.
        slots:
          id: path.id
          project_id: path.project_id
          org_id: path.org_id
      - text: Show the full config of agent {id} under project {project_id} in organization {org_id}.
        slots:
          id: path.id
          project_id: path.project_id
          org_id: path.org_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/ai-agents/organizations/{org_id}/projects/{project_id}/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a project AI agent
      effect: destructive
      questions:
      - How do I permanently delete an agent from a project?
      - Does deleting a project agent also shut down its runner?
      instructions:
      - text: Delete project agent {id} from project {project_id}, org {org_id}.
        slots:
          id: path.id
          project_id: path.project_id
          org_id: path.org_id
      - text: Permanently remove agent {id} in project {project_id} of organization {org_id}.
        slots:
          id: path.id
          project_id: path.project_id
          org_id: path.org_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/ai-agents/organizations/{org_id}/projects/{project_id}/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a project AI agent
      effect: write
      questions:
      - Can I switch the model on an existing project agent?
      - How do I pause a project-scoped agent without deleting it?
      instructions:
      - text: Change project agent {id} in project {project_id}, org {org_id}, to model {model}.
        slots:
          id: path.id
          project_id: path.project_id
          org_id: path.org_id
          model: requestBody.model
      - text: Set active to {active} on agent {id} in project {project_id} of organization {org_id}.
        slots:
          active: requestBody.active
          id: path.id
          project_id: path.project_id
          org_id: path.org_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/ai-agents/organizations/{org_id}/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an organization AI agent's configuration
      effect: read
      questions:
      - How is an organization-level agent set up?
      - Which triggers and channels does an org agent have?
      instructions:
      - text: Get organization agent {id} in org {org_id}.
        slots:
          id: path.id
          org_id: path.org_id
      - text: Show org {org_id}'s agent {id} configuration.
        slots:
          id: path.id
          org_id: path.org_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/ai-agents/organizations/{org_id}/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an organization AI agent
      effect: destructive
      questions:
      - How do I delete an agent owned by my organization?
      - Will removing an org agent stop its running runner?
      instructions:
      - text: Delete organization agent {id} from org {org_id}.
        slots:
          id: path.id
          org_id: path.org_id
      - text: Permanently remove org {org_id}'s agent {id}.
        slots:
          id: path.id
          org_id: path.org_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/ai-agents/organizations/{org_id}/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update an organization AI agent
      effect: write
      questions:
      - Can I change the guardrails on an org-wide agent?
      - Which settings can I edit on an existing organization agent?
      instructions:
      - text: Update organization agent {id} in org {org_id} with guardrails {guardrails}.
        slots:
          id: path.id
          org_id: path.org_id
          guardrails: requestBody.guardrails
      - text: Rename org {org_id}'s agent {id} to {name}.
        slots:
          id: path.id
          org_id: path.org_id
          name: requestBody.name
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/ai-agents/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an AI agent's configuration
      effect: read
      questions:
      - What model, skills and memory does my agent have?
      - Can I check my personal agent's current status?
      instructions:
      - text: Get my agent {id}.
        slots:
          id: path.id
      - text: Show the full configuration and status of personal agent {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/ai-agents/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an AI agent
      effect: destructive
      questions:
      - How do I delete one of my agents for good?
      - Are pending scheduled runs cancelled when I delete my agent?
      instructions:
      - text: Delete my agent {id}.
        slots:
          id: path.id
      - text: Permanently remove personal agent {id} and cancel its scheduled runs.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/ai-agents/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update an AI agent
      effect: write
      questions:
      - Can I add new skills to one of my existing agents?
      - Is there a way to make my personal agent inactive instead of deleting it?
      instructions:
      - text: Set the tools on my agent {id} to {tools}.
        slots:
          id: path.id
          tools: requestBody.tools
      - text: Mark personal agent {id} active {active}.
        slots:
          id: path.id
          active: requestBody.active
      method: generated
      generated: '2026-10-01'