Agent Types in OrKa

Last Updated: 03 January 2026
Status: 🟢 Current
Related: Advanced Agents | Extending Agents | Agent Index | INDEX

In OrKa, agents are modular processing units that receive input and return structured output — all orchestrated via a declarative YAML configuration.

Agents can represent different cognitive functions: classification, decision-making, web search, conditional routing, memory management, and more.

The OrKa framework uses a unified agent base implementation that supports both modern asynchronous patterns and legacy synchronous patterns for backward compatibility.

🧱 Core Agent Types

� `brain`

Procedural skill memory — learns abstract, transferable skills from LLM reasoning traces and re-applies them across domains.

Use case: Cross-domain knowledge transfer, continuous learning, skill accumulation.

Operations:

learn — Extract a transferable skill from an execution trace
recall — Find applicable skills for a new context
feedback — Record whether a transferred skill succeeded

Example config:

- id: brain_learn
  type: brain
  operation: learn
  prompt: "{{ previous_outputs.llm_reasoner }}"

- id: brain_recall
  type: brain
  operation: recall
  prompt: "{{ previous_outputs.new_context }}"

- id: brain_feedback
  type: brain
  operation: feedback
  prompt: "{{ previous_outputs.brain_recall }}"

📖 Complete Brain Documentation

�🧭 `graph-scout`

Intelligent workflow graph inspection and optimal multi-agent path execution. GraphScout automatically discovers, evaluates, and executes the best sequence of agents for any given input.

Use case: Dynamic routing, intelligent workflow orchestration, adaptive agent selection.

Key Features:

Intelligent Path Discovery: Automatically finds optimal agent sequences
Memory-Aware Routing: Positions memory agents optimally (readers first, writers last)
Multi-Agent Execution: Executes ALL agents in shortlist sequentially
LLM-Powered Evaluation: Advanced reasoning for path selection
Budget & Safety Control: Respects token/latency budgets and safety thresholds

Example config:

- id: smart_router
  type: graph-scout
  k_beam: 5                # Top-k candidate paths
  max_depth: 3             # Maximum path depth
  commit_margin: 0.15      # Confidence threshold
  cost_budget_tokens: 1000 # Token budget limit
  latency_budget_ms: 2000  # Latency budget limit
  safety_threshold: 0.2    # Lower is safer (0.0-1.0)
  prompt: "Find the best path for: {{ input }}"

Decision Types:

commit_next: High confidence single path → Execute immediately
shortlist: Multiple good options → Execute all sequentially
no_path: No suitable path → Fallback to response builder

📖 Complete GraphScout Documentation

🔘 `binary`

Returns a boolean ("true" or "false" as strings) based on a question or statement.

Use case: Fact checking, condition validation, flag triggering.

Example config:

- id: is_fact
  type: binary
  prompt: >
    Is the following statement factually accurate? Return TRUE or FALSE.
  queue: orka:binary_check

🧾 `classification`

⚠️ Deprecated - kept only for backward compatibility.

This agent no longer performs classification and returns "deprecated".

Use case: Basic topic detection (legacy support only).

🤖 `openai-binary`

Uses OpenAI's LLM to perform binary classification with sophisticated reasoning.

Use case: Complex true/false decisions requiring natural language understanding.

Example config:

- id: content_appropriate
  type: openai-binary
  prompt: >
    Is this content appropriate for a professional environment?
    Content: {{ input }}
  queue: orka:moderation

🎯 `openai-classification`

Uses OpenAI's LLM to classify input into multiple predefined categories.

Use case: Advanced topic classification, sentiment analysis, content categorization.

Example config:

- id: domain_classifier
  type: openai-classification
  prompt: >
    Classify this question into one of the following domains:
  options: [science, geography, history, technology, general]
  queue: orka:classify

📝 `openai-answer`

Builds comprehensive answers using OpenAI's LLM, typically enriched with context from previous agents.

Use case: Question answering, content generation, summarization.

Example config:

- id: answer_builder
  type: openai-answer
  prompt: |
    Based on the search results: {{ previous_outputs.web_search }}
    And classification: {{ previous_outputs.classifier }}
    Provide a comprehensive answer to: {{ input }}
  queue: orka:answer

🏠 `local_llm`

Interfaces with locally running large language models (Ollama, LM Studio, etc.) for privacy-preserving AI processing.

Use case: Offline processing, privacy-sensitive applications, custom model deployment.

Supported Providers:

ollama: Native Ollama API
lm_studio: LM Studio OpenAI-compatible endpoint
openai_compatible: Any OpenAI-compatible API

Example config:

- id: local_summarizer
  type: local_llm
  prompt: "Summarize this text: {{ input }}"
  model: "llama3.2:latest"
  model_url: "http://localhost:1234"
  provider: "ollama"
  temperature: 0.7
  queue: orka:local

✅ `validate_and_structure`

Validates answers for correctness and structures them into memory objects with metadata.

Use case: Answer validation, data structuring, quality assurance.

Example config:

- id: validator
  type: validate_and_structure
  prompt: "Validate and structure this answer"
  store_structure: |
    {
      "topic": "extracted topic",
      "confidence": "confidence score",
      "key_points": ["list", "of", "points"]
    }
  queue: orka:validate

🔧 Tools

🌐 `duckduckgo`

Performs real-time web search using DuckDuckGo's search engine.

Use case: Information retrieval, fact-checking, current events.

Example config:

- id: web_search
  type: duckduckgo
  prompt: "Search for: {{ input }}"
  params:
    num_results: 5
    region: "us-en"
    safe_search: "moderate"
  queue: orka:search

💾 Memory Agents ⚡ 100x Faster with RedisStack HNSW

OrKa configures memory via a single agent type: memory. The operation is selected via config.operation.

📖 Read (`type: memory`, `config.operation: read`)

- id: memory_reader
  type: memory
  namespace: conversations
  memory_preset: episodic
  config:
    operation: read
    limit: 10
    similarity_threshold: 0.6
    enable_context_search: false
    enable_temporal_ranking: false
  prompt: "Find memories about: {{ input }}"

💾 Write (`type: memory`, `config.operation: write`)

- id: memory_writer
  type: memory
  namespace: conversations
  memory_preset: working
  config:
    operation: write
  metadata:
    source: user
  prompt: "Store: {{ input }}"

🧵 Control Flow Nodes

🔀 `router`

Dynamically routes execution based on previous agent outputs.

Example config:

- id: content_router
  type: router
  params:
    decision_key: content_type
    routing_map:
      "question": [search_agent, answer_builder]
      "statement": [fact_checker, validator]
      "request": [task_processor]

🔄 `failover`

Executes child agents sequentially until one succeeds, providing resilience.

Example config:

- id: resilient_search
  type: failover
  children:
    - id: primary_search
      type: duckduckgo
      prompt: "Search: {{ input }}"
    - id: backup_method
      type: openai-answer
      prompt: "Answer from knowledge: {{ input }}"

🌿 `fork`

Splits execution into multiple parallel branches for concurrent processing.

Example config:

- id: parallel_validation
  type: fork
  targets:
    - [sentiment_check]
    - [toxicity_check]
    - [fact_validation]
  mode: parallel

🔗 `join`

Waits for forked agents to complete and aggregates their outputs.

Example config:

- id: validation_merger
  type: join
  prompt: "Combine validation results"

🔥 `failing`

Intentionally fails for testing error handling and failover scenarios.

Example config:

- id: test_failure
  type: failing
  prompt: "This will always fail"

🔄 `loop`

Executes an internal workflow repeatedly until a score threshold is met or maximum loops are reached. Features cognitive insight extraction and iterative improvement capabilities.

Use case: Iterative refinement, consensus building, multi-agent deliberation, self-improving systems.

Key Features:

Threshold-based execution - Continues until score meets requirements
Cognitive insight extraction - Automatically extracts insights, improvements, and mistakes
Past loops context - Maintains memory of previous iterations for learning
Flexible scoring - Configurable score extraction via regex patterns or direct keys
Iterative improvement - Agents learn from previous attempts

Example config:

- id: iterative_improver
  type: loop
  max_loops: 10
  score_threshold: 0.85
  score_extraction_pattern: "SCORE:\\s*([0-9.]+)"
  
  # Cognitive extraction configuration
  cognitive_extraction:
    enabled: true
    max_length_per_category: 300
    extract_patterns:
      insights:
        - "(?:provides?|identifies?|shows?)\\s+(.+?)(?:\\n|$)"
        - "(?:solid|good|comprehensive)\\s+(.+?)(?:\\n|$)"
      improvements:
        - "(?:lacks?|needs?|requires?|should)\\s+(.+?)(?:\\n|$)"
        - "(?:would improve|could benefit from)\\s+(.+?)(?:\\n|$)"
      mistakes:
        - "(?:overlooked|missed|inadequate)\\s+(.+?)(?:\\n|$)"
        - "(?:weakness|limitation|gap)\\s*[:\\s]*(.+?)(?:\\n|$)"
  
  # Past loops metadata template
  past_loops_metadata:
    loop_number: "{{ loop_number }}"
    score: "{{ score }}"
    key_insights: "{{ insights }}"
    improvements_needed: "{{ improvements }}"
    mistakes_identified: "{{ mistakes }}"
  
  # Internal workflow that gets repeated
  internal_workflow:
    orchestrator:
      id: internal-loop
      strategy: sequential
      agents: [analyzer, scorer]
    agents:
      - id: analyzer
        type: openai-answer
        prompt: |
          Analyze: {{ input }}
          
          {% if previous_outputs.past_loops %}
          Previous attempts:
          {% for loop in previous_outputs.past_loops %}
          - Loop {{ loop.loop_number }} (Score: {{ loop.score }}):
            * Insights: {{ loop.key_insights }}
            * Improvements: {{ loop.improvements_needed }}
            * Mistakes: {{ loop.mistakes_identified }}
          {% endfor %}
          
          Build upon these insights and address the gaps.
          {% endif %}
          
          Provide comprehensive analysis with clear insights.
      
      - id: scorer
        type: openai-answer
        prompt: |
          Rate this analysis (0.0 to 1.0): {{ previous_outputs.analyzer.result }}
          
          Format: SCORE: X.XX
          Explain what needs improvement if score is below threshold.

Multi-Agent Deliberation Example:

- id: cognitive_society
  type: loop
  max_loops: 5
  score_threshold: 0.95
  score_extraction_pattern: "AGREEMENT_SCORE[\":]?\\s*\"?([0-9.]+)\"?"
  
  internal_workflow:
    orchestrator:
      id: deliberation
      strategy: sequential
      agents: [fork_reasoning, join_perspectives, moderator]
    agents:
      - id: fork_reasoning
        type: fork
        targets:
          - [logic_agent]
          - [empathy_agent]
          - [skeptic_agent]
      
      - id: logic_agent
        type: openai-answer
        prompt: "Provide logical analysis of: {{ input }}"
      
      - id: empathy_agent
        type: openai-answer
        prompt: "Provide empathetic perspective on: {{ input }}"
      
      - id: skeptic_agent
        type: openai-answer
        prompt: "Provide critical analysis of: {{ input }}"
      
      - id: join_perspectives
        type: join
        group: fork_reasoning
      
      - id: moderator
        type: openai-answer
        prompt: |
          Evaluate agent convergence on: {{ input }}
          
          Logic: {{ previous_outputs.logic_agent.response }}
          Empathy: {{ previous_outputs.empathy_agent.response }}
          Skeptic: {{ previous_outputs.skeptic_agent.response }}
          
          Score agreement level (0.0-1.0):
          AGREEMENT_SCORE: [score]

🤖 Advanced Nodes

🔍 `rag`

Performs Retrieval-Augmented Generation with vector search and LLM generation.

Configuration:

- id: knowledge_qa
  type: rag
  params:
    top_k: 5
    score_threshold: 0.7
  prompt: "Answer using knowledge base"

📊 Agent Summary

Agent Type	Category	Purpose	Status
`binary`	Agent	Simple true/false decisions	Active
`classification`	Agent	Basic categorization	Deprecated
`openai-binary`	Agent	LLM-powered binary decisions	Active
`openai-classification`	Agent	LLM-powered categorization	Active
`openai-answer`	Agent	Content generation	Active
`local_llm`	Agent	Local model inference	Active
`validate_and_structure`	Agent	Answer validation	Active
`duckduckgo`	Tool	Web search	Active
`memory` (read)	Node	Memory retrieval	Active
`memory` (write)	Node	Memory storage	Active
`rag`	Node	RAG operations	Active
`router`	Node	Dynamic routing	Active
`failover`	Node	Error resilience	Active
`fork`	Node	Parallel execution	Active
`join`	Node	Result aggregation	Active
`loop`	Node	Iterative workflows	Active
`failing`	Node	Testing failures	Active

🧩 Structured Output

Agents support provider-enforced structured outputs via params.structured_output. Enable it per agent to receive valid JSON matching a schema. Modes: auto, model_json, tool_call, prompt. See the Structured Output Guide for details and examples.

🚀 Getting Started

Choose your agent types based on your workflow needs
Configure YAML with appropriate prompts and parameters
Test individually before chaining agents
Monitor execution through OrKa UI or logs
Iterate and optimize based on results

For detailed configuration examples, see the YAML Configuration Guide.

← YAML Configuration | 📚 index | Advanced Agents →

← Streaming Guide | 📚 INDEX | Advanced Agents →

FilesExpand file tree

agents.md

Latest commit

History

agents.md

File metadata and controls

Agent Types in OrKa

🧱 Core Agent Types

� brain

�🧭 graph-scout

🔘 binary

🧾 classification

🤖 openai-binary

🎯 openai-classification

📝 openai-answer

🏠 local_llm

✅ validate_and_structure

🔧 Tools

🌐 duckduckgo

💾 Memory Agents ⚡ 100x Faster with RedisStack HNSW

📖 Read (type: memory, config.operation: read)

💾 Write (type: memory, config.operation: write)

🧵 Control Flow Nodes

🔀 router

🔄 failover

🌿 fork

🔗 join

🔥 failing

🔄 loop

🤖 Advanced Nodes

🔍 rag

📊 Agent Summary

🧩 Structured Output

🚀 Getting Started

← YAML Configuration | 📚 index | Advanced Agents →

� `brain`

�🧭 `graph-scout`

🔘 `binary`

🧾 `classification`

🤖 `openai-binary`

🎯 `openai-classification`

📝 `openai-answer`

🏠 `local_llm`

✅ `validate_and_structure`

🌐 `duckduckgo`

📖 Read (`type: memory`, `config.operation: read`)

💾 Write (`type: memory`, `config.operation: write`)

🔀 `router`

🔄 `failover`

🌿 `fork`

🔗 `join`

🔥 `failing`

🔄 `loop`

🔍 `rag`