Custom Agent API | Build Your Own AI Agents

Run a Custom Agent

curl --request POST \
  --url https://api.you.com/v1/agents/runs \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "agent": "550e8400-e29b-41d4-a716-446655440000",
  "input": "Summarize today's top AI research headlines and cite sources.",
  "stream": false
}
EOF

import requests

url = "https://api.you.com/v1/agents/runs"

payload = {
    "agent": "550e8400-e29b-41d4-a716-446655440000",
    "input": "Summarize today's top AI research headlines and cite sources.",
    "stream": False
}
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    agent: '550e8400-e29b-41d4-a716-446655440000',
    input: 'Summarize today\'s top AI research headlines and cite sources.',
    stream: false
  })
};

fetch('https://api.you.com/v1/agents/runs', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.you.com/v1/agents/runs",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'agent' => '550e8400-e29b-41d4-a716-446655440000',
    'input' => 'Summarize today\'s top AI research headlines and cite sources.',
    'stream' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.you.com/v1/agents/runs"

	payload := strings.NewReader("{\n  \"agent\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"input\": \"Summarize today's top AI research headlines and cite sources.\",\n  \"stream\": false\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.you.com/v1/agents/runs")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"agent\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"input\": \"Summarize today's top AI research headlines and cite sources.\",\n  \"stream\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.you.com/v1/agents/runs")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"agent\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"input\": \"Summarize today's top AI research headlines and cite sources.\",\n  \"stream\": false\n}"

response = http.request(request)
puts response.read_body

{
  "output": [
    {
      "type": "web_search.results, chat_node.answer",
      "text": "Here are today's top AI research headlines...",
      "content": "Summarize today's top AI research headlines and cite sources.",
      "agent": "550e8400-e29b-41d4-a716-446655440000"
    }
  ]
}

POST

agents

runs

Run a Custom Agent

curl --request POST \
  --url https://api.you.com/v1/agents/runs \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "agent": "550e8400-e29b-41d4-a716-446655440000",
  "input": "Summarize today's top AI research headlines and cite sources.",
  "stream": false
}
EOF

import requests

url = "https://api.you.com/v1/agents/runs"

payload = {
    "agent": "550e8400-e29b-41d4-a716-446655440000",
    "input": "Summarize today's top AI research headlines and cite sources.",
    "stream": False
}
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    agent: '550e8400-e29b-41d4-a716-446655440000',
    input: 'Summarize today\'s top AI research headlines and cite sources.',
    stream: false
  })
};

fetch('https://api.you.com/v1/agents/runs', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.you.com/v1/agents/runs",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'agent' => '550e8400-e29b-41d4-a716-446655440000',
    'input' => 'Summarize today\'s top AI research headlines and cite sources.',
    'stream' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.you.com/v1/agents/runs"

	payload := strings.NewReader("{\n  \"agent\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"input\": \"Summarize today's top AI research headlines and cite sources.\",\n  \"stream\": false\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.you.com/v1/agents/runs")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"agent\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"input\": \"Summarize today's top AI research headlines and cite sources.\",\n  \"stream\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.you.com/v1/agents/runs")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"agent\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"input\": \"Summarize today's top AI research headlines and cite sources.\",\n  \"stream\": false\n}"

response = http.request(request)
puts response.read_body

{
  "output": [
    {
      "type": "web_search.results, chat_node.answer",
      "text": "Here are today's top AI research headlines...",
      "content": "Summarize today's top AI research headlines and cite sources.",
      "agent": "550e8400-e29b-41d4-a716-446655440000"
    }
  ]
}

WARNING: Access to this endpoint requires a paid subscription plan.

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.

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. When enabled, the platform does not retain your data and does not use customer data for model training.

WARNING: Privacy settings can only be managed by You.com Enterprise or team admins.

Authorizations

Authorization

string

header

required

The unique API Key required to authorize API access. Learn how to get yours in the “Get your API key” section of the documentation.

Body

application/json

agent

string

required

The custom agent that will be used to execute your request.

Example:

"550e8400-e29b-41d4-a716-446655440000"

input

required

The input for the agent. This can be a query or a prompt.

Example:

"Summarize today's top AI research headlines and cite sources."

stream

boolean

default:false

When true, responses stream over SSE (text/event-stream). When false, returns JSON (application/json).

Response

Inference response in application/json or text/event-stream format.

output

object[]

Show child attributes

API Reference

Custom Agent (Beta)

Description

Features

Enterprise Settings

Authorizations

Body

Response

​Description

​Features

​Enterprise Settings

Authorizations

Body

Response

Description

Features

Enterprise Settings