# 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](https://docs.clarifai.com/compute/inference/#predict-with-openai-compatible-format), 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:

- [OpenAI](https://docs.clarifai.com/compute/agents/build/#openai)
- [Google ADK](https://docs.clarifai.com/compute/agents/build/#google-adk)
- [CrewAI](https://docs.clarifai.com/compute/agents/build/#crewai)
- [Vercel](https://docs.clarifai.com/compute/agents/build/#vercel)
- [Agno](https://docs.clarifai.com/compute/agents/build/#agno)

## LiteLLM

[LiteLLM](https://docs.litellm.ai/docs/providers/clarifai) 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](https://docs.clarifai.com/control/authentication/pat)** 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](https://openai.github.io/openai-agents-python/) 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.

```bash
pip install "openai-agents[litellm]"
```

After the installation, you can use the [LitellmModel](https://openai.github.io/openai-agents-python/models/litellm/) 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:

- `instructions` — Also known as the system prompt or developer message, this defines the agent’s behavior and tone.
- `model` — Specifies which LLM to use. In this case, it points to a Clarifai-hosted model.
- `tools` — Define the actions your agent can take, such as calling APIs or fetching data. These can be implemented as regular Python functions.

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.

```python
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

```text
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)](https://google.github.io/adk-docs/) to build agentic AI apps that make use of Clarifai models.

### Installation

Install the following necessary packages:

- `google-adk` — This is the Google ADK itself, which provides a wide range of components, such as `Agent`, `Runner`, `LiteLlm`, and `InMemorySessionService`.
- `litellm` — The ADK's `LiteLlm` model class relies on the `litellm` library under the hood to handle multi-model support. After the installation, you can use the `LiteLlm` class to access Clarifai models via LiteLLM.
- `google-generativeai` — The ADK uses it for handling `types`; that is, structuring message inputs and outputs.

This is the combined commands for installing them:

```bash
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:

- `instruction` — Also known as the system prompt or developer message, this defines the agent’s behavior and tone.
- `model` — Specifies which LLM to use. In this case, it points to a Clarifai-hosted model.
- `tools` — Define the actions your agent can take, such as calling APIs or fetching data. These can be implemented as regular Python functions.

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.

```python
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

```text
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:

- [Repository for Clarifai-Powered Google ADK Agents](https://github.com/Clarifai/examples/tree/main/agents/Google-ADK)

## CrewAI

You can use [CrewAI](https://docs.crewai.com/introduction) 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.

```bash
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](https://docs.crewai.com/learn/llm-connections). 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:

- `Crew` — The top-level organization that orchestrates how agents work together and manages the overall workflow and process.
- `AI Agents`— These are specialized team members, each with distinct personalities and expertise. An AI agent can:
  - Have a specific `role` (like _"Senior Research Analyst"_).
  - Work towards defined a `goal` (like _"Uncover cutting-edge developments and facts on a given topic"_).
  - Have a `backstory` that shapes its approach and personality.
  - Use designated `tools` to accomplish its work.
  - Delegate tasks.
  - Specify which `llm` to use. In this case, it points to a Clarifai-hosted model.
- `Process` — The workflow management system that defines how agents collaborate. For example, the `sequential` process ensures agents work one after another.
- `Tasks`— The individual assignments that drive the work forward. Each task can:
  - Have a clear `description` of what needs to be done.
  - Define `expected_output` format and content.
  - Be assigned to a specific `agent`.
  - Feed into the larger process.

### 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.

```python
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

```text
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:

- [YouTube Video: Building an AI Blog Writing Agent With Clarifai and CrewAI](https://www.youtube.com/watch?v=1XZT2wD4UzQ&t=25s)
- [Blog Post: Build an AI Agent From Scratch With CrewAI and Clarifai](/content/blog/build-an-ai-agent-from-scratch-with-crewai-and-clarifai/index.html)
- [Repository for Clarifai-Powered CrewAI Agents](https://github.com/Clarifai/examples/tree/main/agents/CrewAI)

## Vercel

You can use the [Vercel](https://vercel.com/docs/agents) platform to build agentic AI apps that make use of Clarifai models. Using the [Vercel AI SDK](https://ai-sdk.dev/) — 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:

- `ai` — This is the Vercel AI SDK, the main library.
- `@ai-sdk/openai-compatible`— The [OpenAI Compatible Provider](https://ai-sdk.dev/providers/openai-compatible-providers) package for the AI SDK, which allows you to connect to OpenAI-compatible APIs (like Clarifai's).
- `zod`— For schema validation of tool parameters.

This is the combined commands for installing them:

```bash
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:

- `model` — Specifies which LLM to use. In this case, it points to a Clarifai-hosted model.
- `maxSteps` — Sets the maximum number of reasoning or tool-use steps the agent can take before halting.
- `tools` — Provides the agent with a set of callable tools. Tools are defined using the `tool` function, which requires a description, a parameter schema (using `zod`), and an `execute` function that defines the tool's behavior.
- `prompt` — The user's input or query that the agent will respond to.

### 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.

```typescript
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

```text
tool-result
```

## Agno

You can use [Agno](https://docs.clarifai.com/compute/agents/build/#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:

- `agno` — The Agno framework itself, which provides components such as `Agent`, `Team`, and `OpenAILike`.
- `openai` — The OpenAI client library used for the OpenAI-compatible connection to Clarifai.
- `ddgs` — Provides the `DuckDuckGoTools` integration for web search capabilities.
- `yfinance` — Provides the `YFinanceTools` integration for financial data lookups.

This is the combined command for installing them:

```bash
pip install agno openai ddgs yfinance
```

### Build an Agent

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

- `model` — Specifies which LLM to use via the `OpenAILike` class, pointing to a Clarifai-hosted model. Set `api_key` to your `CLARIFAI_PAT` and `base_url` to Clarifai's OpenAI-compatible endpoint.
- `tools` — Define the actions your agent can take, such as web search or financial data lookups. Agno provides ready-made tool integrations (e.g., `DuckDuckGoTools`, `YFinanceTools`).
- `description` — A short description that shapes the agent's persona and behavior.
- `markdown` — When set to `True`, the agent formats its responses in Markdown.

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.

```python
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

```text
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:
- [Blog: Building AI Agents with Agno and GPT-OSS 120B](/content/blog/building-ai-agents-with-agno-and-gpt-oss-120b/index.html)
- [Repository for Clarifai-Powered Agno Agents](https://github.com/Clarifai/examples/tree/main/agents/Agno)

## Additional Examples

To learn more about building AI agents with other toolkits, see the following examples:
- [YouTube Video: Building an AI Blog Writing Agent With Clarifai and CrewAI](https://www.youtube.com/watch?v=1XZT2wD4UzQ&t=25s)
- [Blog Post: Build an AI Agent From Scratch With CrewAI and Clarifai](/content/blog/build-an-ai-agent-from-scratch-with-crewai-and-clarifai/index.html)
- [Repository for Clarifai-Powered CrewAI Agents](https://github.com/Clarifai/examples/tree/main/agents/CrewAI)

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

[Get started for free](/content/explore/index.html)