DOCSEARCHbyAlgolia
Submit Docs

Agently AI Application Framework

repository·main·Indexed 22 days ago

https://github.com/agentera/agently

An AI application runtime framework (version 4.1.4.6) for building production-ready AI services. It provides tools for stable structured outputs, observable actions, and durable workflows, featuring TaskDAG for compact task execution, TriggerFlow for multi-step orchestration, and a Knowledge system for Retrieval-Augmented Generation (RAG). The framework includes compatibility layers for OpenAI and Anthropic providers and a multi-layer observability architecture comprising an Event Center, runtime streams, and DevTools.

Tokens
215.8K
Snippets
443
Records
849
Agent score
81%

What's inside agently

  1. Overview of making reliable model requests in Agently

    main

    Agently provides a structured framework for making single model requests reliable. The request lifecycle is managed through several interconnected capabilities:

    • Basic Request Chain: The fundamental flow of a request.
    • Prompt Management: Using slots, scope, and YAML/JSON files to manage prompts.
    • Schema as Prompt: Authoring structured output schemas directly.
    • Output Control: Mechanisms to ensure, validate, retry, and monitor events.
    • Model Response Handling: Reusing responses and accessing text, data, meta, or streams.
    • Session Memory: Managing Session objects, multi-turn history, windowing, and import/export.
    • Context Engineering: Organizing where session, info, KB (Knowledge Base), and tool results are placed.
    • Workspace Management: Handling task context, files, and durable records for progressive disclosure and recovery.

  2. Overview of the Agently Request Lifecycle

    main

    The Agently request lifecycle covers the complete chain of a single model request. To master model requests in Agently, you should understand the following core components:

    • Prompt Management: Using slots, scopes, and YAML/JSON-based prompts.
    • Schema as Prompt: Defining structured output schemas to guide model behavior.
    • Output Control: Implementing mechanisms for ensure, validate, retry, and event handling.
    • Model Response Handling: Reusing responses and accessing text, data, meta, and streaming results.
    • Session Memory: Managing Session objects, multi-turn history, window clipping, and importing/exporting memory.
    • Context Engineering: Determining the placement of session, info, KB (Knowledge Base), and tool results.
    • Workspace Management: Using independent owner instances to handle progressive disclosure, task files, persistent records, and recovery.

  3. Overview of Agently AI Application Runtime Framework

    main

    Agently is an AI application runtime framework designed to build AI service backends with structured output, observable Actions, runtime Skills, MCP (Model Context Protocol) capabilities, process flows, and recoverable workflows.

    It is positioned as an engineering layer that optimizes for stability, maintainability, and explicit control, helping teams move from 'models occasionally working' to 'applications that must work reliably.'

    Key focus areas:

    • Unified Request/Runtime Contract: Decouples business logic from specific model providers by normalizing provider setup, prompt slots, response parsing, and action execution.
    • Guaranteed Structured Output: Provides framework-level guarantees (schema-as-prompt, field extraction, parser feedback, retries, and validation) that go beyond simple provider-native JSON schema support.
    • Observable Actions: All actions (local functions, MCP servers, Shell/Python/Node/SQLite helpers) produce structured records and share a unified Action Runtime.
    • Signal-Driven Workflows: Uses TriggerFlow to support event-driven orchestration, including fan-out, pause/resume, and sub-flows, allowing workflows to react to partial structured outputs before a model response is complete.
    • Resource Lifecycle Management: Manages execution resources like MCP processes, browser sessions, and sandboxes through dedicated providers.

  4. Navigate Agently reference documentation

    main

    The Agently reference documentation is organized to help you understand core concepts and capability boundaries. Use the following guides to navigate the framework:

    • Capability Map: Use this to find documentation based on your specific goal (e.g., "I want to do X").
    • Execution Layer Selection: Use this to decide between ModelRequest, AgentExecution, TaskDAG, and TriggerFlow based on your application's complexity.
    • Blocks Lifecycle: Use this to understand the lifecycle of execution components, including ExecutionPlan, PlanBlock, ExecutionBlock, TriggerFlow lowering, Context read, TaskDAG evidence, and host guards.
    • Glossary: Use this to ensure you are using the correct terminology, API names, and migration guidance.

  5. Available Agently Case Study Patterns

    main

    Agently offers several pre-defined patterns for common AI application scenarios. You can choose a case study based on the combination of components required for your task:

    • Daily News Collector: Uses TriggerFlow + tool + structured output + scheduled tasks.
    • Talk to Control: Uses conversational agent + actions on domain objects + streaming.
    • Knowledge Base (KB) Dialog: Uses embedding + retrieval + session memory + structured responses.
    • PRD to Test Cases: Uses long input structured output + ensure mandatory fields + segmented streaming.
    • Survey Dialog: Uses multi-turn session + dynamic prompt + branching follow-ups.

    Recommended starting point for beginners: Start with the Daily News Collector as it covers the widest range of core components with minimal complexity.

  6. Explore Agently capabilities and execution layers

    main

    The Agently reference documentation is organized into four main areas to help you navigate the framework's capabilities and architectural layers:

    • Capability Map: Use this to find specific implementation pages based on your functional requirements ("what I want to do").
    • Execution Layer Selection: Guidance on choosing the appropriate abstraction level for your use case among ModelRequest, AgentExecution, TaskDAG, and TriggerFlow.
    • Blocks Lifecycle: Detailed technical documentation on how the framework manages execution, covering ExecutionPlan, PlanBlocks, ExecutionBlocks, TriggerFlow lowering, Context reads, TaskDAG evidence, and host guards.
    • Glossary: A central source for shared terminology, exact API names, and migration guidance.

  7. Agently Framework Overview

    main

    Agently is an AI application runtime framework designed to transition AI development from simple model prototyping to maintainable, production-ready applications. It provides a structured environment for:

    • Normalized Model Requests: Standardizing how you interact with different LLM providers.
    • Structured Outputs: Ensuring stable, schema-based responses.
    • Prompt & Response Contracts: Defining clear boundaries for AI execution.
    • Observable Action Calls: Tracking tool and function calls via Action records.
    • Service Exposure: Turning AI logic into deployable services (e.g., via FastAPI).
    • TriggerFlow: Orchestrating long-running, stateful, and event-driven workflows with persistence.

    Agently is best suited for projects that require clear execution boundaries, verifiable data returns, and decoupled prompt management.

  8. Available Agently Cookbook patterns

    main

    The cookbook provides several implementation patterns for common AI application designs:

    • Action loop (01_action_loop_math_model.py): The model plans real Action calls and replies based on the results of those actions.
    • Router (02_router_branching_model.py): The model classifies intent, stores the route in the execution state, and dispatches to a specialized model-backed branch.
    • Concurrent Task DAG (03_todo_concurrent_model.py): Uses a dynamic Task to validate an application-submitted TaskDAG, which is then executed by a TaskDAGExecutor with bounded concurrency.
    • Reflection (04_reflection_loop_model.py): The model generates, evaluates, and revises content within a defined maximum number of rounds.
    • Action policy and sandbox (05_safe_shell_policy_model.py): Demonstrates how to use agent.enable_shell(...) and how the system observes/blocks commands based on security policies.

  9. Understand Agently Observability options

    main

    Agently provides several ways to observe and interact with your AI applications depending on your needs:

    • Event Center: Use this for framework-level observation events and managing compatibility rules.
    • TriggerFlow runtime stream: Use this to receive live data streams from the runtime or to change flow control using emit and when mechanisms.
    • DevTools: Use this for an observation bridge, evaluation bridge, and interactive wrappers to debug and evaluate your agents.
    • Coding-agent guidance: Specialized guidance for developers building with agents.

  10. What is a Knowledge Base in Agently

    main

    In Agently, a Knowledge Base (KB) is a system composed of three parts: a vector store provider, an embedding provider (to convert text to vectors), and a query path to return relevant text chunks.

    Agently uses agently.integrations.chromadb.ChromaCollection as its reference implementation. The local default uses db_store_provider="sqlite" for records and Chroma when available, falling back to SQLite vector storage.

    When to use a Knowledge Base:

    • Use KB when: You need to retrieve relevant snippets from a large corpus of information per question.
    • Do NOT use KB when:
      • You want to include a small, fixed list of facts in every prompt (use info(always=True) instead).
      • You want to cache structured data across executions (use runtime_resources or external storage).
      • You want to remember conversation history (use Session Memory).

  11. What is an Execution Resource

    main

    An Execution Resource is a framework-level layer in Agently that manages the lifecycle (preparation and release) of live resources required by Actions or TriggerFlow steps.

    It handles resources such as:

    • MCP transports
    • Command runners and sandboxes
    • Browsers
    • SQLite connections
    • External process runners (e.g., Docker)

    Note for Application Developers: Most users should not interact with Agently.execution_resource directly. Instead, use high-level Agent Component helpers like agent.enable_python(...), agent.enable_sqlite(...), or built-in Actions that describe the intent. The ExecutionResource is the core lifecycle layer working behind these capabilities.

  12. What is TriggerFlow and when to use it

    main

    TriggerFlow is Agently's orchestration layer designed for complex workflows that go beyond single model calls. It sits above the action runtime (agents, tools, MCP servers) and below your application code.

    When to use TriggerFlow

    Use TriggerFlow if your requirements include:

    • Branching: Logic based on intermediate results (if_condition, match).
    • Concurrency: Processing multiple inputs via batch or for_each.
    • Event-driven logic: Triggering branches based on specific events (when(...)).
    • Long-running processes: Requiring human-in-the-loop approval (pause_for).
    • Durable execution: Needing to survive process restarts (save / load).
    • Live streaming: Emitting real-time events to a UI or SSE via the runtime stream.

    Note: If you only need a linear pipeline of 2–3 steps without fan-out, or a single model call with retries, consider plain async or a standard request instead of a flow. For model-generated or app-generated DAGs, use Agently.create_dynamic_task(...) instead.