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 answers the user’s query with an LLM. Optionally, you can ground the answer using web results (max 1 web search).

Use it for answering simple questions that require a low latency response.

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://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-stream
      summary: Advanced Agent
      description: >-
        This endpoint answers the user’s query with an LLM. Optionally, you can
        ground the answer using web results (max 1 web search).


        Use it for answering simple questions that require a low latency
        response.


        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_:AdvancedAgentRunsStreamingResponse'
        '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_:AdvancedAgentRunsStreamRequestAgent
                  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:
                    - true
                  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_:AdvancedAgentRunsStreamRequestToolsItem
                  description: >-
                    The advanced agent accepts either `compute` or `research`
                    tools <Note> Compute allows your agent to use a Python code
                    interpreter for tasks such as data analysis, mathematical
                    calculations, and plot generation.<br><br> 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.</Note>
                verbosity:
                  $ref: >-
                    #/components/schemas/type_:AdvancedAgentRunsStreamRequestVerbosity
                  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_:AdvancedAgentRunsStreamRequestWorkflowConfig
                  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_:AdvancedAgentRunsStreamRequestAgent:
      type: string
      enum:
        - advanced
      description: Setting this value to "advanced" is mandatory to use the advanced agent.
      title: AdvancedAgentRunsStreamRequestAgent
    type_:AdvancedAgentRunsStreamRequestToolsItemResearchSearchEffort:
      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: AdvancedAgentRunsStreamRequestToolsItemResearchSearchEffort
    type_:AdvancedAgentRunsStreamRequestToolsItemResearchReportVerbosity:
      type: string
      enum:
        - medium
        - high
      description: Select whether to receive a medium or high length model response.
      title: AdvancedAgentRunsStreamRequestToolsItemResearchReportVerbosity
    type_:AdvancedAgentRunsStreamRequestToolsItem:
      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_:AdvancedAgentRunsStreamRequestToolsItemResearchSearchEffort
              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_:AdvancedAgentRunsStreamRequestToolsItemResearchReportVerbosity
              description: >-
                Select whether to receive a medium or high length model
                response.
          required:
            - type
            - search_effort
            - report_verbosity
      discriminator:
        propertyName: type
      title: AdvancedAgentRunsStreamRequestToolsItem
    type_:AdvancedAgentRunsStreamRequestVerbosity:
      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: AdvancedAgentRunsStreamRequestVerbosity
    type_:AdvancedAgentRunsStreamRequestWorkflowConfig:
      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: AdvancedAgentRunsStreamRequestWorkflowConfig
    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_:AdvancedAgentRunsStreamingResponse:
      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: AdvancedAgentRunsStreamingResponse
    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 stream the agent response
from youdotcom import You
from youdotcom.models import (
    AdvancedAgentRunsRequest,
    ResponseCreated,
    ResponseStarting,
    ResponseOutputItemAdded,
    ResponseOutputContentFull,
    ResponseOutputTextDelta,
    ResponseOutputItemDone,
    ResponseDone,
)

with You("api_key") as you:
  response = you.agents.runs.create(
    request=AdvancedAgentRunsRequest(
      input="Explain the impacts of microplastics on the human body",
      stream=True
    )
  )

  with response as stream:
      for chunk in stream:
          event = chunk.data

          # Handle each streaming event type
          if isinstance(event, ResponseCreated):
              print(f"Response created (seq: {event.seq_id})")

          elif isinstance(event, ResponseStarting):
              print(f"Response starting (seq: {event.seq_id})")

          elif isinstance(event, ResponseOutputItemAdded):
              print(f"Output item added (seq: {event.seq_id})")

          elif isinstance(event, ResponseOutputContentFull):
              # Full content from tool results (e.g., search results)
              if event.response.full:
                  for result in event.response.full:
                      print(f"  Source: {result.title} - {result.url}")

          elif isinstance(event, ResponseOutputTextDelta):
              # Stream text as it arrives
              print(event.response.delta, end="", flush=True)

          elif isinstance(event, ResponseOutputItemDone):
              print(f"\nOutput complete (index: {event.response.output_index})")

          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 { AdvancedAgentRunsRequest, 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: AdvancedAgentRunsRequest = {
  agent: "advanced",
  stream: true,
  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) as EventStream<AgentRunsStreamingResponse>;

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: "advanced",
  stream: true,
  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);

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\": \"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\": true\n}")

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

	req.Header.Add("Authorization", "Bearer <token>")
	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<String> response = Unirest.post("https://api.you.com/v1/agents/runs")
  .header("Authorization", "Bearer <token>")
  .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\": 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 <token>");
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\": true\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "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": 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()
```