Agents

An Agent is the core unit in Veska. It receives a task, reasons about it, decides what to do, takes actions using tools, and returns a result. Each agent runs a Think → Decide → Act → Observe loop.

Agent parameters

Create an agent by passing these parameters directly:

python

Agent(
    name: str,                                # Required: agent name
    system_prompt: str = "",                  # Agent's role and purpose
    model: Optional[str] = None,             # Model name (e.g. "claude-sonnet-4-6", "gpt-4o")
    api_key: Optional[str] = None,           # API key (or set in .env)
    tools: Optional[list[Tool]] = None,       # Available tools
    thinking: Optional[dict] = None,          # Extended thinking config
    max_iterations: int = 20,                 # Max reasoning loop iterations
    temperature: Optional[float] = None,      # 0 = precise, 1 = creative
    storage_dir: Optional[str] = None,        # For context persistence
    on_ask_user: Optional[Any] = None,        # Human-in-the-loop callback
    ask_user_timeout: int = 300,              # Timeout for user response (seconds)
    memory_store: Optional[MemoryStore] = None,  # Persistent memory backend
    cache: Optional[CacheStore] = None,          # Response caching
    session_store: Optional[SessionStore] = None, # Conversation history
    output_format: Optional[dict] = None,        # Structured output format
)

Creating an agent

basic.py

from veska import Agent

agent = Agent(
    name="assistant",
    system_prompt="You are a helpful Python developer.",
    model="claude-sonnet-4-6",
)

Running an agent

The run() method is the main entry point:

python

result = agent.run(
    task="Write a function to sort a list",
    context="",                    # Additional context
    stream=None,                   # True, callback, or None
    attachments=None,              # Images, PDFs, audio
    user_id=None,                  # For session tracking
    session_id=None,               # For conversation continuity
)

AgentResult

Every agent run returns an AgentResult:

python

AgentResult(
    agent_name: str,        # Which agent produced this
    success: bool,          # Whether it completed successfully
    output: Any,            # The final output (str or parsed model)
    error: Optional[str],   # Error message if failed
    iterations: int,        # How many loop iterations it took
)

result.py

result = agent.run("Explain decorators in Python")

if result.success:
    print(result.output)        # The agent's response
    print(result.iterations)    # e.g., 1
else:
    print(f"Failed: {result.error}")

Agent with tools

tools.py

from veska import Agent, tool

@tool
def calculate(expression: str):
    return str(eval(expression))

agent = Agent(
    name="math-helper",
    system_prompt="You help with math problems. Use the calculate tool to evaluate expressions.",
    model="claude-sonnet-4-6",
    tools=[calculate],
)

result = agent.run("What is 42 * 17 + 89?")

Agent with memory

memory.py

from veska import Agent, FileMemoryStore

agent = Agent(
    name="assistant",
    system_prompt="You remember everything users tell you.",
    model="claude-sonnet-4-6",
    memory_store=FileMemoryStore("./memory"),
)

# First conversation
agent.run("My name is Alex and I work at Acme Corp")

# Later conversation — agent remembers
agent.run("What's my name?")

Agent properties

Property	Description
`status`	idle, working, waiting, done, or failed
`id`	Unique 8-character UUID
`name`	Agent name
`tools`	List of available tools
`memory`	AgentMemory instance (private)
`cache`	CacheStore instance (optional)
`context`	ContextManager instance

Other methods

methods.py

# Dynamically update tools
agent.update_tools([new_tool_1, new_tool_2])

# Get conversation history
messages = agent.get_conversation_history()

# Reset conversation (keeps memory)
agent.reset()

Per-agent models

Each agent can use a different model:

multi_model.py

from veska import Agent

# This agent uses Claude
researcher = Agent(
    name="researcher",
    system_prompt="You research topics thoroughly.",
    model="claude-sonnet-4-6",
)

# This agent uses OpenAI
writer = Agent(
    name="writer",
    system_prompt="You write clear content.",
    model="gpt-4o",
)