--- title: "Run an Agent" method: POST path: "/v1/agents/runs" --- # Run an Agent `POST /v1/agents/runs` Execute queries using You.com's AI agents. This endpoint supports three agent types: - **Express Agent**: Fast responses with optional web search (max 1 search) - **Advanced Agent**: Complex queries with multi-turn reasoning, planning, and tool usage - **Custom Agent**: User-configured assistants created in the You.com UI The response format depends on the `stream` parameter - either a complete JSON payload or Server-Sent Events (SSE). ## Request body - union - ExpressAgentRunsRequest - `agent` 'express', required — Setting this value to "express" is mandatory to use the express agent. - `input` string, required — The question you'd like to ask the agent - `stream` boolean — Must be set to `true` when you want to stream the express agent response as it's being generated, and `false` when you want the response to return after the agent has finished. - `tools` WebSearchTool[] — You can optionally ground the express agent response using results fetched from the web (max 1 web search) - `type` 'web_search', required — Setting this value to "web_search" is mandatory to use the web_search tool. - AdvancedAgentRunsRequest - `agent` 'advanced', required — Setting this value to "advanced" is mandatory to use the advanced agent. - `input` string, required — The question you'd like to ask the agent - `stream` boolean — Must be set to `true` when you want to stream the agent response as it's being generated, and `false` when you want the response to return after the agent has finished. - `tools` union[] — 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. - union - ComputeTool - `type` 'compute', required — Setting this value to "compute" is mandatory to use the compute agent. - ResearchTool - `type` 'research', required — Setting this value to "research" is mandatory to use the research agent. - `search_effort` 'auto' | 'low' | 'medium' | 'high', required — 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` 'medium' | 'high', required — Select whether to receive a medium or high length model response. - `verbosity` 'medium' | 'high' — 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` object — 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. - `max_workflow_steps` integer, required - CustomAgentRunsRequest - `agent` string, required — Set the value to a Custom Agent's ID. Learn how to obtain an agent ID here [Create Custom Agents](https://docs.you.com/agents/custom/create-agents). - `input` string, required — The question you'd like to ask the agent - `stream` boolean — Must be set to `true` when you want to stream the agent response as it's being generated, and `false` when you want the response to return after the agent has finished. ## Response `200` Successful agent response. The content type depends on the `stream` parameter: - When `stream: false` - Returns complete JSON response (`application/json`) - When `stream: true` - Returns Server-Sent Events stream (`text/event-stream`) - AgentRunsBatchResponse - `agent` string, required — The id of the agent populated in the request. - `mode` string — The mode of the agent - `input` object[], required — The users access role and question you asked the agent - `role` 'user', required — The access based role of the user - `content` string, required — The question populated in the request payload - `output` AgentRunsResponseOutput[], required — Array of response outputs from the agent - `text` string — 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` 'message.answer' | 'web_search.results', required — 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 or express agent with web_search - `content` AgentRunsResponseWebSearchResult[] — The text response of the agent. This field returns when `type == web_search.results` - `source_type` 'web_search', required — The type of content the agent can return outside a text response - `citation_uri` string, required — The web search result the agent returned along in its response - `provider` string — This is currently unused - `title` string, required — The title of the web site returned under url - `snippet` string, required — A textual portion of the web site returned under url - `thumbnail_url` string — The thumbnail image of the url - `url` string, required — The web search result the agent returned along in its response ## Other responses - `400` — The Authorization Bearer token was missing or invalid - `401` — Unauthorized - Invalid or expired API key - `422` — Unprocessable Entity - Invalid request data --- [API](https://skmtc.dev/you/apis/you-com-agents-api.md) · [All operations](https://skmtc.dev/you/apis/you-com-agents-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/you/you-com-agents-api/revisions/77c27a4b50c1/schema)