# 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.

<Info>The call only returns when the agent has finished fully responding to the input question.</Info>

Reference: https://docs.you.com/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.


        <Info>The call only returns when the agent has finished fully responding
        to the input question.</Info>
      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:
                  type: string
                  enum:
                    - advanced
                  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 <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_: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_: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 <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\": 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 <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\": false\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": 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()
```