Getting Started

Get up and running with Cogent in minutes.

---

Installation

Note: The package is published as cogent-ai on PyPI, but you import it as cogent in your code.

From PyPI

# uv (recommended)
uv add cogent-ai

# pip
pip install cogent-ai

With extras

# uv
uv add "cogent-ai[vector-stores]"
uv add "cogent-ai[retrieval]"
uv add "cogent-ai[all-providers]"
uv add "cogent-ai[all]"

# pip
pip install "cogent-ai[vector-stores]"
pip install "cogent-ai[all]"

From GitHub (latest unreleased)

# uv
uv add git+https://github.com/milad-o/cogent.git

# pip
pip install git+https://github.com/milad-o/cogent.git

# With extras from git
uv add "cogent-ai[all] @ git+https://github.com/milad-o/cogent.git"
pip install "cogent-ai[all] @ git+https://github.com/milad-o/cogent.git"

# Specific branch or tag
uv add "git+https://github.com/milad-o/cogent.git@main"
pip install "git+https://github.com/milad-o/cogent.git@v1.19.2"

From source (development)

git clone https://github.com/milad-o/cogent.git
cd cogent
uv sync                            # core only
uv sync --group dev --group test   # with dev + test tools

Optional dependency groups

Group	Purpose	Includes
vector-stores	Vector databases	FAISS, Qdrant, SciPy
retrieval	Retrieval libraries	BM25, sentence-transformers
database	SQL databases	SQLAlchemy, aiosqlite, asyncpg, psycopg2
infrastructure	Infrastructure	Redis
web	Web tools	BeautifulSoup4, DuckDuckGo search
browser	Browser automation	Playwright
document	Document processing	PDF, Word, Markdown loaders
api	API framework	FastAPI, Uvicorn, Starlette
visualization	Graphs & charts	PyVis, Gravis, Matplotlib, Seaborn, Pandas
anthropic	Claude models	Anthropic SDK
azure	Azure models	Azure Identity, Azure AI Inference
cerebras	Cerebras models	Cerebras Cloud SDK
cohere	Cohere models	Cohere SDK
gemini	Gemini models	Google GenAI SDK
groq	Groq models	Groq SDK
all-providers	All LLM providers	anthropic, azure, cerebras, cohere, gemini, groq
a2a	Agent2Agent protocol	a2a-sdk, uvicorn
all-backend	All backends	vector-stores, retrieval, database, infrastructure
all	Everything	All above + visualization

Development installation

# Core dev tools (linting, type checking)
uv sync --group dev

# Add testing
uv sync --group dev --group test

# Add backend tests (vector stores, databases)
uv sync --group dev --group test --group test-backends

# Add documentation
uv sync --group dev --group test --group test-backends --group docs

---

Quick Start

Your First Agent

import asyncio
from cogent import Agent, tool

@tool
def get_weather(city: str) -> str:
    """Get current weather for a city."""
    return f"Weather in {city}: 72°F, sunny"

async def main():
    # Simple string model (recommended)
    agent = Agent(
        name="Assistant",
        model="gpt4",  # Auto-resolves to gpt-4.1
        tools=[get_weather],
    )

    result = await agent.run("What's the weather in Tokyo?")
    print(result.output)

asyncio.run(main())

Other model options:

# With provider prefix
agent = Agent(name="Assistant", model="anthropic:claude")

# Medium-level: Factory function
from cogent.models import create_chat
agent = Agent(name="Assistant", model=create_chat("gpt4"))

# Low-level: Full control
from cogent.models import OpenAIChat
agent = Agent(name="Assistant", model=OpenAIChat(model="gpt-4.1", temperature=0.7))

With Toolkits

Instead of defining individual tools, use pre-built toolkits:

from cogent import Agent
from cogent.toolkits import FileSystem, WebSearch, CodeSandbox

agent = Agent(
    name="Assistant",
    model="gpt4",  # Simple string model
    tools=[
        FileSystem(allowed_paths=["./project"]),
        WebSearch(),
        CodeSandbox(timeout=30),
    ],
)

result = await agent.run("Search for Python tutorials and create a summary file")

---

Core Concepts

Agents

Autonomous entities that think, act, and communicate:

agent = Agent(
    name="Researcher",
    model="gpt4",  # String model - auto-resolves to gpt-4.1
    instructions="You are a thorough researcher.",
    tools=[search, summarize],
    verbosity=True,
)

Tools

Define tools with the @tool decorator:

from cogent import tool

@tool
def search(query: str, max_results: int = 10) -> str:
    """Search the web for information.

    Args:
        query: Search query string.
        max_results: Maximum results to return.
    """
    return f"Found {max_results} results for: {query}"

# Async tools supported
@tool
async def fetch_data(url: str) -> str:
    """Fetch data from URL."""
    async with httpx.AsyncClient() as client:
        response = await client.get(url)
        return response.text

Tool features: - Automatic schema extraction from type hints - Docstring → description - Sync and async support - Context injection via ctx: RunContext

---

Model Providers

Cogent supports all major LLM providers with native SDK integrations:

from cogent.models import (
    OpenAIChat,
    AnthropicChat,
    GeminiChat,
    GroqChat,
    OllamaChat,
)

# OpenAI
model = OpenAIChat(model="gpt-5.4")

# Anthropic Claude
model = AnthropicChat(model="claude-sonnet-4-20250514")

# Google Gemini
model = GeminiChat(model="gemini-2.0-flash-exp")

# Groq (fast inference)
model = GroqChat(model="llama-3.3-70b-versatile")

# Ollama (local models)
model = OllamaChat(model="llama3.2")

# Or use factory function
from cogent.models import create_chat

model = create_chat("anthropic", model="claude-sonnet-4-20250514")

---

Streaming

Stream responses token-by-token:

agent = Agent(
    name="Writer",
    model=model,
    stream=True,
)

async for chunk in agent.run_stream("Write a poem about AI"):
    print(chunk.content, end="", flush=True)

---

Memory & Context

Agents maintain conversation history automatically:

agent = Agent(
    name="Assistant",
    model=model,
    memory_enabled=True,  # Default: True
)

# First interaction
await agent.run("My name is Alice")

# Later interaction - agent remembers
await agent.run("What's my name?")  # "Your name is Alice"

# Clear memory
agent.clear_memory()

---

Observability

Track execution with built-in observability:

from cogent.observability import Observer

# Pre-configured observers
observer = Observer(level="trace")      # Maximum detail, including stream tokens
observer = Observer(level="debug")      # LLM internals: requests, responses, token usage
observer = Observer(level="progress")   # Agent lifecycle and tool calls (default)

# Use observer with agent
result = await agent.run("Query", observer=observer)

# Access event history
for event in observer.history():
    print(f"{event.type}: {event.data}")

See observability.md for the full built-in event taxonomy and payload conventions.

---

Interceptors

Control execution with middleware:

from cogent.interceptors import BudgetGuard, RateLimiter, PIIShield

agent = Agent(
    name="Assistant",
    model=model,
    interceptors=[
        BudgetGuard(max_tokens=10000, max_cost=0.50),  # Token/cost limits
        RateLimiter(max_requests_per_minute=60),        # Rate limiting
        PIIShield(redact=True),                         # PII protection
    ],
)

---

Next Steps

Now that you know the basics, explore:

• Agent Documentation — Deep dive into agents, instructions, and configuration
• Multi-Agent — Build coordinated multi-agent systems
• Toolkits — Explore built-in toolkits
• Graph Visualization — Visualize your agents
• RAG & Retrieval — Build retrieval-augmented generation systems
• Examples — See working examples

---

Need Help?

• Documentation: https://milad-o.github.io/cogent
• Examples: https://github.com/milad-o/cogent/tree/main/examples
• Issues: https://github.com/milad-o/cogent/issues