Core Concepts

Understanding AGNT5's building blocks for creating durable workflows and applications


AGNT5 provides five core building blocks for creating durable applications that survive failures and maintain state across restarts.

These primitives work together whether you’re building simple functions or complex multi-agent systems.

Tasks

Tasks are durable functions that automatically recover from failures.

They represent any unit of computational work with exactly-once execution guarantees.

What tasks can do:

  • Execute any Python or TypeScript function with durability
  • Process classification tasks with LLMs
  • Handle structured output extraction and validation
  • Run data transformations and API calls
  • Perform complex multi-step computations

Key features:

  • Automatic recovery - Resume from exactly where they failed
  • State persistence - Maintain progress across restarts
  • Result validation - Define success criteria and output types
  • Timeout handling - Configurable execution limits
  • Error boundaries - Isolate failures to prevent cascade effects

Tasks are the fundamental building blocks that make any function durable and reliable.

Workflows

Workflows orchestrate multiple tasks and provide coordination for complex operations.

They maintain shared context and handle dependencies between tasks.

What workflows enable:

  • Chain tasks with conditional logic and dependencies
  • Run tasks in parallel or sequential patterns
  • Share state and data between multiple tasks
  • Handle complex business processes with multiple steps
  • React to external events and triggers

Key features:

  • Task orchestration - Coordinate execution order and dependencies
  • Shared context - Maintain consistent state across all tasks
  • Failure isolation - Continue execution when individual tasks fail
  • Event-driven patterns - React to external triggers and webhooks
  • Hierarchical structure - Nest workflows for complex operations

Workflows provide the structure for building sophisticated applications with multiple coordinated steps.

Agents

Agents are AI-powered entities that can execute tasks intelligently.

They bring reasoning and adaptability to your workflows through LLM integration.

What agents provide:

  • Intelligent decision-making within tasks and workflows
  • Natural language processing and generation
  • Conversation memory and context management
  • Specialized capabilities for different domains
  • Collaboration patterns for multi-agent coordination

Key features:

  • LLM integration - Works with OpenAI, Anthropic, Google, and other providers
  • Memory management - Maintain conversation history and learned context
  • Specialization - Configure agents for specific roles and expertise
  • Multi-agent coordination - Enable collaboration between multiple agents
  • Interactive capabilities - Support human-in-the-loop patterns

Agents add intelligence to your tasks and workflows, handling the nuanced aspects of AI-powered operations.

Tools

Tools extend functionality by providing access to external systems, APIs, and custom functions.

They bridge your workflows with the real world.

What tools enable:

  • Connect to databases, APIs, and external services
  • Execute custom Python or TypeScript functions
  • Process files, images, and other media
  • Send notifications and webhooks
  • Integrate with existing systems and infrastructure

Key features:

  • Function integration - Call any custom function as a tool
  • API connectivity - Connect to REST APIs and web services
  • System access - Controlled access to databases and file systems
  • Webhook handling - Process inbound and send outbound webhooks
  • Custom implementations - Build domain-specific tools for your use case

Tools enable your tasks and agents to interact with external systems and perform real-world operations.

Entities

Entities are stateful, persistent components that maintain state across restarts and failures.

They provide object-oriented patterns with automatic state management.

What entities enable:

  • Maintain long-lived state for users, sessions, or entities
  • Provide serialized access per object instance (no race conditions)
  • Implement entity-specific business logic and operations
  • Cache frequently accessed data with automatic persistence
  • Build stateful components like shopping carts or user profiles

Key features:

  • Persistent state - Object state survives crashes and restarts
  • Serialized access - Only one method executes per object at a time
  • Automatic routing - Objects are consistently routed to the same partition
  • LRU caching - Inactive objects are evicted from memory but state persists
  • Method invocation - Call object methods like regular function calls

Entities bridge the gap between stateless functions and stateful applications, perfect for entity-centric logic.

How They Work Together

These building blocks compose into reliable, durable applications:

  1. Tasks provide the durable execution foundation
  2. Workflows coordinate multiple tasks and manage dependencies
  3. Agents add AI capabilities and intelligent reasoning
  4. Tools enable interaction with external systems and data
  5. Entities maintain persistent state for entities and sessions

Whether you’re building a simple data processing pipeline or a complex multi-agent system, you combine these building blocks based on your needs.

Start with stateless tasks and add stateful entities with intelligent agents as needed.

Common Patterns

Simple durable function:

@task
def process_payment(payment_data):
    # This function will automatically retry on failure
    result = payment_api.charge(payment_data)
    return result

Multi-step workflow:

@workflow
def order_fulfillment(order_id):
    # Tasks run durably within the workflow
    payment = process_payment.run(order_id)
    inventory = reserve_inventory.run(order_id)
    shipping = schedule_shipping.run(order_id, inventory)
    return shipping

AI-powered task:

@task
def classify_support_ticket(ticket_text):
    agent = Agent(model="gpt-4")
    classification = agent.run(
        f"Classify this support ticket: {ticket_text}"
    )
    return classification

Stateful entity:

@durable.object
class CustomerSession:
    def __init__(self, customer_id: str):
        self.customer_id = customer_id
        self.conversation_history = []
    
    async def add_message(self, role: str, content: str):
        # State automatically persists across failures
        self.conversation_history.append({"role": role, "content": content})
        return len(self.conversation_history)

Advanced: Low-Level Primitives

For developers with advanced needs, AGNT5 provides direct access to the underlying durable primitives that power the high-level building blocks.

These primitives give you maximum control but require more setup. Start with high-level building blocks first.

@durable.function - Single reliable operation with exactly-once guarantees

@durable.function
async def reliable_operation(ctx, data):
    # Direct access to context API, custom retry logic, manual state management
    return await ctx.call("external_service", data)

@durable.flow - Multi-step process coordination with checkpointing

@durable.flow
async def complex_process(ctx, input_data):
    # Manual orchestration, custom error handling, parallel execution control
    step1 = await ctx.call(process_data, input_data)
    step2 = await ctx.call(transform_data, step1)
    return step2

@durable.object - Stateful entity with serialized access and persistence

@durable.object
class StatefulComponent:
    # Direct state management, custom serialization, method-level access control
    def __init__(self):
        self.state = {}

These primitives provide maximum flexibility and control for complex use cases.

Use them when you need custom durability patterns, specialized error handling, or fine-grained performance optimization.

Validate Your Understanding

Quick Check: Can you identify which building blocks you’d use for a customer support system with AI agents, persistent user sessions, and external API integrations?

Answer: Agents (AI reasoning), Entities (user sessions), Tools (APIs), Tasks (individual operations), Workflows (multi-step processes).

Next Steps

Ready to start building?