> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.twelvelabs.io/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.twelvelabs.io/_mcp/server. # Migrate from Models > Compare Agents with Models and move your workflows. TwelveLabs offers two ways to work with your videos and images, both built on the same ingestion flow. * **Models**: Dedicated APIs for individual tasks. Search for moments across your videos, analyze a video, or generate embeddings, then combine the results yourself. * **Agents**: [Jockey](/v1.3/agents/concepts/jockey), a unified agentic system that reasons across your videos and images. Ask a question, and Jockey plans its own steps, runs them, and returns a grounded, cited answer. * **Use both together**: Combine Models for embeddings and per-video analysis with Jockey for corpus-level reasoning. This guide compares the two, helps you evaluate which workflows to migrate, and walks through a search workflow migration step by step. # Key differences The following table highlights the key differences between Models and Agents. | Models | Agents | Difference | | -------------------------------------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Index | Knowledge store | A knowledge store contains your videos and images plus derived understanding - entities, relationships, and embeddings - not just a vector index. | | Indexed video | Knowledge store item | An item is a video or image in a knowledge store. The same content can be reused across multiple knowledge stores. | | Marengo / Pegasus | [Jockey](/v1.3/agents/concepts/jockey) | You no longer choose a model. Jockey plans and runs the necessary steps across all modalities itself. | | `POST /search` | `POST /knowledge-stores/{id}/search` or `POST /responses` | Knowledge store search returns ranked matches directly; the Responses API adds agentic reasoning and explanations. Both take natural language. | | Search options (for example, `visual` and `audio`) | Automatic with Jockey; optional on search | The Responses API needs no modality configuration; Jockey selects the modalities itself. Knowledge store search accepts the `search_options` parameter and matches on visual content by default. | | `POST /embed` | No equivalent | Continue using the Embed API for vector embeddings. | # Detailed comparison by task The following table shows which tasks each API supports. | Task | Models | Agents | | ---------------------------- | ------------- | ----------------------------------------------------------------- | | Search for moments in videos | ✅ Search API | ✅ Knowledge store search (or Responses API for agentic search) | | Summarize a single video | ✅ Analyze API | ✅ Responses API (target one item with the `selections` parameter) | | Organize videos by topic | ❌ | ✅ Responses API with structured output | | Track entities across videos | ❌ | ✅ Responses API | | Build agent workflows | ❌ | ✅ Multi-turn sessions + structured output | | Generate vector embeddings | ✅ Embed API | ❌ | Agents return text, data references, and timestamps, not processed video. Use these references in your own rendering pipeline. When you scope a request to specific items with the `selections` parameter, Jockey treats them as a strong preference, not a hard boundary. It can still draw on other items in the knowledge store. For strict single-video analysis, keep the Analyze API. # Choose the workflows to migrate Some workflows can move to Agents. Others should stay on the existing Models APIs. | Current workflow | Recommendation | Reason | | ------------------------------------------------------ | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Search for moments in videos** | Use knowledge store search for a direct match, or the Responses API for agentic search. | Knowledge store search returns ranked matches directly. The Responses API adds cross-video reasoning, multi-turn refinement, and structured output. | | **Analyze a single video** for summaries or Q\&A | Keep the Analyze API, or use the Responses API with the `selections` parameter. | The Analyze API handles stateless, single-video analysis. Targeting one item with the `selections` parameter in the Responses API adds reasoning, multi-turn refinement, and structured output. | | **Generate embeddings** for machine-learning pipelines | Keep using the Embed API. | Agents do not generate vector embeddings. | TwelveLabs recommends you start with a pilot. Upload a subset of your existing content to a pilot knowledge store. Compare results side by side before migrating production workflows. # Migrate a search workflow This example shows how to move a search workflow from Models to Agents. Both approaches start by uploading a video as an asset. The differences begin after upload. | Step | Models | Agents | | ------------------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------- | | **1. Upload an asset** | Upload a video file or URL | Same | | **2. Create a container** | Create an index with model and modality configuration | Create a knowledge store (no model configuration needed) | | **3. Add the asset** | Add to index, poll until indexed | Add to knowledge store, poll until indexed | | **4. Query** | `POST /search` with structured parameters | `POST /responses` (agentic) or `POST /knowledge-stores/{id}/search`, both with natural language | **What you gain**: * **No model selection**: Jockey processes all modalities automatically * **Natural language queries**: describe what you want instead of specifying search options * **Follow-up queries**: refine results in a multi-turn session * **Corpus-level reasoning**: generate responses that reason across your entire video and image collection * **Structured output**: retrieve typed JSON responses using a schema For a working code example of the Agents workflow, see the [Quickstart](/v1.3/agents/get-started/quickstart/create-a-response). > **Research preview limitations** > > During the research preview period: > > * Webhooks are not available. Use polling to check processing status > * Rate limits may differ from Models > * The API surface may change before general availability > * SLAs do not apply > > Models continue to operate. Adopt Agents at your own pace. # Next steps * [Guides](/v1.3/agents/guides) - set up content, configure ingestion, and generate responses * [Recipes](/v1.3/agents/recipes) - common tasks you can adapt to your use case