Build Agents | Clarifai Docs

Learn how to build agents with Clarifai

Clarifai provides a streamlined developer experience that allows you to quickly prototype, build, and deploy agentic AI applications.

We provide an OpenAI-compatible API endpoint, which allows you to seamlessly integrate with popular agent development toolkits that support the OpenAI's API standard. This empowers you to create powerful, flexible, and tool-using AI agents with minimal configuration.

Let’s illustrate how you can build agents with the various toolkits we support:

LiteLLM

LiteLLM is a library that offers a unified API for working with various LLM providers. When using an agent toolkit that supports LiteLLM to access Clarifai's models, specify the model using the openai/ prefix followed by the Clarifai model URL — for example: openai/deepseek-ai/deepseek-chat/models/DeepSeek-R1-Distill-Qwen-7B.

Install Clarifai Package

Install the latest version of the Clarifai Python SDK package by running pip install --upgrade clarifai. Also, go to the Secrets section in your personal settings page and generate a Personal Access Token (PAT) to authenticate with the Clarifai platform.

OpenAI

You can use the OpenAI Agents SDK to build agentic AI apps that make use of Clarifai models.

Installation

The following command will install the openai-agents package and the optional litellm dependency group.

pip install "openai-agents[litellm]"

After the installation, you can use the LitellmModel class in the OpenAI Agents SDK to access Clarifai models via LiteLLM.

Build an Agent

When building an agent with the OpenAI Agents SDK, the most common properties you'll configure are:

You'll also need the Runner class to run your agent.

Example

Here is an example of an AI agent powered by a Clarifai-hosted model and equipped with a simple weather lookup tool. When asked about the weather, the agent will recognize the need to use its tool, get the information, and then summarize it in the form of a haiku.

import os
import asyncio
from agents import Agent, Runner, function_tool
from agents.extensions.models.litellm_model import LitellmModel

# Define the Clarifai-hosted LLM using the OpenAI-compatible API
clarifai_model = LitellmModel(
    model="openai/deepseek-ai/deepseek-chat/models/DeepSeek-R1-Distill-Qwen-7B",
    base_url="https://api.clarifai.com/v2/ext/openai/v1",
    api_key=os.environ["CLARIFAI_PAT"]  # Ensure CLARIFAI_PAT is set as an environment variable
)

# Define a tool the agent can use
@function_tool
def get_weather(city: str):
    print(f"[debug] getting weather for {city}")
    return f"The weather in {city} is sunny."

# Define the AI agent
agent = Agent(
    name="Assistant",
    instructions="You only respond in haikus.",
    model=clarifai_model,
    tools=[get_weather],
)

# Run the agent with an example prompt
async def run_agent():
    result = await Runner.run(agent, "What's the weather in Tokyo?")
    print(result.final_output)

if __name__ == "__main__":
    asyncio.run(run_agent())

Example Output

Okay, so the user asked, "What's the weather in Tokyo?" and I responded with a haiku about the weather in Tokyo on February 23, 2024. The haiku goes:

"Sky gray, wind sharp,
Clouds low, rain starts.
Shinshu meadows dry."

Google ADK

You can use the Google Agent Development Kit (ADK) to build agentic AI apps that make use of Clarifai models.

Installation

Install the following necessary packages:

This is the combined commands for installing them:

pip install google-adk litellm google-generativeai

Build an Agent

When building an agent with the Google ADK, the most common properties you'll configure are:

You'll also need the Runner class to run your agent.

Example

Here is an example of an interactive AI agent that is designed to act as a helpful weather assistant, leveraging a Clarifai-hosted LLM and a custom tool to fetch weather information.

import os
import asyncio
from google.adk.agents import Agent
from google.adk.models.lite_llm import LiteLlm
from google.adk.runners import Runner
from google.adk.sessions import InMemorySessionService
from google.genai import types

# Initialize Clarifai-hosted model using LiteLlm
clarifai_model = LiteLlm(
    model="openai/deepseek-ai/deepseek-chat/models/DeepSeek-R1-Distill-Qwen-7B",
    base_url="https://api.clarifai.com/v2/ext/openai/v1",
    api_key=os.environ["CLARIFAI_PAT"]  # Ensure this environment variable is set
)

def get_weather(city: str) -> dict:
    """
    Mock tool that retrieves weather data for a city.
    """
    print(f"[Tool] get_weather called for: {city}")
    city_key = city.lower().replace(" ", "")

mock_data = {
        "newyork": {"status": "success", "report": "Sunny, 25°C in New York."},
        "london": {"status": "success", "report": "Cloudy, 15°C in London."},
        "tokyo": {"status": "success", "report": "Light rain, 18°C in Tokyo."},
    }

return mock_data.get(city_key, {
        "status": "error",
        "error_message": f"No weather data available for '{city}'."
    })

# Define the agent
agent = Agent(
    name="WeatherAssistant",
    description="Provides weather updates using Clarifai-hosted LLM and custom tools.",
    instruction="You are a helpful weather assistant. Use the `get_weather` tool to fetch city weather. "
                "Return detailed weather reports when available, or clear error messages if not.",
    model=clarifai_model,
    tools=[get_weather],
)

async def main():
    """
    Runs an interactive loop with the weather agent in the terminal.
    """
    app_name = "weather_agent_gpt"
    session_service = InMemorySessionService()

await session_service.create_session(
        app_name=app_name,
        user_id="terminal_user",
        session_id="default_session"
    )

runner = Runner(
        agent=agent,
        app_name=app_name,
        session_service=session_service
    )

print("Ask about the weather (e.g., 'What's the weather in Tokyo?') or type 'exit' to quit.")

while True:
        user_input = input("You: ")
        if user_input.strip().lower() == "exit":
            break

response_events = runner.run(
            user_id="terminal_user",
            session_id="default_session",
            new_message=types.Content(role="user", parts=[types.Part(text=user_input)])
        )

final_response = next(
            (
                event.content.parts[0].text
                for event in response_events
                if event.is_final_response() and event.content and event.content.parts
            ),
            "No response from agent."
        )

print(f"Agent: {final_response}")

if __name__ == "__main__":
    asyncio.run(main())

Example Output

Ask about the weather (e.g., 'What's the weather in Tokyo?') or type 'exit' to quit.
You: What's the weather in Tokyo?
Agent: Okay, so I just got the query asking for the weather in Tokyo. Hmm, I need to figure out how to respond. First, I should check if the get_weather tool is available and if it can fetch the information. I remember that the user mentioned using the get_weather tool, so I should rely on that.

Alright, I'll use the get_weather function with 'Tokyo' as the city parameter. The function should return a detailed weather report if possible. Let me simulate that call. I think the API returns a JSON object with temperature, condition, humidity, wind speed, and feels like temperature. I'll structure that information into a readable format.

I should make sure the response is clear and concise. Maybe start with the temperature and condition, then add humidity, wind speed, and the feels like temperature. That way, the user gets all the necessary details without overwhelming them.

Additional Examples

To learn more about building AI agents with the Google ADK, see the following examples:

CrewAI

You can use CrewAI to build agentic AI apps that make use of Clarifai models. CrewAI is a Python framework that empowers developers to create autonomous AI agents tailored to a wide range of use cases.

Installation

The following command will install the core CrewAI package.

pip install crewai

The crewai package provides a wide range of components for interacting with the CrewAI ecosystem, such as Agent, Task, Crew, Process, and LLM.

CrewAI uses LiteLLM to integrate with a wide range of LLMs. With the LLM class, you can easily connect to any OpenAI-compatible model, including those hosted by providers like Clarifai.

Build an Agent

When building an agent with CrewAI, the most common properties you'll configure are:

Example

Here is an example of a specialized AI agent powered by a Clarifai-hosted model. When you provide a topic, the agent performs a detailed analysis and then generates responses.

import os
from crewai import Agent, Task, Crew, Process, LLM

# Configure Clarifai LLM
clarifai_llm = LLM(
    model="openai/deepseek-ai/deepseek-chat/models/DeepSeek-R1-Distill-Qwen-7B",
    base_url="https://api.clarifai.com/v2/ext/openai/v1",
    api_key=os.environ["CLARIFAI_PAT"]  # Ensure this environment variable is set
)

# Define the Researcher Agent
researcher = Agent(
    role="Senior Research Analyst",
    goal="Uncover cutting-edge developments and facts on a given topic",
    backstory="""You are a meticulous and insightful research analyst at a tech think tank.
    You specialize in identifying trends, gathering verified information,
    and presenting concise insights.""",
    verbose=True, # Set to False to disable verbose output
    allow_delegation=False,
    llm=clarifai_llm
)

def create_research_task(topic):
    return Task(
        description=f"""Conduct a comprehensive analysis of '{topic}'.
        Identify key trends, breakthrough technologies, important figures, and potential industry impacts.
        Focus on factual and verifiable information.""",
        expected_output="A detailed analysis report in bullet points, including sources if possible.",
        agent=researcher
    )

def run_research(topic):
    task = create_research_task(topic)

crew = Crew(
        agents=[researcher],
        tasks=[task],
        process=Process.sequential,
        verbose=True
    )

return crew.kickoff() # Starts the execution of the crew

if __name__ == "__main__":
    topic = input("Enter the topic to research: ").strip()
    if topic:
        print(f"\n Researching '{topic}'...\n")
        result = run_research(topic)
        print("\n Research Completed:\n")
        print(result)
    else:
        print("No topic entered.")

Example Output

Enter the topic to research: Artificial Intelligence

Researching 'Artificial Intelligence'...

# Agent: Senior Research Analyst
## Task: Conduct a comprehensive analysis of 'Artificial Intelligence'.
        Identify key trends, breakthrough technologies, important figures, and potential industry impacts.
        Focus on factual and verifiable information.

# Agent: Senior Research Analyst
## Final Answer:
Okay, so I need to conduct a comprehensive analysis of Artificial Intelligence. I'm a bit new to this topic, so I'll start by breaking it down into the areas I need to cover: key trends, breakthrough technologies, important figures, and industry impacts. I'll also need to make sure I use factual and verifiable information. Let me think through each part step by step.

First, key trends in AI. I know AI is becoming more integrated into everyday life, right? Like in healthcare, self-driving cars, and maybe even in how we interact with technology daily. I remember hearing about AI being used in customer service and virtual assistants like Siri or Alexa. That sounds like a trend. Also, I think the term "AI for Good" is a big deal these days. It focuses on using AI to solve global issues like climate change or public health. That must be a trend pushing AI into more ethical and beneficial applications.

Then, there's the rise of AI in entertainment. I've seen movies where AI creates characters, but I'm not sure how real that is. Maybe it's more about AI being used to analyze audience preferences or recommend content. That could be a trend, but I'm not entirely certain if it's a significant one yet.

Additional Examples

To learn more about building AI agents with CrewAI, see the following examples:

Vercel

You can use the Vercel platform to build agentic AI apps that make use of Clarifai models. Using the Vercel AI SDK — a TypeScript toolkit for working with OpenAI-compatible APIs — you can easily connect to and interact with Clarifai's hosted AI models.

Installation

You can install the following necessary packages:

This is the combined commands for installing them:

npm install ai @ai-sdk/openai-compatible zod

Build an Agent

When building an agent with the Vercel AI SDK, the core function you can use to interact with the language model is generateText. It serves as the main entry point for generating responses and orchestrating tool use.

The most common properties you'll configure in a generateText call are:

Example

Here is an example that demonstrates how to build an agent using the Vercel AI SDK that interacts with a Clarifai-hosted language model.

import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
import { generateText, tool } from "ai";
import { z } from "zod";

const clarifai = createOpenAICompatible({
  baseURL: "https://api.clarifai.com/v2/ext/openai/v1",
  apiKey: process.env.CLARIFAI_PAT,
});

const model = clarifai(
  "https://clarifai.com/anthropic/completion/models/claude-sonnet-4",
);

const result = await generateText({
  model,
  maxSteps: 2,
  tools: {
    weather: tool({
      description: "Get the weather in a location",
      parameters: z.object({
        location: z.string().describe("The location to get the weather for"),
      }),
      execute: async ({ location }) => ({
        location,
        temperature: 72 + Math.floor(Math.random() * 21) - 10,
      }),
    }),
    activities: tool({
      description: 'Get the activities in a location',
      parameters: z.object({
        location: z.string().describe('The location to get the activities for'),
      }),
      execute: async ({ location }) => ({
        location,
        activities: ['hiking', 'swimming', 'sightseeing'],
      }),
    }),
    cityAttractions: tool({
      parameters: z.object({ city: z.string() }),
    }),
  },
  prompt:
    "What is the weather in San Francisco and what attractions should I visit?",
});

console.log(result.toolResults);

Example Output

tool-result

Agno

You can use Agno to build agentic AI apps that make use of Clarifai models. Agno is a framework for building AI agents that can use tools, maintain memory, and work in teams.

Installation

You can install the following necessary packages:

This is the combined command for installing them:

pip install agno openai ddgs yfinance

Build an Agent

When building an agent with Agno, the most common properties you'll configure are:

You can also compose multiple agents into a Team to tackle complex, multi-step tasks collaboratively.

Examples

Simple Agent

Here is an example of a simple AI assistant powered by a Clarifai-hosted model. When asked a question, the agent generates a direct response without using any external tools.

import os
from agno.agent import Agent
from agno.models.openai.like import OpenAILike

agent = Agent(
    model=OpenAILike(
        id="openai/chat-completion/models/gpt-oss-120b",
        api_key=os.environ["CLARIFAI_PAT"],
        base_url="https://api.clarifai.com/v2/ext/openai/v1",
        max_tokens=4096
    ),
    description="AI assistant powered by Clarifai",
    markdown=True
)

agent.print_response("What are the key trends in AI for 2026?", stream=True)

Example Output

Here are the key AI trends shaping 2026:

1. Agentic AI – Autonomous agents that plan, use tools, and complete multi-step tasks with minimal human oversight are moving from research into production.
2. Multimodal Models – Leading models now process text, images, audio, and video in a single unified architecture, enabling richer applications.
3. On-Device Inference – Smaller, quantized models are running directly on consumer hardware, reducing latency and improving data privacy.
4. Reasoning Models – Models trained with chain-of-thought and reinforcement learning demonstrate stronger logical reasoning and problem-solving across domains.
5. AI Infrastructure Consolidation – Cloud providers and specialized platforms are offering tighter integration between model hosting, fine-tuning, and deployment pipelines.

Additional Examples

To learn more about building AI agents with Agno, see the following examples:

Additional Examples

To learn more about building AI agents with other toolkits, see the following examples:

Build your next AI app, test and tune popular LLMs models, and much more.

Get started for free