Skip to content

Agent Types

Kagura provides three core agent types, each tailored for specific tasks and workflows. Understanding these types will help you choose the best one for your project.

Atomic Agent

Overview

The Atomic Agent is the foundational building block for stateful AI tasks. It interacts with LLMs and supports flexible configurations for complex processing.

Key Features

  • Stateful LLM Processing: Manages input and output states using YAML-defined models.
  • Pre/Post-Processing Hooks: Allows for additional customization before and after LLM interactions.
  • Structured Outputs: Ensures consistency through type-safe validation.

Use Cases

  • Generating structured content like summaries or reports.
  • Answering complex queries with context-aware responses.
  • Processing multi-step LLM workflows.

Example Configuration

# agent.yml
type: atomic  # atomic, tool, or workflow
llm: # Custom LLM configuration for the agent (optional)
  model: openai/gpt-4o-mini
  max_tokens: 2048
  retry_count: 3
description:
  - language: en
    text: An agent for summarizing documents.
prompt:
  - language: en
    template: |
      Summarize: {content}
response_fields:
  - summary
input_fields:
  - content

Tool Agent

Overview

The Tool Agent is designed for tasks that do not involve LLMs. It excels at fast data transformations and external API integrations.

Key Features

  • No LLM Dependency: Focuses on computational tasks.
  • Fast Execution: Optimized for quick processing.
  • Extensibility: Supports integration with custom tools and APIs.

Use Cases

  • Fetching data from external sources.
  • Transforming or validating structured data.
  • Integrating with external APIs for domain-specific tasks.

Example Configuration

# agent.yml
custom_tool: agent_name.tools.data_fetcher
response_fields:
  - data  # State fields updated or generated by the tool
input_fields:  # State fields required for the tool
  - url
  - params

Workflow Agent

Overview

The Workflow Agent coordinates workflows involving multiple agents. It manages state sharing, conditional routing, and error handling across agents.

Key Features

  • Multi-Agent Workflows: Integrates and coordinates multiple agents (Atomic Agent and Tool Agent) in a single workflow.
  • State Binding: Shares and transfers state between agents seamlessly.
  • Conditional Routing: Supports dynamic transitions between workflow nodes based on runtime conditions.
  • Error Recovery: Handles errors gracefully with retry mechanisms and fallback options.
  • No State Model Requirement: Relies on predefined configurations of Atomic Agent and Tool Agent, eliminating the need for its own state_model.yml.

Use Cases

  • Coordinating a pipeline for document analysis and summarization.
  • Managing workflows that combine data processing and LLM interactions.
  • Implementing complex multi-step decision-making systems.

Example Configuration

# agent.yml
entry_point: data_collector
nodes:
  - data_collector
  - analyzer
  - summarizer

edges:
  - from: data_collector
    to: analyzer
  - from: analyzer
    to: summarizer

state_field_bindings:
  - from: data_collector.data
    to: analyzer.input_text
  - from: analyzer.result.text
    to: summarizer.context

Choosing the Right Agent

Agent Type Use When You Need
Atomic Agent Context-aware LLM interactions.
Tool Agent Fast data transformations and API calls.
Worfklow Agent Complex, multi-step workflows.