orka.agents package

OrKa Agents Package

This package contains all agent implementations for the OrKa framework. Agents are the fundamental building blocks that perform specific tasks within orchestrated workflows.

Agent Architecture

OrKa supports two agent implementation patterns:

Modern Async Pattern (Recommended)

Inherits from BaseAgent

  • Full async/await support for concurrent execution

  • Built-in timeout and concurrency control

  • Structured output handling with automatic error wrapping

  • Lifecycle hooks for initialization and cleanup

Legacy Sync Pattern (Backward Compatibility)

Inherits from LegacyBaseAgent

  • Simple synchronous execution model

  • Compatible with existing agent implementations

  • Direct result return without wrapping

Available Agent Types

Core Decision Agents

BinaryAgent

Makes binary (yes/no) decisions based on input criteria

ClassificationAgent

Deprecated since version 0.5.6: Classifies input into predefined categories (deprecated - use OpenAIClassificationAgent instead)

LLM Integration Agents

OpenAIAnswerBuilder

Generates text responses using OpenAI models

OpenAIBinaryAgent

Makes binary decisions using OpenAI model reasoning

OpenAIClassificationAgent

Performs classification using OpenAI models

LocalLLMAgent

Integrates with local LLM providers (Ollama, LM Studio, etc.)

Specialized Agents

ValidationAndStructuringAgent

Validates answers and structures them into memory objects

Agent Registry

The package maintains a central registry mapping agent type identifiers to their implementation classes:

AGENT_REGISTRY = {
    "binary": BinaryAgent,
    "classification": ClassificationAgent,
    "local_llm": LocalLLMAgent,
    "openai-answer": OpenAIAnswerBuilder,
    "openai-binary": OpenAIBinaryAgent,
    "openai-classification": OpenAIClassificationAgent,
    "validate_and_structure": ValidationAndStructuringAgent,
}

Usage Examples

Creating Custom Agents

from orka.agents.base_agent import BaseAgent

class MyCustomAgent(BaseAgent):
    async def _run_impl(self, ctx):
        input_data = ctx.get("input")
        # Process input asynchronously
        return "processed result"

Using Existing Agents

from orka.agents import OpenAIAnswerBuilder

# Agent is typically instantiated by the orchestrator
# based on YAML configuration
agent = OpenAIAnswerBuilder(agent_id="my_agent")

Agent Configuration

Agents are typically configured through YAML workflow definitions:

agents:
  - id: my_classifier
    type: classification
    prompt: "Classify this input: {{ input }}"
    options: [positive, negative, neutral]
    timeout: 30.0
    max_concurrency: 5

Module Components

Available Modules:

  • base_agent - Base classes and interfaces

  • agents - Core decision agents (binary, classification)

  • llm_agents - OpenAI integration agents

  • local_llm_agents - Local LLM integration

  • validation_and_structuring_agent - Validation utilities

  • local_cost_calculator - Cost calculation for local models

Submodules