Skip to main content
TwelveLabsTools enable an Agent to understand and search video using TwelveLabs. The toolkit exposes two capabilities: analyze_video, which answers a natural-language question about a video using the Pegasus video understanding model, and embed_text, which generates a multimodal embedding with the Marengo model that lives in the same latent space as TwelveLabs video, audio and image embeddings (useful for searching a video corpus by text).

​
Prerequisites

You need to install the twelvelabs library and an API key which can be obtained from the TwelveLabs dashboard. 
uv pip install twelvelabs
Set the TWELVELABS_API_KEY environment variable. 
export TWELVELABS_API_KEY=****

​
Example

The following agent will use TwelveLabs to answer a question about a video and to generate a text embedding.
cookbook/91_tools/twelvelabs_tools.py
from agno.agent import Agent
from agno.tools.twelvelabs import TwelveLabsTools

# Example 1: Enable all tools
agent = Agent(
    tools=[TwelveLabsTools(all=True)],
    markdown=True,
)

agent.print_response(
    "What is happening in this video? https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4",
)

# Example 2: Enable only text embedding (useful for embedding search queries
# against a TwelveLabs video index)
embedding_agent = Agent(
    tools=[
        TwelveLabsTools(
            enable_analyze_video=False,
            enable_embed_text=True,
        )
    ],
    markdown=True,
)

embedding_agent.print_response(
    "Embed the text 'a cat playing piano' and tell me how many dimensions it has."
)

​
Toolkit Params

ParameterTypeDefaultDescription
api_keyOptional[str]NoneThe TwelveLabs API key. Read from the TWELVELABS_API_KEY environment variable if not provided.
analyze_modelstrpegasus1.5The Pegasus model used for analyze_video.
embed_modelstrmarengo3.0The Marengo model used for embed_text.
max_tokensint2048Maximum number of tokens for analyze_video responses.
enable_analyze_videoboolTrueEnable the analyze_video functionality.
enable_embed_textboolTrueEnable the embed_text functionality.
allboolFalseEnable all functionality.

​
Toolkit Functions

FunctionDescription
analyze_videoAnalyze a video and answer a natural-language question about it using the Pegasus model.
embed_textGenerate a multimodal (Marengo) embedding for a piece of text, which can be used to search a video corpus by text.

​
Developer Resources