> ## Documentation Index
> Fetch the complete documentation index at: https://developer.watson-orchestrate.ibm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Register An External Chat Completions Agent.

<Note>
  If only one of the fields [**name**](#body-name) or [**nickname**](#body-nickname) is provided, the system automatically generates the other based on the value you entered.
</Note>


## OpenAPI

````yaml post /v1/agents/external-chat
openapi: 3.1.0
info:
  title: WxO Server API
  summary: API for the next gen watsonx Orchestrate stack
  description: >+

    The watsonx Orchestrate Server provides a set of APIs to power the watsonx
    Orchestrate AI assistant. This includes the following core services:


    * Orchestrate Assistant - a built-in AI assistant that powers the
    Orchestrate end-user experience.

    * Custom Assistants - a service layer for interacting with existing AI
    assistatns (such as those in watsonx Assistant).

    * Message Threads - a chat history and async message tracking store.

    * Document Store - manage collections of documents in nearly any format
    including text, pdf, html and many more.

    * Information Extraction - automatically extract clean text and images from
    any document in the Document Store.  Also extract other useful metadata like
    questions answered, keywords, and named entities.

    * Embedding - generate vector embeddings for text and images in the Document
    Store.

    * Vector Index and Retrieval - automatically index documents with rich
    metadata for vector search or hybrid search.

    * Search Engine - create a Gen AI powered search engine that works like Bing
    or Google.

    * Query Engine - configure your own RAG (Retrieval Augmented Generation)
    engine supporting advanced retrieval patterns and automated data management.

    * Model Proxy - create your own LLM model endpoints for chat completions and
    embeddings.  Supports IBM watsonx.ai, IBM BAM, OpenAI, MistralAI, or Ollama
    for local models.


    WxO API Server utilizes the following open source projects:


    * [PostgreSQL](https://www.postgresql.org/)

    * [PGVector](https://github.com/pgvector/pgvector)

    * [LlamaIndex](https://docs.llamaindex.ai/en/stable/)

    * [LangChain](https://python.langchain.com/docs/get_started/introduction)

    * [FastAPI](https://fastapi.tiangolo.com/)

    * [Unstructured](https://unstructured.io/)

    * [Celery](https://docs.celeryproject.org/en/stable/)

  version: 0.1.0
servers:
  - url: https://{api_endpoint}
    description: version
security: []
paths:
  /v1/agents/external-chat:
    post:
      tags:
        - External Chat Agents
      summary: Register An External Chat Completions Agent.
      operationId: >-
        Register_an_external_chat_completions_agent__v1_agents_external_chat_post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateExternalChatAgent'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - HTTPBearer: []
components:
  schemas:
    CreateExternalChatAgent:
      properties:
        title:
          anyOf:
            - type: string
            - type: 'null'
          title: Title
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
        tags:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Tags
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
        api_url:
          type: string
          title: Api Url
        auth_scheme:
          $ref: '#/components/schemas/ExternalAgentAuthScheme'
          default: BEARER_TOKEN
        auth_config:
          additionalProperties: true
          type: object
          title: Auth Config
          default: {}
        chat_params:
          additionalProperties: true
          type: object
          title: Chat Params
          default: {}
        instructions:
          anyOf:
            - type: string
            - type: 'null'
          title: Instructions
        config:
          anyOf:
            - $ref: '#/components/schemas/ExternalChatAgentConfig'
            - type: 'null'
        nickname:
          anyOf:
            - type: string
            - type: 'null'
          title: Nickname
        connection_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Connection Id
        provider:
          type: string
          title: Provider
          default: external_chat
        context_access_enabled:
          type: boolean
          title: Context Access Enabled
          description: Enable access to context variables for this agent
          default: true
        context_variables:
          items:
            type: string
          type: array
          title: Context Variables
          description: List of context variable names that this agent can access
          default: []
      type: object
      required:
        - api_url
      title: CreateExternalChatAgent
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ExternalAgentAuthScheme:
      type: string
      enum:
        - BEARER_TOKEN
        - API_KEY
        - NONE
      title: ExternalAgentAuthScheme
    ExternalChatAgentConfig:
      properties:
        hidden:
          type: boolean
          title: Hidden
          default: false
        enable_cot:
          type: boolean
          title: Enable Cot
          default: false
      type: object
      title: ExternalChatAgentConfig
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer

````