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

# Create an agent

> Creates a new agent with the given properties.



## OpenAPI

````yaml admin-openapi POST /agents
openapi: 3.0.1
info:
  title: api
  version: 0.0.1
servers:
  - url: https://api.proficientai.com
    description: Production (The production environment)
  - url: https://main-64bxvpctea-uc.a.run.app
    description: Staging (The staging environment)
  - url: http://localhost:8080
    description: Development (The local environment)
security: []
paths:
  /agents:
    post:
      tags:
        - Agents
      summary: Create an agent
      description: Creates a new agent with the given properties.
      operationId: agents_create
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentCreateParams'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agent'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
components:
  schemas:
    AgentCreateParams:
      title: AgentCreateParams
      type: object
      description: The data with which an agent is created.
      properties:
        description:
          $ref: '#/components/schemas/AgentDescription'
          nullable: true
        display_description:
          $ref: '#/components/schemas/AgentDisplayDescription'
          nullable: true
        display_name:
          $ref: '#/components/schemas/AgentDisplayName'
          nullable: true
        greeting_message:
          $ref: '#/components/schemas/GreetingMessage'
          nullable: true
        initial_turn:
          $ref: '#/components/schemas/InitialTurn'
          nullable: true
        model:
          $ref: '#/components/schemas/Model'
        name:
          $ref: '#/components/schemas/AgentName'
          nullable: true
        openai:
          $ref: '#/components/schemas/OpenAIConfig'
          nullable: true
        system_message:
          $ref: '#/components/schemas/SystemMessage'
          nullable: true
      required:
        - model
    Agent:
      title: Agent
      type: object
      description: >-
        <p>An _agent_ is an AI entity that exists to serve your project's users.
        Agents are intelligent, configurable and context-aware and can interact
        with your users via a messaging system enabled by the Proficient
        API.</p>
      properties:
        id:
          $ref: '#/components/schemas/AgentId'
        object:
          $ref: '#/components/schemas/AgentObjectType'
        active:
          $ref: '#/components/schemas/AgentActiveStatus'
        description:
          $ref: '#/components/schemas/AgentDescription'
        display_description:
          $ref: '#/components/schemas/AgentDisplayDescription'
        display_name:
          $ref: '#/components/schemas/AgentDisplayName'
        name:
          $ref: '#/components/schemas/AgentName'
        created_at:
          $ref: '#/components/schemas/CreatedAt'
        updated_at:
          $ref: '#/components/schemas/UpdatedAt'
      required:
        - id
        - object
        - active
        - description
        - display_description
        - display_name
        - name
        - created_at
        - updated_at
    ApiError:
      title: ApiError
      type: object
      description: >-
        Represents the general interface of an API error. The body of every
        error returned by the API contains `code` and `message` fields.
      properties:
        error:
          $ref: '#/components/schemas/ApiErrorBody'
      required:
        - error
    AgentDescription:
      title: AgentDescription
      type: string
      description: The description of the agent, intended for developers' reference.
    AgentDisplayDescription:
      title: AgentDisplayDescription
      type: string
      description: >-
        The agent's public-facing description, meant to be visible to your
        users.
    AgentDisplayName:
      title: AgentDisplayName
      type: string
      description: >-
        The agent's display name, intended to serve as the public-facing name
        visible to your users.
    GreetingMessage:
      title: GreetingMessage
      type: string
      description: >-
        <p>The message sent by the agent to initiate an interaction. This
        property supports <a
        href="https://handlebarsjs.com/guide/#what-is-handlebars">Handlebars</a>
        template format where you have access to the <code>user</code> and
        <code>agent</code> parameters. You can use these parameters to add
        context and personalize the message.</p>
    InitialTurn:
      $ref: '#/components/schemas/InteractionParticipant'
      title: InitialTurn
      description: >-
        Indicates who sends the first message in each interaction. Defaults to
        `"user"`.
    Model:
      title: Model
      type: string
      enum:
        - anthropic.claude-v1
        - anthropic.claude-v1-100k
        - anthropic.claude-instant-v1
        - anthropic.claude-instant-v1-100k
        - openai.gpt-4
        - openai.gpt-3.5-turbo
        - openai.gpt-3.5-turbo-16k
      description: The underlying model that powers the agent.
    AgentName:
      title: AgentName
      type: string
      description: >-
        The name of the agent, designed to be visible to developers for internal
        reference purposes.
    OpenAIConfig:
      title: OpenAIConfig
      type: object
      description: The configuration that is applied to OpenAI models.
      properties:
        frequency_penalty:
          $ref: '#/components/schemas/OpenAIConfigFrequencyPenalty'
          nullable: true
        presence_penalty:
          $ref: '#/components/schemas/OpenAIConfigPresencePenalty'
          nullable: true
        temperature:
          $ref: '#/components/schemas/OpenAIConfigTemperature'
          nullable: true
        top_p:
          $ref: '#/components/schemas/OpenAIConfigTopP'
          nullable: true
    SystemMessage:
      title: SystemMessage
      type: string
      description: >-
        <p>The system prompt that will be injected at the beginning of each
        interaction. This property supports <a
        href="https://handlebarsjs.com/guide/#what-is-handlebars">Handlebars</a>
        template format where you have access to the <code>user</code> and
        <code>agent</code> parameters. You can use these parameters to provide
        rich context to the agent and steer it in a specific direction.</p>
    AgentId:
      title: AgentId
      type: string
      description: The unique identifier of the agent
    AgentObjectType:
      title: AgentObjectType
      type: string
      enum:
        - agent
      description: The type of the `Agent` object
    AgentActiveStatus:
      title: AgentActiveStatus
      type: boolean
      description: >-
        Whether the agent is currently active. If not, users will not be able to
        interact with the agent.
    CreatedAt:
      title: CreatedAt
      type: integer
      description: >-
        The time at which the object was created, measured in milliseconds since
        the Unix epoch
    UpdatedAt:
      title: UpdatedAt
      type: integer
      description: >-
        The time at which the object was last updated, measured in milliseconds
        since the Unix epoch
    ApiErrorBody:
      title: ApiErrorBody
      type: object
      properties:
        code:
          $ref: '#/components/schemas/ApiErrorCode'
        message:
          type: string
      required:
        - code
        - message
    InteractionParticipant:
      title: InteractionParticipant
      type: string
      enum:
        - user
        - agent
      description: >-
        Represents the type of the participant in a given interaction. As an
        example, message are created by interaction participants so the
        `sent_by` property of a `Message` object must be an
        `InteractionParticipant`.
    OpenAIConfigFrequencyPenalty:
      title: OpenAIConfigFrequencyPenalty
      type: number
      format: double
      description: >-
        <p>Can take values between -2.0 and 2.0, with positive values penalizing
        the model for generating new tokens that have already appeared
        frequently in the generated text so far. This reduces the likelihood of
        the model repeating the same line or phrase verbatim. In essence, a
        higher positive value for <code>frequency_penalty</code> encourages the
        model to use less frequently used tokens in the generated text. See
        original <a
        href="https://platform.openai.com/docs/api-reference/completions/create#completions/create-frequency_penalty">definition</a>.</p>
    OpenAIConfigPresencePenalty:
      title: OpenAIConfigPresencePenalty
      type: number
      format: double
      description: >-
        <p>Can take values between -2.0 and 2.0, with positive values penalizing
        the model for generating new tokens that have already appeared in the
        generated text. This encourages the model to generate text about new
        topics and increases the likelihood of generating more diverse content.
        In essence, a higher positive value for <code>presence_penalty</code>
        will lead to more avoidance of repeating previously used tokens in the
        generated text. See original <a
        href="https://platform.openai.com/docs/api-reference/completions/create#completions/create-presence_penalty">definition</a>.</p>
    OpenAIConfigTemperature:
      title: OpenAIConfigTemperature
      type: number
      format: double
      description: >-
        <p>Determines the level of randomness in the generated output. Can take
        values between 0 and 2.0, with higher values like 0.8 resulting in more
        randomness, and lower values like 0.2 making the output more
        predictable. See original <a
        href="https://platform.openai.com/docs/api-reference/completions/create#completions/create-temperature">definition</a>.</p>
    OpenAIConfigTopP:
      title: OpenAIConfigTopP
      type: number
      format: double
      description: >-
        <p>An alternative to the <code>temperature</code> option. Uses a method
        called nucleus sampling, which involves considering only the tokens with
        the highest probability mass. It specifies the proportion of the
        probability mass to consider, with a value of 0.1 indicating that only
        the tokens comprising the top 10% probability mass will be taken into
        account. In essence, <code>top_p</code> determines the size of the set
        of tokens to choose from, based on their probabilities. See original <a
        href="https://platform.openai.com/docs/api-reference/completions/create#completions/create-top_p">definition</a>.</p>
    ApiErrorCode:
      title: ApiErrorCode
      type: string
      enum:
        - invalid_request
        - invalid_credentials
        - forbidden
        - resource_not_found
        - conflict
        - unavailable
        - unknown

````