Agent Module¶

The cogent.agent module defines the core agent abstraction - autonomous entities that can think, act, and communicate.

Overview¶

Agents are the primary actors in the system. Each agent has: - A unique identity and role - Configuration defining its toolkits - Runtime state tracking its activity - Access to tools and the event bus

from cogent import Agent

# Simple string model
agent = Agent(
    name="Researcher",
    model="gpt4",  # Auto-resolves to gpt-4.1
    tools=[search_tool],
    instructions="You are a research assistant.",
)

# With provider prefix
agent = Agent(
    name="Researcher",
    model="anthropic:claude",  # Explicit provider
    tools=[search_tool],
)

# Medium-level: Factory function
from cogent.models import create_chat
agent = Agent(
    name="Researcher",
    model=create_chat("gpt4"),
    tools=[search_tool],
)

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

result = await agent.run("Find information about quantum computing")

Core Classes¶

Agent¶

The main agent class:

from cogent import Agent

# String model (recommended)
agent = Agent(
    name="Writer",
    model="gpt4",  # Auto-resolves to gpt-4.1
    tools=[write_tool],
    instructions="You write compelling content.",
)

# Provider prefix for explicit control
agent = Agent(
    name="Writer",
    model="anthropic:claude-sonnet-4",
    tools=[write_tool],
)

# Model instance for full control
from cogent.models import create_chat

agent = Agent(
    name="Writer",
    model=create_chat("gpt4"),
    tools=[write_tool],
)

TaskBoard¶

Enable task tracking for complex, multi-step work:

agent = Agent(
    name="ProjectManager",
    model="gpt-5.4-mini",
    instructions="You are a helpful project manager.",
    taskboard=True,  # Enables task tracking tools
)

result = await agent.run("Plan a REST API for a todo app")

# Check taskboard after execution
print(agent.taskboard.summary())

TaskBoard Tools¶

When taskboard=True, the agent gets these tools:

Tool	Description
`add_task`	Create a new task to track
`update_task`	Update task status (pending, in_progress, completed, failed, blocked)
`add_note`	Record observations and findings
`verify_task`	Verify a task was completed correctly
`get_taskboard_status`	See overall progress

How It Works¶

Instructions injected — Agent receives guidance on when/how to use taskboard
LLM decides — For complex tasks, the agent breaks them into subtasks
Progress tracked — Tasks have status, notes, and verification
Summary available — agent.taskboard.summary() shows progress

TaskBoard Configuration¶

from cogent.agent.taskboard import TaskBoardConfig

agent = Agent(
    name="Worker",
    model="gpt4",
    taskboard=TaskBoardConfig(
        include_instructions=True,  # Inject usage instructions (default: True)
        max_tasks=50,               # Maximum tasks to track
        track_time=True,            # Track task timing
    ),
)

See examples/advanced/taskboard.py for a complete example.

API Reference¶

Agent Methods¶

Method	Description
`run(task, context)`	Execute a task with optional context
`chat(message, thread_id)`	Chat with memory support
`think(prompt)`	Single reasoning step
`stream_chat(message)`	Streaming chat response
`resume(state, decision)`	Resume after HITL interrupt

See docs/context.md for context patterns.

Model-Specific Configuration¶

Pass model-specific parameters via model_kwargs:

from cogent import Agent

# Gemini with thinking enabled
agent = Agent(
    name="Thinker",
    model="gemini-2.5-flash",
    model_kwargs={"thinking_budget": 16384},  # Enable native thinking
)

# OpenAI with specific settings
agent = Agent(
    name="Assistant",
    model="gpt-5.4",
    model_kwargs={"seed": 42, "logprobs": True},
)

# Any model-specific parameter
agent = Agent(
    name="Custom",
    model="anthropic:claude-sonnet-4",
    model_kwargs={"top_k": 10},
)

Note: model_kwargs only applies when using string model names. Ignored when passing ChatModel instances (configure the instance directly instead).

Agent Parameters¶

Parameter	Type	Description
`name`	`str`	Agent name
`model`	`str \\| BaseChatModel`	Chat model (string or instance)
`model_kwargs`	`dict \\| None`	Model-specific parameters (for string models)
`instructions`	`str \\| None`	Instructions defining agent behavior
`tools`	`list`	Tool functions, BaseTool objects, or Toolkit instances
`subagents`	`list \\| dict`	Specialist agents for delegation
`returns`	`type \\| dict \\| None`	Structured output schema when used as a subagent
`resilience`	`ResilienceConfig \\| None`	Retry logic and circuit breakers
`interrupt_on`	`dict \\| None`	HITL triggers
`stream`	`bool`	Enable streaming
`reasoning`	`bool \\| ReasoningConfig`	Extended thinking
`taskboard`	`bool \\| TaskBoardConfig`	Task tracking
`verbosity`	`bool \\| str \\| int \\| None`	Observability level

Exports¶

from cogent.agent import (
    # Core
    Agent,
    AgentState,
    # Memory
    AgentMemory,
    MemorySnapshot,
    InMemorySaver,
    ThreadConfig,
    # Resilience
    RetryStrategy,
    RetryPolicy,
    CircuitBreaker,
    ResilienceConfig,
    ToolResilience,
    # HITL
    InterruptReason,
    HumanDecision,
    InterruptedException,
    # TaskBoard
    TaskBoard,
    TaskBoardConfig,
    Task,
    TaskStatus,
    # Reasoning
    ReasoningConfig,
    ReasoningStyle,
    ThinkingStep,
    # Output
    ResponseSchema,
    StructuredResult,
    # Spawning
    AgentSpec,
    SpawningConfig,
    SpawnManager,
)