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

# Create or replace agent

> Create or replace agent. If there is an existing agent with the same name as the one specified in the request, will replace the existing agent with the provided fields



## OpenAPI

````yaml /openapi.yaml put /v1/agent
openapi: 3.1.1
info:
  version: 1.0.0
  title: Braintrust API
  description: >-
    API specification for the backend data server. The API is hosted globally at

    https://api.braintrust.dev or in your own environment.


    You can access the OpenAPI spec for this API at
    https://github.com/braintrustdata/braintrust-openapi.
  license:
    name: Apache 2.0
servers:
  - url: https://api.braintrust.dev
security:
  - bearerAuth: []
  - {}
paths:
  /v1/agent:
    put:
      tags:
        - Agents
      summary: Create or replace agent
      description: >-
        Create or replace agent. If there is an existing agent with the same
        name as the one specified in the request, will replace the existing
        agent with the provided fields
      operationId: putAgent
      requestBody:
        description: Any desired information about the new agent object
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAgent'
      responses:
        '200':
          description: Returns the new agent object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agent'
        '400':
          description: >-
            The request was unacceptable, often due to missing a required
            parameter
          content:
            text/plain:
              schema:
                type: string
            application/json:
              schema:
                nullable: true
        '401':
          description: No valid API key provided
          content:
            text/plain:
              schema:
                type: string
            application/json:
              schema:
                nullable: true
        '403':
          description: The API key doesn’t have permissions to perform the request
          content:
            text/plain:
              schema:
                type: string
            application/json:
              schema:
                nullable: true
        '429':
          description: >-
            Too many requests hit the API too quickly. We recommend an
            exponential backoff of your requests
          headers:
            Retry-After:
              schema:
                type: string
          content:
            text/plain:
              schema:
                type: string
            application/json:
              schema:
                nullable: true
        '500':
          description: Something went wrong on Braintrust's end. (These are rare.)
          content:
            text/plain:
              schema:
                type: string
            application/json:
              schema:
                nullable: true
      security:
        - bearerAuth: []
        - {}
components:
  schemas:
    CreateAgent:
      type: object
      properties:
        project_id:
          type: string
          format: uuid
          description: Unique identifier for the project that the agent belongs under
        name:
          type: string
          description: Name of the agent. Within a project, agent names are unique
        description:
          type: string
          nullable: true
          description: Textual description of the agent
        metadata:
          type: object
          nullable: true
          additionalProperties:
            nullable: true
          description: User-controlled metadata about the agent
      required:
        - project_id
        - name
      description: >-
        An agent is a project-scoped durable object that identifies an AI agent
        or service emitting spans
    Agent:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the agent
        project_id:
          type: string
          format: uuid
          description: Unique identifier for the project that the agent belongs under
        user_id:
          type: string
          format: uuid
        created:
          type: string
          nullable: true
          format: date-time
          description: Date of agent creation
        name:
          type: string
          description: Name of the agent. Within a project, agent names are unique
        slug:
          type: string
          description: >-
            Stable, URL-safe identifier for the agent, unique within its
            project.
        kind:
          type: string
          description: >-
            Agent classification: 'custom' for customer-defined agents, 'loop'
            for built-in Loop agents.
        description:
          type: string
          nullable: true
          description: Textual description of the agent
        metadata:
          type: object
          nullable: true
          additionalProperties:
            nullable: true
          description: User-controlled metadata about the agent
      required:
        - id
        - project_id
        - user_id
        - name
        - slug
        - kind
      description: >-
        An agent is a project-scoped durable object that identifies an AI agent
        or service emitting spans
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key or JWT
      description: >-
        Most Braintrust endpoints are authenticated by providing your API key as
        a header `Authorization: Bearer [api_key]` to your HTTP request. You can
        create an API key in the Braintrust [organization settings
        page](https://www.braintrustdata.com/app/settings?subroute=api-keys).

````