# Agents overview

> Learn about You.com's AI agents - Express for speed, Advanced for deep research, and Custom for specialized workflows. Choose the right agent for your use case.

## What are You.com agents?

You.com Agents are AI-powered assistants that combine real-time web search, reasoning capabilities, and specialized tools to provide comprehensive answers to complex queries. Unlike simple search APIs that return raw results, Agents synthesize information, cite sources, and can deliver structured responses tailored to your needs.

Agents turn search results into actionable answers. We offer 3 kinds: **Express** for fast responses, **Advanced** for in-depth research and **Custom** for domain-specific workflows.

## Agent types

### Express Agent

**Purpose:** Fast, reliable answers with citations optimized for speed and efficiency.

The Express Agent is designed to balance speed and depth. It searches the web, processes results, and delivers a concise answer with relevant citations—typically within 2-3 seconds.

**When to use:**

* Chatbots requiring quick responses
* FAQ answering systems
* Real-time information lookup
* Applications where latency matters

**Example use case:** A customer support bot that answers "What are your business hours?" by searching your website and returning a formatted answer with a link to your hours page.

**Learn more:** [Express Agent API](/api-reference/agents/express-agent/express-agent-runs)

<CodeBlock>
  ```python
  # Utilize our official Python SDK to run an Express agent
  from youdotcom import You
  from youdotcom.types.typesafe_models import (
      AgentType,
      stream_text_tokens
  )

  with You(
      api_key_auth="Your You.com API Key",
  ) as you:
      res = you.agents.runs.create(
          agent=AgentType.EXPRESS,
          input="Teach me how to make an omelet",
          stream=True,
      )

      # A built-in helper to handle streamed responses
      stream_text_tokens(res)
  ```

  ```typescript
  // Utilize our official TypeScript SDK to run an Express agent
  import { You } from "@youdotcom-oss/sdk";
  import type { ExpressAgentRunsRequest, AgentRunsStreamingResponse } from "@youdotcom-oss/sdk/models";
  import { type EventStream } from "@youdotcom-oss/sdk/lib/event-streams.js";

  const you = new You({
    apiKeyAuth: "YOUR_API_KEY",
  });

  async function run() {
    const request: ExpressAgentRunsRequest = {
      agent: "express",
      input: "What is the capital of France?",
      stream: true,
    };

    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);
      } else if (chunk.data.type === "response.done") {
        console.log("\nResponse completed!");
      }
    }
  }

  run();
  ```

  ```curl
  curl -N \
    -X POST https://api.you.com/v1/agents/runs \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Accept: text/event-stream" \
    -H "Content-Type: application/json" \
    -d '{
      "agent": "express",
      "input": "What is the capital of France?",
      "stream": true
    }'
  ```
</CodeBlock>

***

### Advanced Agent

**Purpose:** Deep research with extensive citations and comprehensive analysis.

The Advanced Agent is built for thorough investigations. It uses multiple tools—web search, research capabilities, and compute functions—to gather information, synthesize findings, and produce detailed reports with extensive citations.

**When to use:**

* Market research reports
* Competitive analysis
* Academic research assistance
* Complex technical explanations
* Multi-step reasoning tasks

**Example use case:** A research platform that generates comprehensive reports on emerging technologies, complete with data analysis, trend identification, and cited sources.

**Available tools:**

* **Research Tool:** Deep investigation with source analysis
* **Compute Tool:** Data processing and calculations

**Learn more:** [Advanced Agent API](/api-reference/agents/advanced-agent/advanced-agent-runs-stream)

<CodeBlock>
  ```python
  # Utilize our official Python SDK to run an Advanced agent
  from youdotcom import You
  from youdotcom.models import ComputeTool, ResearchTool
  from youdotcom.types.typesafe_models import (
      AgentType,
      SearchEffort,
      Verbosity,
      stream_text_tokens,
  )

  with You(
      api_key_auth="Your You.com API Key",
  ) as you:
      res = you.agents.runs.create(
              agent=AgentType.ADVANCED,
              input="Analyze the impact of microplastics on marine ecosystems.",
              stream=True,
              tools=[
                  ResearchTool(
                      search_effort=SearchEffort.HIGH,
                      report_verbosity=Verbosity.HIGH,
                  ),
              ]
      )

      # A built-in helper to handle streamed responses
      stream_text_tokens(res)

  ```

  ```typescript
  // Utilize our official TypeScript SDK to run an Advanced agent
  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: "YOUR_API_KEY",
  });

  async function run() {
    const request: AdvancedAgentRunsRequest = {
      agent: "advanced",
      input: "Analyze the impact of microplastics on marine ecosystems.",
      stream: true,
      tools: [
        {
          type: "research",
          searchEffort: "high",
          reportVerbosity: "high",
        },
      ],
    };

    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);
      } else if (chunk.data.type === "response.done") {
        console.log("\nResponse completed!");
      }
    }
  }

  run();
  ```

  ```curl
  curl -N \
    -X POST https://api.you.com/v1/agents/runs \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Accept: text/event-stream" \
    -H "Content-Type: application/json" \
    -d '{
      "agent": "advanced",
      "input": "Analyze the impact of microplastics on marine ecosystems",
      "stream": true,
      "tools": [
        {
          "type": "research",
          "search_effort": "high",
          "report_verbosity": "high"
        }
      ]
    }'
  ```
</CodeBlock>

***

### Custom Agent

**Purpose:** Personalized AI agents with custom instructions and tailored capabilities.

Custom Agents let you define your own system instructions, choose which tools to enable, and configure behavior for specific domains or workflows. Create specialized assistants for legal research, medical information, code review, or any domain where you need consistent, customized responses.

**When to use:**

* Domain-specific applications (legal, medical, financial)
* Branded AI assistants with specific tone/style
* Workflows requiring consistent instructions
* Applications needing tool control (enable/disable search, research, compute)

**Example use case:** A legal research assistant that searches case law, follows specific citation formats, and applies jurisdictional constraints based on your custom instructions.

**Customization options:**

* **Custom Instructions:** Define personality, expertise, output format
* **Model Choice:** Select underlying LLM (subject to availability)
* **Response Style:** Control verbosity, tone, and formatting

<Note>
  To use a Custom Agent via API, you'll need to [create one first](/agents/custom/create-agents).
</Note>

**Learn more:** [Custom Agent API](/api-reference/agents/custom-agent/custom-agent-runs)

<CodeBlock>
  ```python
  # Utilize our official Python SDK to run a Custom agent
  from youdotcom import You
  from youdotcom.types.typesafe_models import stream_text_tokens

  # Initialize the SDK with your API key
  with You(api_key_auth="your-api-key-here") as you:
      # Create a custom agent run and stream the response
      res = you.agents.runs.create(
          # This is a custom agent we've created for you to try
          # Replace it with your own
          agent="63773261-b4de-4d8f-9dfd-cff206a5cb51",
          input="Teach me how to make an omelet",
          stream=True,
      )

      # A built-in helper to handle streamed responses
      stream_text_tokens(res)
  ```

  ```typescript
  // Utilize our official TypeScript SDK to run a Custom agent
  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: "YOUR_API_KEY",
  });

  async function run() {
    const request: CustomAgentRunsRequest = {
      // This is a custom agent we've created for you to try
      // Replace it with your own
      agent: "63773261-b4de-4d8f-9dfd-cff206a5cb51",
      input: "Teach me how to make an omelet",
      stream: true,
    };

    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);
      } else if (chunk.data.type === "response.done") {
        console.log("\nResponse completed!");
      }
    }
  }

  run();
  ```

  ```curl
  curl -N \
    -X POST https://api.you.com/v1/agents/runs \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Accept: text/event-stream" \
    -H "Content-Type: application/json" \
    -d '{
      "agent": "63773261-b4de-4d8f-9dfd-cff206a5cb51",
      "input": "Teach me how to make an omelet",
      "stream": true
    }'
  ```
</CodeBlock>

<Note>
  Custom agents using foundational models with advanced research and reasoning are not currently supported via API. Tools can only be configured via the UI, not through API parameters.
</Note>

***

## Common features across all agents

### Streaming responses

All agents support streaming via Server-Sent Events (SSE), allowing you to process responses incrementally as they're generated. This provides a better user experience with real-time feedback.

**Stream event types:**

* `response.created` - Agent started processing
* `response.starting` - Response generation beginning
* `response.output_item.added` - New output item created
* `response.output_text.delta` - Text chunk available
* `response.output_item.done` - Output item complete
* `response.done` - Full response complete

### Citations & sources

All agents provide citations with their responses, including:

* Source URLs
* Page titles
* Relevant snippets
* Favicon URLs
* Page age/freshness

### Error handling

Agents return standard HTTP error codes and structured error responses. See [Error Reference](/api-reference/errors) for details.

***

## Choosing the right Agent

<CardGroup cols={3}>
  <Card title="Need speed?" icon="fa-regular fa-bolt" href="/api-reference/agents/express-agent/express-agent-runs">
    **Use Express Agent**

    Fast answers in 2-3 seconds with reliable citations. Perfect for chatbots and real-time applications.
  </Card>

  <Card title="Need depth?" icon="fa-regular fa-microscope" href="/api-reference/agents/advanced-agent/advanced-agent-runs">
    **Use Advanced Agent**

    Comprehensive research with extensive citations. Ideal for reports and analysis.
  </Card>

  <Card title="Need control?" icon="fa-regular fa-sliders" href="/api-reference/agents/custom-agent/custom-agent-runs">
    **Use Custom Agent**

    Full customization with your own instructions and tool selection. Best for domain-specific tasks.
  </Card>
</CardGroup>

| Feature           | Express                      | Advanced                    | Custom                              |
| ----------------- | ---------------------------- | --------------------------- | ----------------------------------- |
| **Best for**      | Quick answers with citations | Deep research & analysis    | Specialized tasks with custom logic |
| **Speed**         | \~2-3 seconds                | \~30-60 seconds             | Varies by configuration             |
| **Tool use**      | Web search                   | Research tool, Compute tool | On creation                         |
| **Streaming**     | ✅ Yes                        | ✅ Yes                       | ✅ Yes                               |
| **Customization** | None                         | Tool use                    | Full (instructions, tools, model)   |
| **Use cases**     | FAQ bots, quick Q\&A         | Report generation, analysis | Industry-specific assistants        |
| **Cost**          | \$                           | \$\$\$                      | \$\$                                |

***

## Pricing & rate limits

Agent pricing varies by type and usage. Express agents are optimized for cost-efficiency, while Advanced agents consume more resources due to their comprehensive research capabilities. Custom agents fall in between.

For detailed pricing information and rate limits, visit [you.com/pricing](https://you.com/pricing) or contact [api@you.com](mailto:api@you.com).

***

## Next steps

<CardGroup cols={2}>
  <Card title="Quickstart guide" icon="fa-regular fa-play" href="/get-started/quickstart">
    Get your API key and make your first call in minutes
  </Card>

  <Card title="API reference" icon="fa-regular fa-code" href="/api-reference/agents/express-agent/express-agent-runs">
    Explore detailed endpoint documentation
  </Card>

  <Card title="Python SDK" icon="fa-brands fa-python" href="/developer-resources/python-sdk">
    Use our Python SDK for easier integration
  </Card>
</CardGroup>