> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs-staging.you.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs-staging.you.com/_mcp/server.
# Custom Agent
POST https://api.you.com/v1/agents/runs
Content-Type: application/json
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 you must have created a custom agent at https://you.com/agents.
## 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, we do not retain your data and do not use it for model training.
Privacy settings can only be managed by You.com Enterprise or team admins.
The data returns as SSE (Server-Side Events) with the `text/event-stream` content type in the response header. It streams data in while the agent is responding.
Reference: https://docs-staging.you.com/docs/custom-solutions/agents/custom-agent/custom-agent-runs
## OpenAPI Specification
```yaml
openapi: 3.1.0
info:
title: custom
version: 1.0.0
paths:
/v1/agents/runs:
post:
operationId: custom-agent-runs-stream
summary: Custom Agent
description: >-
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 you must have created a custom agent
at https://you.com/agents.
## 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, we do not retain your data and do not use it for model
training.
Privacy settings can only be managed by You.com Enterprise or
team admins.
The data returns as SSE (Server-Side Events) with the
`text/event-stream` content type in the response header. It streams data
in while the agent is responding.
tags:
- ''
parameters:
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
responses:
'200':
description: ''
content:
text/event-stream:
schema:
$ref: '#/components/schemas/type_:CustomAgentRunsStreamingResponse'
'400':
description: The Authorization Bearer token was missing or invalid
content:
application/json:
schema:
$ref: '#/components/schemas/type_:AgentRuns400Response'
'422':
description: When the request data coming in is invalid
content:
application/json:
schema:
$ref: '#/components/schemas/type_:AgentRuns422Response'
requestBody:
content:
application/json:
schema:
type: object
properties:
agent:
type: string
description: >-
Your Custom Agent's ID. To obtain one you must have created
a custom agent at https://you.com/agents.
input:
type: string
description: The question you'd like to ask the agent
stream:
type: boolean
enum:
- true
description: >-
Must be `true` to stream the agent response as it's
generated, and `false` to receive a response after the agent
has finished.
required:
- agent
- input
- stream
servers:
- url: https://api.you.com
description: Production
components:
schemas:
type_:ResponseCreatedType:
type: string
enum:
- response.created
title: ResponseCreatedType
type_:ResponseStartingType:
type: string
enum:
- response.starting
title: ResponseStartingType
type_:ResponseOutputItemAddedType:
type: string
enum:
- response.output_item.added
title: ResponseOutputItemAddedType
type_:ResponseOutputItemAddedResponse:
type: object
properties:
output_index:
type: integer
description: The index of the output item in the response
required:
- output_index
title: ResponseOutputItemAddedResponse
type_:ResponseOutputContentFullType:
type: string
enum:
- response.output_content.full
title: ResponseOutputContentFullType
type_:ResponseOutputContentFullResponseType:
type: string
enum:
- web_search.results
title: ResponseOutputContentFullResponseType
type_:AgentRunsResponseWebSearchResultSourceType:
type: string
enum:
- web_search
description: The type of content the agent can return outside a text response
title: AgentRunsResponseWebSearchResultSourceType
type_:AgentRunsResponseWebSearchResult:
type: object
properties:
source_type:
$ref: >-
#/components/schemas/type_:AgentRunsResponseWebSearchResultSourceType
description: The type of content the agent can return outside a text response
citation_uri:
type: string
description: The web search result the agent returned along in its response
provider:
type: string
description: This is currently unused
title:
type: string
description: The title of the web site returned under url
snippet:
type: string
description: A textual portion of the web site returned under url
thumbnail_url:
type: string
description: The thumbnail image of the url
url:
type: string
description: The web search result the agent returned along in its response
required:
- source_type
- citation_uri
- title
- snippet
- url
description: >-
The text response of the agent. This field only returns when the type is
`web_search.results`
title: AgentRunsResponseWebSearchResult
type_:ResponseOutputContentFullResponse:
type: object
properties:
output_index:
type: integer
type:
$ref: '#/components/schemas/type_:ResponseOutputContentFullResponseType'
full:
type: array
items:
$ref: '#/components/schemas/type_:AgentRunsResponseWebSearchResult'
description: Complete web search results
required:
- output_index
- type
- full
title: ResponseOutputContentFullResponse
type_:ResponseOutputItemDoneType:
type: string
enum:
- response.output_item.done
title: ResponseOutputItemDoneType
type_:ResponseOutputItemDoneResponse:
type: object
properties:
output_index:
type: integer
required:
- output_index
title: ResponseOutputItemDoneResponse
type_:ResponseOutputTextDeltaType:
type: string
enum:
- response.output_text.delta
title: ResponseOutputTextDeltaType
type_:ResponseOutputTextDeltaResponseType:
type: string
enum:
- message.answer
title: ResponseOutputTextDeltaResponseType
type_:ResponseOutputTextDeltaResponse:
type: object
properties:
output_index:
type: integer
type:
$ref: '#/components/schemas/type_:ResponseOutputTextDeltaResponseType'
delta:
type: string
description: Incremental text content
required:
- output_index
- type
- delta
title: ResponseOutputTextDeltaResponse
type_:ResponseDoneType:
type: string
enum:
- response.done
title: ResponseDoneType
type_:ResponseDoneResponse:
type: object
properties:
run_time_ms:
type: string
description: Total runtime in milliseconds
finished:
type: boolean
description: Whether the response is complete
required:
- run_time_ms
- finished
title: ResponseDoneResponse
type_:CustomAgentRunsStreamingResponse:
oneOf:
- type: object
properties:
type:
$ref: '#/components/schemas/type_:ResponseCreatedType'
seq_id:
type: integer
required:
- type
- seq_id
- type: object
properties:
type:
$ref: '#/components/schemas/type_:ResponseStartingType'
seq_id:
type: integer
required:
- type
- seq_id
- type: object
properties:
type:
$ref: '#/components/schemas/type_:ResponseOutputItemAddedType'
seq_id:
type: integer
response:
$ref: '#/components/schemas/type_:ResponseOutputItemAddedResponse'
required:
- type
- seq_id
- response
- type: object
properties:
type:
$ref: '#/components/schemas/type_:ResponseOutputContentFullType'
seq_id:
type: integer
response:
$ref: '#/components/schemas/type_:ResponseOutputContentFullResponse'
required:
- type
- seq_id
- response
- type: object
properties:
type:
$ref: '#/components/schemas/type_:ResponseOutputItemDoneType'
seq_id:
type: integer
response:
$ref: '#/components/schemas/type_:ResponseOutputItemDoneResponse'
required:
- type
- seq_id
- response
- type: object
properties:
type:
$ref: '#/components/schemas/type_:ResponseOutputTextDeltaType'
seq_id:
type: integer
response:
$ref: '#/components/schemas/type_:ResponseOutputTextDeltaResponse'
required:
- type
- seq_id
- response
- type: object
properties:
type:
$ref: '#/components/schemas/type_:ResponseDoneType'
seq_id:
type: integer
response:
$ref: '#/components/schemas/type_:ResponseDoneResponse'
required:
- type
- seq_id
- response
discriminator:
propertyName: type
description: Server-Sent Event (SSE) format for streaming agent responses
title: CustomAgentRunsStreamingResponse
type_:AgentRuns400Response:
type: object
properties:
detail:
type: string
description: The message returned by the error
title: AgentRuns400Response
type_:AgentRuns422ResponseDetailItemLocItem:
oneOf:
- type: string
- type: integer
title: AgentRuns422ResponseDetailItemLocItem
type_:AgentRuns422ResponseDetailItem:
type: object
properties:
type:
type: string
loc:
type: array
items:
$ref: '#/components/schemas/type_:AgentRuns422ResponseDetailItemLocItem'
msg:
type: string
input:
type: string
required:
- type
- loc
- msg
- input
title: AgentRuns422ResponseDetailItem
type_:AgentRuns422Response:
type: object
properties:
detail:
type: array
items:
$ref: '#/components/schemas/type_:AgentRuns422ResponseDetailItem'
title: AgentRuns422Response
securitySchemes:
bearerAuth:
type: http
scheme: bearer
```
## Examples
**Request**
```json
{
"agent": "63773261-b4de-4d8f-9dfd-cff206a5cb51",
"input": "What are some great recipes I can make in under half an hour",
"stream": true
}
```
**Response**
```text
event: response.created
data: {"seq_id":0,"type":"response.created"}
event: response.starting
data: {"seq_id":1,"type":"response.starting"}
event: response.output_item.added
data: {"seq_id":2,"type":"response.output_item.added","response":{"output_index":0}}
event: response.output_content.full
data: {"seq_id":3,"type":"response.output_content.full","response":{"output_index":0,"type":"web_search.results","full":[{"source_type":"web_search","citation_uri":"https://www.epicurious.com/recipes-menus/30-minute-meals-gallery","provider":null,"title":"51 Low-Lift 30-Minute Meals for Nights When You Just Can't ...","snippet":"Jan 14, 2022 ... But becoming a parent has convinced me that recipes that take \"under an hour ... Here's how to make the best use of everything you've got.","thumbnail_url":"https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcRX2IMUVEnRryaG2b_5aNB-OUfthPmP53Z325NyYKXcAOdKmgA0M9i72xI&s","url":"https://www.epicurious.com/recipes-menus/30-minute-meals-gallery"},{"source_type":"web_search","citation_uri":"https://www.tasteofhome.com/collection/best-30-minute-meals/","provider":null,"title":"95 of the Best 30-Minute Meals We've Ever Made | Taste of Home","snippet":"Dec 6, 2022 ... From the Recipe Creator: Easy chicken recipes are my go-to dinner choice. My chicken piccata pasta dish is ready to serve in a half hour. It …","thumbnail_url":"https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcTxLMew3wR12JXgOCLpIc5A10U7lTeBxGKyom6Fi3_cYyHlNVuAJivxB0M&s","url":"https://www.tasteofhome.com/collection/best-30-minute-meals/"},{"source_type":"web_search","citation_uri":"https://www.foodnetwork.com/recipes/photos/30-minute-dinner-recipes","provider":null,"title":"103 Easy 30-Minute Dinner Recipes That Will Save Your Weeknights","snippet":"Apr 11, 2025 ... These quick dinner ideas will help you get a meal on the table in half an hour or less. ... It's a simple recipe ready in under half an hour with …","thumbnail_url":"https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcQJTNucjGK8ZqfurwAmyuyhQ-7n7AVZHoJwUqfsqRYuCqlIpMwepNDEE_M&s","url":"https://www.foodnetwork.com/recipes/photos/30-minute-dinner-recipes"},{"source_type":"web_search","citation_uri":"https://jeffreymorgenthaler.com/how-to-make-your-own-grenadine/","provider":null,"title":"How to Make Your Own Grenadine - Jeffrey Morgenthaler","snippet":"Dec 10, 2009 ... In the end, the recipe was pretty solid and a good grenadine came out. ... It took me less than half an hour with clean up to make this. Thank …","thumbnail_url":"https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcQoswbT01RQJYn5gqxAYXXbbMkboXG-kCNSJmxJBjfjvizXSnj_B3vSuMI&s","url":"https://jeffreymorgenthaler.com/how-to-make-your-own-grenadine/"},{"source_type":"web_search","citation_uri":"https://theadventurebite.com/category/recipes/time/1-hour/","provider":null,"title":"1 Hour Or Less ~ The Adventure Bite","snippet":"Home » Recipes » Recipes By Time » 1 Hour Or Less. BROWSE RECIPES: D · 55+ Easy 15 Minute Dinner Recipes · baked potato in air fryer. AFDFGFVHD …","thumbnail_url":"https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcQpgr0Hdwe45s0Bw4B22IfVH6nR72qw-35ZNchZzacrMz52ahJ4EtYllx6R&s","url":"https://theadventurebite.com/category/recipes/time/1-hour/"},{"source_type":"web_search","citation_uri":"https://www.lifeasastrawberry.com/easy-crusty-french-bread/","provider":null,"title":"Easy Crusty French Bread (VIDEO) - Life As A Strawberry","snippet":"Jan 12, 2023 ... (*the converter in the recipe card below may tell you to double ... the half hour mark to increase strength. Finally, when shaping the …","thumbnail_url":"https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcTkp6HYji3Hsr2YAdkmx6mWA8qBFGH48DRdbJ1xNDB-TJeyra6z3XZUEjtq&s","url":"https://www.lifeasastrawberry.com/easy-crusty-french-bread/"},{"source_type":"web_search","citation_uri":"https://blue-kitchen.com/2017/12/27/baked-microwaved-potatoes/","provider":null,"title":"Half-baked a microwave start speeds baked potatoes to the table ...","snippet":"Dec 27, 2017 ... Recipe of sorts below. Half-Baked Potato. WE END THE YEAR WITH A ... Just enough time to cook some fish, chicken breasts or chops, and toss a …","thumbnail_url":"https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcSLEoeuw-zekVvA7udn--h6fUyXTR-TgmjKgMuY6gDBO-L1Met4GA1vsg&s","url":"https://blue-kitchen.com/2017/12/27/baked-microwaved-potatoes/"},{"source_type":"web_search","citation_uri":"https://www.reddit.com/r/cookingforbeginners/comments/kfn6pe/no_soak_beans_beans_from_dry_to_fully_cooked_in_w/","provider":null,"title":"No soak beans: beans from dry to fully cooked in under two hours. : r ...","snippet":"Dec 18, 2020 ... You can cook the beans from scratch by applying enough heat for a long enough period of time. I usually start with one cup (or half a bag) of dry beans, …","thumbnail_url":null,"url":"https://www.reddit.com/r/cookingforbeginners/comments/kfn6pe/no_soak_beans_beans_from_dry_to_fully_cooked_in_w/"},{"source_type":"web_search","citation_uri":"https://www.facebook.com/groups/TheWeddingCookieTableCommunity/posts/4125114214442391/","provider":null,"title":"Why do Toll House cookies turn hard after half an hour?","snippet":"Dec 13, 2024 ... My Mom's chocolate chip cookie recipe baked very flat and were great that way, but if you did the half crisco they baked thicker. 10 mos.","thumbnail_url":"https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcSz3N562Qdhzgrt78KNhpovRr2Z5R41s2w8qfrvIZ2gRHqfpG_D_h_NLSU&s","url":"https://www.facebook.com/groups/TheWeddingCookieTableCommunity/posts/4125114214442391/"},{"source_type":"web_search","citation_uri":"https://www.reddit.com/r/Breadit/comments/19fgwj7/best_sameday_pizza_dough_recipe_w/","provider":null,"title":"Best same-day pizza dough recipe? : r/Breadit","snippet":"Jan 25, 2024 ... Bake on the bottom half of your oven to get the hottest spot, you ... under two hours to complete the pizza. [deleted]. • 2y ago.","thumbnail_url":null,"url":"https://www.reddit.com/r/Breadit/comments/19fgwj7/best_sameday_pizza_dough_recipe_w/"}]}}
event: response.output_item.done
data: {"seq_id":2,"type":"response.output_item.done","response":{"output_index":0}}
event: response.output_text.delta
data: {"seq_id":7,"type":"response.output_text.delta","response":{"output_index":1,"type":"message.answer","delta":"A partial response to the question. You'll recieve many of these events to stream down the response as its being generated"}}
event: response.done
data: {"seq_id":365,"type":"response.done","response":{"run_time_ms":"5.956","finished":true}}
```
**SDK Code**
```python
# Use our official Python SDK to stream the agent response
from youdotcom import You
from youdotcom.models import (
CustomAgentRunsRequest,
ResponseOutputTextDelta,
ResponseDone,
)
with You("api_key") as you:
response = you.agents.runs.create(
request=CustomAgentRunsRequest(
agent="63773261-b4de-4d8f-9dfd-cff206a5cb51",
input="What are some great recipes I can make in under half an hour",
stream=True
)
)
with response as stream:
for chunk in stream:
event = chunk.data
if isinstance(event, ResponseOutputTextDelta):
print(event.response.delta, end="", flush=True)
elif isinstance(event, ResponseDone):
print(f"\nDone in {event.response.run_time_ms}ms")
```
```typescript
// Use our official TypeScript SDK to stream the agent response
import { You } from "@youdotcom-oss/sdk";
import type { CustomAgentRunsRequest, AgentRunsStreamingResponse } from "@youdotcom-oss/sdk/models";
import type { EventStream } from "@youdotcom-oss/sdk/lib/event-streams.js";
const you = new You({ apiKeyAuth: "api_key" });
const request: CustomAgentRunsRequest = {
agent: "63773261-b4de-4d8f-9dfd-cff206a5cb51",
stream: true,
input: "What are some great recipes I can make in under half an hour"
};
const result = await you.agentsRuns(request) as EventStream;
for await (const chunk of result) {
if (chunk.data.type === "response.output_text.delta") {
process.stdout.write(chunk.data.response.delta);
}
}
```
```javascript
// Use our official JavaScript SDK to stream the agent response
import { You } from "@youdotcom-oss/sdk";
const you = new You({ apiKeyAuth: "api_key" });
const request = {
agent: "63773261-b4de-4d8f-9dfd-cff206a5cb51",
stream: true,
input: "What are some great recipes I can make in under half an hour"
};
const result = await you.agentsRuns(request);
for await (const chunk of result) {
if (chunk.data.type === "response.output_text.delta") {
process.stdout.write(chunk.data.response.delta);
}
}
```
```go
package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.you.com/v1/agents/runs"
payload := strings.NewReader("{\n \"agent\": \"63773261-b4de-4d8f-9dfd-cff206a5cb51\",\n \"input\": \"What are some great recipes I can make in under half an hour\",\n \"stream\": true\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer ")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
```
```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;
HttpResponse response = Unirest.post("https://api.you.com/v1/agents/runs")
.header("Authorization", "Bearer ")
.header("Content-Type", "application/json")
.body("{\n \"agent\": \"63773261-b4de-4d8f-9dfd-cff206a5cb51\",\n \"input\": \"What are some great recipes I can make in under half an hour\",\n \"stream\": true\n}")
.asString();
```
```csharp
using RestSharp;
var client = new RestClient("https://api.you.com/v1/agents/runs");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer ");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n \"agent\": \"63773261-b4de-4d8f-9dfd-cff206a5cb51\",\n \"input\": \"What are some great recipes I can make in under half an hour\",\n \"stream\": true\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```
```swift
import Foundation
let headers = [
"Authorization": "Bearer ",
"Content-Type": "application/json"
]
let parameters = [
"agent": "63773261-b4de-4d8f-9dfd-cff206a5cb51",
"input": "What are some great recipes I can make in under half an hour",
"stream": true
] as [String : Any]
let postData = JSONSerialization.data(withJSONObject: parameters, options: [])
let request = NSMutableURLRequest(url: NSURL(string: "https://api.you.com/v1/agents/runs")! as URL,
cachePolicy: .useProtocolCachePolicy,
timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data
let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
if (error != nil) {
print(error as Any)
} else {
let httpResponse = response as? HTTPURLResponse
print(httpResponse)
}
})
dataTask.resume()
```