For clean Markdown of any page, append .md to the page URL. For a complete documentation index, see https://you.com/docs/custom-solutions/agents/advanced-agent/llms.txt. For full documentation content, see https://you.com/docs/custom-solutions/agents/advanced-agent/llms-full.txt.
# Advanced Agent
POST https://api.you.com/v1/agents/runs
Content-Type: application/json
This endpoint engages advanced agents that use tools, multi-turn reasoning, and planning to solve complex queries. The agents break down each query into a workflow, execute the steps iteratively, and reflect on the findings before generating a final response.
Use it for answering complex questions that require in depth responses.
The data returns as a JSON payload with a `application/json` content type.
The call only returns when the agent has finished fully responding to the input question.
Reference: https://you.com/docs/custom-solutions/agents/advanced-agent/advanced-agent-runs
## OpenAPI Specification
```yaml
openapi: 3.1.0
info:
title: advanced
version: 1.0.0
paths:
/v1/agents/runs:
post:
operationId: advanced-agent-runs
summary: Advanced Agent
description: >-
This endpoint engages advanced agents that use tools, multi-turn
reasoning, and planning to solve complex queries. The agents break down
each query into a workflow, execute the steps iteratively, and reflect
on the findings before generating a final response.
Use it for answering complex questions that require in depth responses.
The data returns as a JSON payload with a `application/json` content
type.
The call only returns when the agent has finished fully responding
to the input question.
tags:
- ''
parameters:
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/type_:AdvancedAgentRunsBatchResponse'
'401':
description: The Authorization Bearer token was missing or invalid
content:
application/json:
schema:
$ref: '#/components/schemas/type_:AgentRuns401Response'
'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:
$ref: '#/components/schemas/type_:AdvancedAgentRunsRequestAgent'
description: >-
Setting this value to "advanced" is mandatory to use the
advanced agent.
input:
type: string
description: The question you'd like to ask the agent
stream:
type: boolean
enum:
- false
description: >-
Must be set to `true` when you want to stream the agent
response as its being generated, and `false` when you want
the response to return after the agent has finished.
tools:
type: array
items:
$ref: >-
#/components/schemas/type_:AdvancedAgentRunsRequestToolsItem
description: >-
The advanced agent accepts either `compute` or `research`
tools Compute allows your agent to use a Python code
interpreter for tasks such as data analysis, mathematical
calculations, and plot generation.
Research
iteratively searches the web, analyzes the results, and
stops when finished. It then provides a comprehensive report
to your agent with current, cited information.
verbosity:
$ref: '#/components/schemas/type_:AdvancedAgentRunsRequestVerbosity'
description: >-
Controls the level of detail provided by the agent's
response. Choosing high maps to a long-form report while
medium maps to a medium verbosity report that captures most
details but is less comprehensive.
workflow_config:
$ref: >-
#/components/schemas/type_:AdvancedAgentRunsRequestWorkflowConfig
description: >-
Defines the maximum number of steps the agent uses in its
workflow plan to answer your query. Higher values allow for
more tool calls, but it takes longer for the agent to
provide the response. For instance, setting
max_workflow_steps=5 could allow the agent to call the
research tool 3 times and the compute tool 2 times.
required:
- agent
- input
- stream
servers:
- url: https://api.you.com
components:
schemas:
type_:AdvancedAgentRunsRequestAgent:
type: string
enum:
- advanced
description: Setting this value to "advanced" is mandatory to use the advanced agent.
title: AdvancedAgentRunsRequestAgent
type_:AdvancedAgentRunsRequestToolsItemResearchSearchEffort:
type: string
enum:
- auto
- low
- medium
- high
description: >-
This parameter maps to different configurations regarding the depth of
research the tool can perform. Its values range from `low`, `medium` to
`high`.
Alternatively, use `auto` mode for a more dynamic search approach,
allowing the tool the freedom to adjust its subparameters.
title: AdvancedAgentRunsRequestToolsItemResearchSearchEffort
type_:AdvancedAgentRunsRequestToolsItemResearchReportVerbosity:
type: string
enum:
- medium
- high
description: Select whether to receive a medium or high length model response.
title: AdvancedAgentRunsRequestToolsItemResearchReportVerbosity
type_:AdvancedAgentRunsRequestToolsItem:
oneOf:
- type: object
properties:
type:
type: string
enum:
- compute
description: 'Discriminator value: compute'
required:
- type
- type: object
properties:
type:
type: string
enum:
- research
description: 'Discriminator value: research'
search_effort:
$ref: >-
#/components/schemas/type_:AdvancedAgentRunsRequestToolsItemResearchSearchEffort
description: >-
This parameter maps to different configurations regarding the
depth of research the tool can perform. Its values range from
`low`, `medium` to `high`.
Alternatively, use `auto` mode for a more dynamic search
approach, allowing the tool the freedom to adjust its
subparameters.
report_verbosity:
$ref: >-
#/components/schemas/type_:AdvancedAgentRunsRequestToolsItemResearchReportVerbosity
description: >-
Select whether to receive a medium or high length model
response.
required:
- type
- search_effort
- report_verbosity
discriminator:
propertyName: type
title: AdvancedAgentRunsRequestToolsItem
type_:AdvancedAgentRunsRequestVerbosity:
type: string
enum:
- medium
- high
description: >-
Controls the level of detail provided by the agent's response. Choosing
high maps to a long-form report while medium maps to a medium verbosity
report that captures most details but is less comprehensive.
title: AdvancedAgentRunsRequestVerbosity
type_:AdvancedAgentRunsRequestWorkflowConfig:
type: object
properties:
max_workflow_steps:
type: integer
default: 10
required:
- max_workflow_steps
description: >-
Defines the maximum number of steps the agent uses in its workflow plan
to answer your query. Higher values allow for more tool calls, but it
takes longer for the agent to provide the response. For instance,
setting max_workflow_steps=5 could allow the agent to call the research
tool 3 times and the compute tool 2 times.
title: AdvancedAgentRunsRequestWorkflowConfig
type_:AdvancedAgentRunsBatchResponseInputItemRole:
type: string
enum:
- user
description: The access based role of the user
title: AdvancedAgentRunsBatchResponseInputItemRole
type_:AdvancedAgentRunsBatchResponseInputItem:
type: object
properties:
role:
$ref: >-
#/components/schemas/type_:AdvancedAgentRunsBatchResponseInputItemRole
description: The access based role of the user
content:
type: string
description: The question populated in the request payload
required:
- role
- content
title: AdvancedAgentRunsBatchResponseInputItem
type_:AdvancedAgentRunsResponseOutputType:
type: string
enum:
- message.answer
- web_search.results
description: >-
The type of output. This can either be:
* `message.answer` for text responses
* `web_search.results` for output that contains web links.
`web_search.results` only appear when you use the `research` tool
title: AdvancedAgentRunsResponseOutputType
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_:AdvancedAgentRunsResponseOutput:
type: object
properties:
text:
type: string
description: >-
The text response of the agent. This field returns when `type ==
message.answer`. The response returns as markdown formatted text.
For an overview of Markdown syntax, see the [Basic Syntax Markdown
Guide](https://www.markdownguide.org/basic-syntax/)
type:
$ref: '#/components/schemas/type_:AdvancedAgentRunsResponseOutputType'
description: >-
The type of output. This can either be:
* `message.answer` for text responses
* `web_search.results` for output that contains web links.
`web_search.results` only appear when you use the `research` tool
content:
type: array
items:
$ref: '#/components/schemas/type_:AgentRunsResponseWebSearchResult'
description: |-
The text response of the agent.
This field returns when `type == web_search.results`
required:
- type
description: The response populated by the agent.
title: AdvancedAgentRunsResponseOutput
type_:AdvancedAgentRunsBatchResponse:
type: object
properties:
agent:
type: string
description: The id of the agent populated in the request.
input:
type: array
items:
$ref: '#/components/schemas/type_:AdvancedAgentRunsBatchResponseInputItem'
description: The users access role and question you asked the agent
output:
type: array
items:
$ref: '#/components/schemas/type_:AdvancedAgentRunsResponseOutput'
description: The agent's response items
required:
- agent
- input
- output
description: The id of the agent populated in the request.
title: AdvancedAgentRunsBatchResponse
type_:AgentRuns401Response:
type: object
properties:
detail:
type: string
description: The message returned by the error
title: AgentRuns401Response
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
```
## SDK Code Examples
```python
# Use our official Python SDK to get an agent response
from youdotcom import You
from youdotcom.models import AdvancedAgentRunsRequest, AgentRunsBatchResponse
with You("api_key") as you:
response = you.agents.runs.create(
request=AdvancedAgentRunsRequest(
input="You are a biologist studying the impacts of microplastics. Explain what microplastics are to a group of engineers, explain the impacts of microplastics on the body, and what the common sources and dosages of microplastics are. Highlight what a safe dosage might be and how to achieve it",
stream=False
)
)
if isinstance(response, AgentRunsBatchResponse) and response.output:
for output in response.output:
if output.text:
print(output.text)
```
```typescript
// Use our official TypeScript SDK to get an agent response
import { You } from "@youdotcom-oss/sdk";
import type { AdvancedAgentRunsRequest } from "@youdotcom-oss/sdk/models";
const you = new You({ apiKeyAuth: "api_key" });
const request: AdvancedAgentRunsRequest = {
agent: "advanced",
stream: false,
input: "You are a biologist studying the impacts of microplastics. Explain what microplastics are to a group of engineers, explain the impacts of microplastics on the body, and what the common sources and dosages of microplastics are. Highlight what a safe dosage might be and how to achieve it",
tools: [{
type: "research",
searchEffort: "low",
reportVerbosity: "medium",
}]
};
const result = await you.agentsRuns(request);
console.log(result);
```
```javascript
// Use our official JavaScript SDK to get an agent response
import { You } from "@youdotcom-oss/sdk";
const you = new You({ apiKeyAuth: "api_key" });
const request = {
agent: "advanced",
stream: false,
input: "You are a biologist studying the impacts of microplastics. Explain what microplastics are to a group of engineers, explain the impacts of microplastics on the body, and what the common sources and dosages of microplastics are. Highlight what a safe dosage might be and how to achieve it",
tools: [{
type: "research",
searchEffort: "low",
reportVerbosity: "medium",
}]
};
const result = await you.agentsRuns(request);
console.log(result);
```
```go
package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.you.com/v1/agents/runs"
payload := strings.NewReader("{\n \"agent\": \"advanced\",\n \"input\": \"You are a biologist studying the impacts of microplastics. Explain what microplastics are to a group of engineers, explain the impacts of microplastics on the body, and what the common sources and dosages of microplastics are. Highlight what a safe dosage might be and how to achieve it\",\n \"stream\": false\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\": \"advanced\",\n \"input\": \"You are a biologist studying the impacts of microplastics. Explain what microplastics are to a group of engineers, explain the impacts of microplastics on the body, and what the common sources and dosages of microplastics are. Highlight what a safe dosage might be and how to achieve it\",\n \"stream\": false\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\": \"advanced\",\n \"input\": \"You are a biologist studying the impacts of microplastics. Explain what microplastics are to a group of engineers, explain the impacts of microplastics on the body, and what the common sources and dosages of microplastics are. Highlight what a safe dosage might be and how to achieve it\",\n \"stream\": false\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```
```swift
import Foundation
let headers = [
"Authorization": "Bearer ",
"Content-Type": "application/json"
]
let parameters = [
"agent": "advanced",
"input": "You are a biologist studying the impacts of microplastics. Explain what microplastics are to a group of engineers, explain the impacts of microplastics on the body, and what the common sources and dosages of microplastics are. Highlight what a safe dosage might be and how to achieve it",
"stream": false
] 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()
```