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

# Custom Agent (Beta)

<Warning>**WARNING**: Access to this endpoint requires a paid subscription plan.</Warning>

## Description

This endpoint lets you run an assistant you can configure in the UI.
Users can create a custom AI agent by providing a description of the desired functionality using natural language. The system supports both conversational inputs and advanced prompting techniques to define the agent's behavior. Before using it, [create a custom agent and retrieve its ID](/developer-resources/tutorials/custom-agent/create-custom-agents).

## Features

Custom Agent include the following features:

* **Document upload**: Provide the agent with documents to process.
* **Model selection**: Specify a preferred large language model (LLM) or use "auto" to optimize performance for specific tasks.
* **Web access control**: Enable or disable the ability of an agent to access the web.
* **Advanced tools**: Use additional tools for research and reasoning tasks.

## Enterprise Settings

To maintain enterprise security, enable Zero Data Retention on your enterprise account. Manage this setting at [you.com/settings/privacy](https://you.com/settings/privacy). When enabled, the platform does not retain your data and does not use customer data for model training.

<Warning>**WARNING**: Privacy settings can only be managed by You.com Enterprise or team admins.</Warning>


## OpenAPI

````yaml openapi_agents_custom POST /v1/agents/runs
openapi: 3.1.0
info:
  title: Agents API (Custom Agents)
  description: Run a configured Custom Agent by ID
  version: 0.1.0
servers:
  - url: https://api.you.com
security:
  - ApiKeyAuth: []
paths:
  /v1/agents/runs:
    post:
      summary: Run a Custom Agent
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - agent
                - input
              properties:
                agent:
                  type: string
                  description: The custom agent that will be used to execute your request.
                  example: 550e8400-e29b-41d4-a716-446655440000
                input:
                  oneOf:
                    - type: string
                      description: >-
                        The input for the agent. This can be a query or a
                        prompt.
                      example: >-
                        Summarize today's top AI research headlines and cite
                        sources.
                    - type: array
                      description: >-
                        Array of message objects; server converts to internal
                        Message type.
                      items:
                        type: object
                        properties:
                          content:
                            type: string
                            description: Message text content.
                            example: What are the latest trends in renewable energy?
                        required:
                          - content
                stream:
                  type: boolean
                  default: false
                  description: >-
                    When `true`, responses stream over SSE (text/event-stream).
                    When `false`, returns JSON (application/json).
      responses:
        '200':
          description: Inference response in application/json or text/event-stream format.
          content:
            application/json:
              schema:
                type: object
                properties:
                  output:
                    type: array
                    items:
                      type: object
                      properties:
                        type:
                          type: string
                          description: The type of the output.
                          example: web_search.results, chat_node.answer
                        text:
                          type: string
                          description: The text of the output.
                          example: Here are today's top AI research headlines...
                        content:
                          type: object
                          description: Returns the exact search query.
                          example: >-
                            Summarize today's top AI research headlines and cite
                            sources.
                        agent:
                          type: string
                          description: The agent ID used to generate the response.
                          example: 550e8400-e29b-41d4-a716-446655440000
            text/event-stream:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    description: Sequence number of the SSE event, starts from 0.
                    example: 0
                  event:
                    type: string
                    description: The type of the SSE event.
                    example: response.output_item.added
                  data:
                    type: object
                    properties:
                      seq_id:
                        type: integer
                        description: Sequence number of the SSE event, starts from 0.
                        example: 0
                      type:
                        type: string
                        description: The type of the SSE event.
                        example: response.output_item.added
                      response:
                        type: object
                        properties:
                          type:
                            type: string
                            description: The type of the response.
                            example: web_search.results, chat_node.answer
                          output_index:
                            type: integer
                            description: The index of the output in the response.
                            example: 0
                          delta:
                            type: string
                            description: The delta of the response.
                            example: ital of France
                          full:
                            type: object
                            description: The full response object of the output item.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  responses:
    BadRequest:
      description: Invalid request payload
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            bad_request:
              summary: Malformed body
              value:
                errors:
                  - status: '400'
                    code: bad_request
                    title: Invalid request body
                    detail: The field 'tools' must be an array of objects.
    Unauthorized:
      description: Missing or invalid Authorization header
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            unauthorized:
              summary: Missing Authorization header
              value:
                errors:
                  - status: '401'
                    code: unauthorized
                    title: Unauthorized
                    detail: >-
                      Missing or invalid Authorization header. Use
                      'Authorization: Bearer <API_KEY>'.
    NotFound:
      description: Resource not found or unsupported
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            agent_not_found:
              summary: Agent ID does not exist
              value:
                errors:
                  - status: '404'
                    code: agent_not_found
                    title: Agent not found
                    detail: >-
                      The agent with id '550e8400-e29b-41d4-a716-446655440000'
                      not found.
            agent_not_supported_yet:
              summary: Agent uses unsupported model/feature
              value:
                errors:
                  - status: '404'
                    code: agent_not_supported_yet
                    title: Agent not supported yet
                    detail: >-
                      The agent with id '550e8400-e29b-41d4-a716-446655440000'
                      uses an unsupported model or feature.
  schemas:
    ErrorResponse:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
    Error:
      type: object
      properties:
        status:
          type: string
          example: '404'
        code:
          type: string
          description: Machine readable error code
          example: agent_not_found
        title:
          type: string
          example: Agent not found
        detail:
          type: string
          example: The agent with id '550e8400-e29b-41d4-a716-446655440000' not found.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        The unique API Key required to authorize API access. Learn how to get
        yours in the [“Get your API key” section of the
        documentation](/get-started/quickstart#get-your-api-key).

````