Getting Started¶

Get up and running with Cogent in minutes.

Installation¶

# Install from PyPI
pip install cogent-ai

# Or with uv (recommended)
uv add cogent-ai

Optional dependency groups:

Choose what you need:

# Vector stores (FAISS, Qdrant)
uv add "cogent-ai[vector-stores]"

# Retrieval (BM25, rerankers)
uv add "cogent-ai[retrieval]"

# Database backends (SQLAlchemy + drivers)
uv add "cogent-ai[database]"

# Infrastructure (Redis)
uv add "cogent-ai[infrastructure]"

# Web tools (search, scraping)
uv add "cogent-ai[web]"

# LLM providers (Anthropic, Azure, Cerebras, Cohere, Gemini, Groq)
uv add "cogent-ai[all-providers]"

# All backends
uv add "cogent-ai[all-backend]"

# Everything
uv add "cogent-ai[all]"

Development installation:

# Development + testing
uv sync --group dev --group test
uv sync --group dev --group test --group test-backends
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-5.4
        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-5.4", temperature=0.7))

With Capabilities¶

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

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

agent = Agent(
    name="Assistant",
    model="gpt4",  # Simple string model
    capabilities=[
        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-5.4
    instructions="You are a thorough researcher.",
    tools=[search, summarize],
    verbose=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
Capabilities — Explore built-in tools and capabilities
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