{"id":50184295,"url":"https://github.com/agentera/agently","last_synced_at":"2026-05-25T09:05:16.469Z","repository":{"id":178363927,"uuid":"660706360","full_name":"AgentEra/Agently","owner":"AgentEra","description":"[GenAI Application Development Framework]  🚀 Build GenAI application quick and easy 💬 Easy to interact with GenAI agent in code using structure data and chained-calls syntax 🧩 Use Event-Driven Flow *TriggerFlow* to manage complex GenAI working logic 🔀 Switch to any model without rewrite application code","archived":false,"fork":false,"pushed_at":"2026-05-24T15:41:55.000Z","size":44852,"stargazers_count":1574,"open_issues_count":4,"forks_count":174,"subscribers_count":23,"default_branch":"main","last_synced_at":"2026-05-24T17:26:01.239Z","etag":null,"topics":["agent","agent-based-framework","agent-framework","chatglm","claude","deepseek","ernie","framework","gemini","google-gemini","gpt","llm-agent","llm-application","llm-apps","llm-framework","llmops","llms","minimax","python"],"latest_commit_sha":null,"homepage":"http://agently.tech","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AgentEra.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":"CLA.md"}},"created_at":"2023-06-30T16:26:54.000Z","updated_at":"2026-05-24T15:41:33.000Z","dependencies_parsed_at":"2023-12-23T06:51:59.579Z","dependency_job_id":"6cc6d4e3-1e2d-4e8c-a5ca-82f41e55a053","html_url":"https://github.com/AgentEra/Agently","commit_stats":null,"previous_names":["maplemx/agently","agentera/agently"],"tags_count":55,"template":false,"template_full_name":null,"purl":"pkg:github/AgentEra/Agently","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AgentEra%2FAgently","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AgentEra%2FAgently/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AgentEra%2FAgently/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AgentEra%2FAgently/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AgentEra","download_url":"https://codeload.github.com/AgentEra/Agently/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AgentEra%2FAgently/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33467452,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-25T06:32:55.349Z","status":"ssl_error","status_checked_at":"2026-05-25T06:32:35.322Z","response_time":57,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","agent-based-framework","agent-framework","chatglm","claude","deepseek","ernie","framework","gemini","google-gemini","gpt","llm-agent","llm-application","llm-apps","llm-framework","llmops","llms","minimax","python"],"created_at":"2026-05-25T09:05:10.403Z","updated_at":"2026-05-25T09:05:16.451Z","avatar_url":"https://github.com/AgentEra.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cimg width=\"640\" alt=\"Agently\" src=\"https://github.com/user-attachments/assets/c645d031-c8b0-4dba-a515-9d7a4b0a6881\" /\u003e\n\n# Agently 4.1.3 - AI Application Runtime Framework\n\n\u003e Build AI service backends with structured outputs, observable Actions, runtime Skills, MCP capabilities, process streams, and recoverable workflows.\n\n[English](https://github.com/AgentEra/Agently/blob/main/README.md) | [中文介绍](https://github.com/AgentEra/Agently/blob/main/README_CN.md)\n\n[![license](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](https://github.com/AgentEra/Agently/blob/main/LICENSE)\n[![PyPI version](https://img.shields.io/pypi/v/agently.svg)](https://pypi.org/project/agently/)\n[![Downloads](https://img.shields.io/pypi/dm/agently.svg)](https://pypistats.org/packages/agently)\n[![GitHub Stars](https://img.shields.io/github/stars/AgentEra/Agently.svg?style=social)](https://github.com/AgentEra/Agently/stargazers)\n[![Twitter Follow](https://img.shields.io/twitter/follow/AgentlyTech?style=social)](https://x.com/AgentlyTech)\n\u003ca href=\"https://doc.weixin.qq.com/forms/AIoA8gcHAFMAScAhgZQABIlW6tV3l7QQf\"\u003e\n\u003cimg alt=\"WeChat\" src=\"https://img.shields.io/badge/WeChat%20Group-Join-brightgreen?logo=wechat\u0026style=flat-square\"\u003e\n\u003c/a\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cb\u003e\u003ca href=\"https://agently.tech/docs\"\u003eDocs\u003c/a\u003e · \u003ca href=\"#quickstart\"\u003eQuickstart\u003c/a\u003e · \u003ca href=\"#why-agently\"\u003eWhy Agently\u003c/a\u003e · \u003ca href=\"#core-capabilities\"\u003eCapabilities\u003c/a\u003e · \u003ca href=\"#architecture\"\u003eArchitecture\u003c/a\u003e · \u003ca href=\"#ecosystem\"\u003eEcosystem\u003c/a\u003e\u003c/b\u003e\n\u003c/p\u003e\n\n---\n\n## Who This README Is For\n\nAgently is for teams moving from \"the model can do it once\" to \"the application must do it reliably\":\n\n- product engineers building assistants, internal copilots, knowledge tools, operation workflows, or AI-backed APIs\n- platform teams that need clear extension points for model providers, tools, MCP servers, sandboxes, workflows, and observability\n- technical leads comparing AI frameworks for maintainability, explicit control, debuggability, and production handoff\n- coding-agent users who want a framework whose recommended patterns can be encoded as reusable project guidance\n\nThe main design question is simple: how do you keep model behavior useful while still giving application code stable contracts, observable execution, and restart-safe workflow boundaries?\n\nAgently 4.1.3 is the release where the 4.1.2 runtime foundation becomes a\ncoherent AI application runtime. One Agent turn can now connect model reasoning,\nActions, remote Skills, MCP tools, Dynamic Task DAGs, process streams, structured\noutputs, and coding-agent guidance through one engineering path. Read the\n[4.1.3 Release Notes](docs/en/development/release-notes-4.1.3.md) for the full\nrelease story.\n\n## Why Agently\n\nMany AI frameworks are strong at exploration or at assembling broad integration stacks. Agently is optimized for the engineering layer that makes model applications survive model changes, output drift, streaming UX, action execution, workflow signals, and service boundaries.\n\nAgently is a good fit when you care about:\n\n- **AI services should be runtime executions, not prompt glue** - one Agent turn can declare candidate Actions, Skills, MCP services, Dynamic Task planning, process streams, and output contracts, then execute through the same runtime surface. Read [4.1.3 Release Notes](docs/en/development/release-notes-4.1.3.md), [Agent Auto Orchestration examples](examples/agent_auto_orchestration/), and [Skills Executor examples](examples/skills_executor/).\n- **Model switching should not rewrite business logic** - Agently normalizes provider setup, prompt slots, response parsing, action execution, and response reading into one request/runtime contract. Read [Model Setup](docs/en/start/model-setup.md), [Models Overview](docs/en/models/overview.md), and [Requests Overview](docs/en/requests/overview.md).\n- **Structured output should be a framework guarantee, not only a provider feature** - `.output(...)` schemas, required field extraction, parser feedback, retries, `ensure_keys`, `ensure_all_keys`, and validation handlers work together inside Agently. Read [Schema as Prompt](docs/en/requests/schema-as-prompt.md), [Output Control](docs/en/requests/output-control.md), and examples in [`examples/basic/`](examples/basic/).\n- **Streaming should expose structure before the final token** - `instant` mode lets consumers react to structured fields while the model is still streaming, which is useful for UI updates, SSE routes, and workflow signals. Read [Model Response](docs/en/requests/model-response.md), [FastAPI Service Exposure](docs/en/services/fastapi.md), and [`examples/fastapi/`](examples/fastapi/).\n- **Actions should be observable and model-portable** - local functions, built-in actions, MCP servers, shell/Python/Node/SQLite/workspace helpers, and custom executors produce structured records and can share one Action Runtime. Read [Action Runtime](docs/en/actions/action-runtime.md), [MCP](docs/en/actions/mcp.md), and [`examples/action_runtime/`](examples/action_runtime/).\n- **Skills should be runtime capabilities, not inline prompt snippets** - `agent.use_skills(...)` can declare local or remote Skill sources; the Skills Executor discovers, installs, selects, mounts MCP/script capabilities, streams diagnostics, and executes only when the planner needs them. Read [Skills Executor](docs/en/development/skills-executor.md) and [`examples/skills_executor/`](examples/skills_executor/).\n- **Execution dependencies should have lifecycle owners** - Execution Environment providers manage reusable resources such as MCP processes, browser sessions, shell/Python/Node runtimes, SQLite handles, and sandboxes. Read [Execution Environment](docs/en/actions/execution-environment.md) and [`examples/execution_environment/`](examples/execution_environment/).\n- **Generated plans should become validated task graphs** - Dynamic Task turns model-generated or app-generated DAG data into validated, observable task execution through `Agently.create_dynamic_task(...)`. Read [Dynamic Task](docs/en/dynamic-task/README.md) and [`examples/dynamic_task/`](examples/dynamic_task/).\n- **Workflows should be signal-driven, not just graph-shaped** - TriggerFlow supports events, fan-out, runtime streams, pause/resume, save/load, sub-flows, and close snapshots; `instant` structured output can become workflow input without waiting for the whole response. Read [TriggerFlow Overview](docs/en/triggerflow/overview.md), [Events and Streams](docs/en/triggerflow/events-and-streams.md), and [`examples/trigger_flow/`](examples/trigger_flow/).\n- **Common model-app patterns should be composable** - router, To-Do/dependency execution, planning, reflection, evaluator/reviser, and multi-agent collaboration can be built from the same request/action/signal primitives. Read [Playbooks](docs/en/playbooks/overview.md), [TriggerFlow Model Integration](docs/en/triggerflow/model-integration.md), and [`examples/step_by_step/`](examples/step_by_step/).\n- **Services should keep clean project boundaries** - async APIs, FastAPI helpers, settings files, prompt files, DevTools observation, and companion coding-agent skills fit non-trivial projects. Read [Project Framework](docs/en/start/project-framework.md), [FastAPI Service Exposure](docs/en/services/fastapi.md), and [Observability](docs/en/observability/overview.md).\n\nCurrent framework version: `4.1.3`.\n\nPython: `\u003e=3.10`.\n\n## Framework Positioning\n\nThe point is not that other frameworks are wrong. They choose different centers of gravity.\n\n| Framework | Primary strength | Where Agently is intentionally different |\n|---|---|---|\n| LangChain | Broad integrations, prebuilt agents, and application building blocks | Agently is narrower and more system-shaped: provider adaptation, prompt slots, structured output, response parsing, action execution, settings, and observability are normalized in one request/runtime contract. See [Requests](docs/en/requests/overview.md), [Action Runtime](docs/en/actions/action-runtime.md), and [`examples/action_runtime/`](examples/action_runtime/). |\n| LangGraph | Low-level orchestration runtime for long-running, stateful agents | TriggerFlow is the orchestration layer inside Agently's model-application stack: workflow signals compose directly with structured response events, actions, runtime streams, pause/resume, execution state, and close snapshots. See [TriggerFlow Events and Streams](docs/en/triggerflow/events-and-streams.md), [Persistence and Blueprint](docs/en/triggerflow/persistence-and-blueprint.md), and [`examples/trigger_flow/`](examples/trigger_flow/). |\n| CrewAI | Multi-agent crews plus flow-controlled agent teamwork | Agently treats multi-agent collaboration as one buildable pattern on top of lower-level request, action, signal, and workflow primitives, not as the only application shape. See [Playbooks](docs/en/playbooks/overview.md) and [`examples/step_by_step/`](examples/step_by_step/). |\n| AutoGen | Conversable agents and multi-agent conversation patterns | Agently emphasizes model-output contracts, explicit action logs, signal-driven workflows, lifecycle snapshots, and service-facing execution handles over open-ended agent chat as the default boundary. |\n| Direct SDK calls | Maximum control with minimal abstraction | Agently adds reusable contracts for output parsing, actions, sessions, configuration, observability, and workflows without forcing a separate orchestration service. |\n\nUse Agently when the application needs an AI execution substrate. Stay closer to direct SDK calls when the product is only one or two simple prompts. Use a specialized multi-agent framework when natural-language agent collaboration is the main product primitive.\n\nThe practical differences show up in four layers:\n\n- **Against LangChain's integration-first style:** LangChain is strong when you want a broad, flexible set of model, tool, retrieval, and agent building blocks. Agently's bet is that production model apps need a more uniform request contract: different model providers should still feed the same prompt slots, structured parser, retry/validation path, `ModelResponse` readers, and Action Runtime. That reduces the chance that swapping the base model or provider changes the shape expected by downstream business logic. Start with [Requests Overview](docs/en/requests/overview.md) and [Action Runtime](docs/en/actions/action-runtime.md).\n- **Against provider-native structured output as the only guarantee:** Agently can use model providers, but its output quality path does not depend only on provider-side JSON schema or tool-calling parameters. The framework owns schema-as-prompt authoring, required-field extraction, parser feedback, retries, `ensure_keys`, `ensure_all_keys`, and validation handlers. That matters when the target model does not expose the same structured-output or tool-calling semantics as another provider. See [Schema as Prompt](docs/en/requests/schema-as-prompt.md) and [Output Control](docs/en/requests/output-control.md).\n- **Against graph-only orchestration:** LangGraph is strong for graph-shaped stateful agents and durable execution. TriggerFlow's core is event/signal-driven, and Agently's `instant` response mode can surface structured fields while the model is still streaming. That lets workflow signals be driven by partial structured output, action results, human input, or sub-flow state instead of waiting for a whole model response to finish. See [Model Response](docs/en/requests/model-response.md), [TriggerFlow Events and Streams](docs/en/triggerflow/events-and-streams.md), and [`examples/fastapi/`](examples/fastapi/) for streaming/service patterns.\n- **Against treating multi-agent as the framework root:** Multi-agent collaboration is useful, but in Agently it is a scenario you can build on top of requests, Actions, TriggerFlow signals, sub-flows, Session, and runtime resources. Router, To-Do/dependency execution, planning, reflection, evaluator/reviser, and agent-team patterns are all compositions over the same lower-level engineering substrate. See [Playbooks](docs/en/playbooks/overview.md), [TriggerFlow Model Integration](docs/en/triggerflow/model-integration.md), and [`examples/step_by_step/`](examples/step_by_step/).\n\n## Quickstart\n\nInstall:\n\n```bash\npip install -U agently\n```\n\nUse DeepSeek or another OpenAI-compatible hosted endpoint:\n\n```python\nfrom agently import Agently\n\nAgently.set_settings(\n    \"OpenAICompatible\",\n    {\n        \"base_url\": \"https://api.deepseek.com/v1\",\n        \"model\": \"deepseek-chat\",\n        \"auth\": \"DEEPSEEK_API_KEY\",\n        \"model_type\": \"chat\",\n        \"request_options\": {\"temperature\": 0.2},\n    },\n)\n\nagent = Agently.create_agent()\n\nresult = (\n    agent\n    .input(\"Introduce Python in one sentence and list three strengths.\")\n    .output({\n        \"intro\": (str, \"one sentence\", True),\n        \"strengths\": [(str, \"one strength\")],\n    })\n    .start(ensure_all_keys=True)\n)\n\nprint(result)\n```\n\nUse local Ollama by changing provider settings:\n\n```bash\nollama pull qwen2.5:7b\n```\n\n```python\nAgently.set_settings(\n    \"OpenAICompatible\",\n    {\n        \"base_url\": \"http://127.0.0.1:11434/v1\",\n        \"model\": \"qwen2.5:7b\",\n        \"api_key\": \"ollama\",\n        \"model_type\": \"chat\",\n    },\n)\n```\n\nUse a Model Pool when the same application needs multiple models:\n\n```python\nagent.set_settings(\"model_pool\", {\n    \"ollama-qwen2.5\": \"qwen2.5:7b\",\n    \"deepseek-v4\": \"deepseek-chat\",\n})\nagent.set_settings(\"key_pool\", {\n    \"local\": \"ollama\",\n    \"deepseek-main\": \"${ENV.DEEPSEEK_API_KEY}\",\n    \"deepseek-backup\": \"${ENV.DEEPSEEK_BACKUP_API_KEY}\",\n})\nagent.set_settings(\"key_pool_strategy\", {\n    \"qwen2.5:7b\": {\"mode\": \"fixed\", \"pool\": [\"local\"]},\n    \"deepseek-chat\": {\"mode\": \"round_robin\", \"pool\": [\"deepseek-main\", \"deepseek-backup\"]},\n})\n\nagent.activate_model(\"ollama-qwen2.5\")\n```\n\n`activate_model(...)` changes the default model key for subsequent Agent-owned\nrequests. Use `agent.create_request(model_key=\"deepseek-v4\")` for a one-off\noverride.\n\nFor file-backed settings, prefer:\n\n```python\nfrom agently import Agently\n\nAgently.load_settings(\"yaml_file\", \"settings.yaml\", auto_load_env=True)\n```\n\n## Core Capabilities\n\n### 1. Structured Requests\n\nPrompts are composed from named slots. That keeps application intent, constraints, context, and output contracts reviewable:\n\n```python\nresponse = (\n    agent\n    .role(\"You are a concise release-note writer.\")\n    .info({\"version\": \"4.1.3\", \"audience\": \"framework users\"})\n    .instruct(\"Return only facts grounded in the input.\")\n    .input(\"Summarize this release line for an engineering changelog.\")\n    .output({\n        \"headline\": (str, \"short headline\", True),\n        \"bullets\": [(str, \"one stable fact\")],\n    })\n    .get_response()\n)\n\ndata = response.result.get_data()\ntext = response.result.get_text()\nmeta = response.result.get_meta()\n```\n\nUse `get_response()` when the same model call will be inspected in more than one way.\n\n### 2. Contract-First Output Control\n\nFixed required leaves belong directly in `.output(...)` as the third tuple item:\n\n```python\nticket = (\n    agent\n    .input(\"The billing export fails for accounts with archived invoices.\")\n    .output({\n        \"category\": (str, \"billing / auth / data / unknown\", True),\n        \"severity\": (int, \"1-5\", True),\n        \"next_actions\": [(str, \"recommended action\")],\n    })\n    .start()\n)\n```\n\nUse `ensure_keys=` for conditional or runtime-dependent paths. Use `.validate(...)` or `validate_handler=` for value-level business rules. Use `ensure_all_keys=True` when the whole schema must be present.\n\nYAML and JSON prompt files can carry the same contract through `$ensure: true`, so teams can review prompt and response shape outside Python code.\n\n### 3. Structured Streaming\n\nInstant events let a UI, service, or downstream consumer react as each structured field changes:\n\n```python\nresponse = (\n    agent\n    .input(\"Explain recursion with two examples.\")\n    .output({\n        \"definition\": (str, \"one sentence\", True),\n        \"examples\": [(str, \"example with explanation\")],\n    })\n    .get_response()\n)\n\nfor event in response.get_generator(type=\"instant\"):\n    if event.path == \"definition\" and event.delta:\n        print(event.delta, end=\"\", flush=True)\n    if event.wildcard_path == \"examples[*]\" and event.is_complete:\n        print(\"\\nEXAMPLE:\", event.value)\n```\n\nThis is useful for dashboards, chat UIs, SSE responses, and workflows that need partial structured results before the final response is complete.\n\n### 4. Actions and Tool Use\n\nActions are model-callable capabilities. New code should start with `@agent.action_func` and `agent.use_actions(...)`:\n\n```python\nfrom agently import Agently\n\nagent = Agently.create_agent()\n\n@agent.action_func\ndef calculate_total(price: float, quantity: int) -\u003e float:\n    \"\"\"Calculate an order total.\"\"\"\n    return price * quantity\n\nagent.use_actions(calculate_total)\n\nresponse = (\n    agent\n    .input(\"Use the available action to calculate 19.5 * 4, then explain the result.\")\n    .get_response()\n)\n\nprint(response.result.get_text())\nprint(response.result.full_result_data[\"extra\"].get(\"action_logs\", []))\n```\n\nCommon capability helpers:\n\n```python\nagent.enable_python()\nagent.enable_shell(root=\".\", commands=[\"pwd\", \"rg\"])\nagent.enable_workspace(root=\".\", read=True, write=False)\nagent.enable_nodejs()\nagent.enable_sqlite(database=\"app.db\")\n```\n\nBuilt-in action packages:\n\n```python\nfrom agently.builtins.actions import Browse, Search\n\nagent.use_actions(Search(timeout=15, backend=\"duckduckgo\"))\nagent.use_actions(Browse())\n```\n\nUse `agent.use_mcp(...)` for MCP servers. Use `agent.register_action(..., executor=..., execution_environments=[...])` when building a custom backend with explicit managed resources.\n\nInstruction-heavy actions keep later model context compact with execution digests and artifact references. The application can read raw artifacts explicitly when it needs full code, shell output, page content, SQL rows, screenshots, or logs:\n\n```python\nrecords = agent.get_action_result()\nartifact_ref = records[0][\"artifact_refs\"][0]\n\nraw = agent.action.read_action_artifact(\n    artifact_id=artifact_ref[\"artifact_id\"],\n    action_call_id=artifact_ref[\"action_call_id\"],\n)\n```\n\nThe older `tool_func` / `use_tools` / `use_mcp` / `use_sandbox` family remains a compatibility surface, but new examples use actions.\n\n### 5. Runtime Skills\n\nSkills are reusable task guidance and capability packages. In 4.1.3, the\nrecommended application surface is `agent.use_skills(...)`: declare candidate\nSkill sources on the Agent and let the Skills Executor perform lightweight\ndiscovery, planner selection, on-demand materialization, capability mounting,\nand execution diagnostics.\n\n```python\nagent.use_skills(\n    [\n        {\"source\": \"GarethManning/education-agent-skills\"},\n        {\"source\": \"anthropics/skills\", \"subpath\": \"skills/docx\"},\n        {\"source\": \"anthropics/skills\", \"subpath\": \"skills/pptx\"},\n        {\"source\": \"anthropics/skills\", \"subpath\": \"skills/xlsx\"},\n    ],\n    mode=\"model_decision\",\n)\n\nexecution = await agent.async_run_skills_task(\n    \"Create a four-week B1 business English course package.\",\n    effort=\"normal\",\n    output={\n        \"course_plan\": (dict, \"course goals and weekly structure\", True),\n        \"teacher_guide\": (str, \"teacher-facing guide summary\", True),\n        \"progress_tracker\": ([str], \"tracking columns and checkpoints\", True),\n    },\n)\n```\n\nBusiness value: reusable Skills can turn a model call into a deliverable\nbusiness process such as an education package, research memo, QA evidence pack,\ntravel plan, or operational review. Application code stays focused on business\ninputs and output contracts instead of cloning remote repositories, parsing\nSkill files, or manually wiring each tool.\n\nSkill-declared MCP, shell, and script capabilities mount through Action Runtime\nand Execution Environment, so side effects remain observable and policy\ncontrolled. High-risk local execution requires approval or `auto_allow=True`;\nsafe pure-computation gaps can be synthesized as sandboxed Python actions, and\nbusiness-system capabilities fail closed unless a real connector is mounted.\n\n### 6. TriggerFlow Orchestration\n\nTriggerFlow is Agently's workflow layer for explicit stages, branching, fan-out, event-driven input, runtime streams, pause/resume, persistence, and restart-safe execution.\n\n```python\nimport asyncio\nfrom agently import TriggerFlow, TriggerFlowRuntimeData\n\nflow = TriggerFlow(name=\"ticket-flow\")\n\nasync def classify(data: TriggerFlowRuntimeData):\n    text = data.input[\"text\"]\n    category = \"billing\" if \"invoice\" in text.lower() else \"unknown\"\n    await data.async_set_state(\"category\", category)\n    return category\n\nasync def route(data: TriggerFlowRuntimeData):\n    category = data.input\n    await data.async_set_state(\"handler\", f\"{category}-team\")\n\nflow.to(classify).to(route)\n\nasync def main():\n    execution = flow.create_execution()\n    await execution.async_start({\"text\": \"Invoice export failed.\"})\n    snapshot = await execution.async_close()\n    print(snapshot)\n\nasyncio.run(main())\n```\n\nFor services, workers, webhooks, human review, or SSE/WebSocket routes, keep the execution handle and close it explicitly:\n\n```python\nexecution = flow.create_execution(auto_close=False)\nawait execution.async_start(initial_input)\nawait execution.async_emit(\"UserApproved\", {\"approved\": True})\nsnapshot = await execution.async_close()\n```\n\n`close()` / `async_close()` is the canonical completion path in the 4.1 line. The close snapshot is the durable result contract.\n\nTriggerFlow is the right tool when you need:\n\n| Need | TriggerFlow surface |\n|---|---|\n| Branches based on intermediate results | `if_condition`, `elif_condition`, `else_condition`, `match`, `case` |\n| Parallel work over many items | `for_each(concurrency=...)`, `batch(...)` |\n| External events or human review | `when(...)`, `emit(...)`, `pause_for(...)`, `continue_with(...)` |\n| Live UI or service output | runtime stream APIs |\n| Restart safety | `save(...)`, `load(...)`, close snapshots |\n| Reusable workflow topology | blueprint export/import |\n\n### 7. Dynamic Task\n\nDynamic Task is Agently's framework-level surface for executing model-generated or app-generated DAGs. It is an application API, not a TriggerFlow sub-API; internally the executor compiles validated task graphs to TriggerFlow so it can reuse lifecycle, stream, pause/resume, and runtime resource mechanics.\n\n```python\nfrom agently import Agently\n\nasync def local_handler(context):\n    return {\"task_id\": context.task.id, \"deps\": dict(context.dependency_results)}\n\ntask = Agently.create_dynamic_task(\n    target=\"review policy\",\n    plan={\n        \"graph_id\": \"review\",\n        \"task_schema_version\": \"task_dag/v1\",\n        \"tasks\": [\n            {\"id\": \"extract\", \"kind\": \"local\", \"binding\": \"local_handler\"},\n            {\"id\": \"final\", \"kind\": \"local\", \"binding\": \"local_handler\", \"depends_on\": [\"extract\"]},\n        ],\n        \"semantic_outputs\": {\"final\": \"final\"},\n    },\n    handlers={\"local_handler\": local_handler},\n)\nsnapshot = await task.async_start(timeout=10)\n```\n\nUse Dynamic Task when the task plan itself is data that needs planning, validation, pruning, and execution. Use TriggerFlow directly when you own a stable workflow topology in code.\n\n### 8. Session Memory\n\nSession keeps bounded multi-turn state when the problem is still one conversational thread, not a full workflow:\n\n```python\nagent.activate_session(session_id=\"user-42\")\nagent.set_settings(\"session.max_length\", 10000)\n\nreply1 = agent.input(\"My name is Alice.\").start()\nreply2 = agent.input(\"What is my name?\").start()\n```\n\nFor long-running processes, event waits, fan-out, or human approvals, put TriggerFlow above the request layer instead of stretching Session into a workflow store.\n\n### 9. Knowledge, Services, and Observability\n\nAgently includes integration surfaces around the request and workflow layers:\n\n- Knowledge base helpers for retrieval-backed context.\n- `FastAPIHelper` for POST, SSE, and WebSocket exposure of agents, requests, generators, TriggerFlow definitions, and TriggerFlow executions.\n- Observation events for request, action, execution environment, and TriggerFlow internals.\n- Optional `agently-devtools` for local observation, evaluation, playground workflows, and project scaffolding.\n\n```bash\npip install agently-devtools\nagently-devtools init my_project\n```\n\nAgently 4.1.3 recommends `agently-devtools \u003e=0.1.5,\u003c0.2.0`.\n\n## Architecture\n\n### Layer Model\n\nAgently organizes AI application code into explicit layers. The layers can be used independently, but they are designed to compose:\n\n```mermaid\ngraph TB\n    App[\"Application and business logic\"]\n    Settings[\"Settings files and environment\"]\n    Prompt[\"Prompt slots and output schema\"]\n    Agent[\"Agent request layer\"]\n    Model[\"Model requester plugins\"]\n    Response[\"ModelResponse: text, data, meta, stream\"]\n    Action[\"Action Runtime: planning, dispatch, logs\"]\n    Env[\"Execution Environment: MCP, Python, Bash, Node, Browser, SQLite\"]\n    Flow[\"TriggerFlow: branch, fan-out, stream, pause/resume, persist\"]\n    Observe[\"Observation events and DevTools\"]\n\n    App --\u003e Settings\n    App --\u003e Agent\n    Settings --\u003e Agent\n    Prompt --\u003e Agent\n    Agent --\u003e Model\n    Model --\u003e Response\n    Agent --\u003e Action\n    Action --\u003e Env\n    App --\u003e Flow\n    Flow --\u003e Agent\n    Agent --\u003e Observe\n    Action --\u003e Observe\n    Env --\u003e Observe\n    Flow --\u003e Observe\n```\n\n### Action Stack\n\nAction Runtime separates planning, loop orchestration, backend execution, and managed resource lifecycle:\n\n```mermaid\ngraph LR\n    Agent[\"Agent\"]\n    Facade[\"Action facade\"]\n    Runtime[\"ActionRuntime plugin\\nplanning and call normalization\"]\n    Flow[\"ActionFlow plugin\\naction loop and orchestration bridge\"]\n    Executor[\"ActionExecutor plugin\\nfunction, MCP, sandbox, Search/Browse, custom\"]\n    Env[\"ExecutionEnvironmentProvider\\nresource lifecycle\"]\n    Logs[\"action_logs and artifacts\"]\n\n    Agent --\u003e Facade\n    Facade --\u003e Runtime\n    Runtime --\u003e Flow\n    Flow --\u003e Env\n    Flow --\u003e Executor\n    Executor --\u003e Logs\n```\n\nExtension points:\n\n| Layer | Extension point |\n|---|---|\n| Agent | custom agent extension and lifecycle hooks |\n| Request | prompt generator, model requester, response parser |\n| Actions | `ActionRuntime`, `ActionFlow`, `ActionExecutor` |\n| Managed resources | `ExecutionEnvironmentProvider` |\n| Workflow | TriggerFlow chunks, conditions, events, runtime stream, persistence |\n| Observation | event hookers, sinks, DevTools bridge |\n\n## Project Shape\n\nFor anything beyond a small script, keep settings, prompts, actions, flows, and service code separate:\n\n```text\nmy-agently-app/\n  pyproject.toml\n  .env\n  settings.yaml\n  prompts/\n    summarize.yaml\n    triage.yaml\n  app/\n    agents.py\n    actions.py\n    api.py\n    main.py\n  flows/\n    triage.py\n  tests/\n    test_triage_flow.py\n```\n\n`settings.yaml`:\n\n```yaml\nplugins:\n  ModelRequester:\n    OpenAICompatible:\n      base_url: ${ENV.OPENAI_BASE_URL}\n      api_key: ${ENV.OPENAI_API_KEY}\n      model: ${ENV.OPENAI_MODEL}\ndebug: false\n```\n\nLoad at startup:\n\n```python\nfrom agently import Agently\n\nAgently.load_settings(\"yaml_file\", \"settings.yaml\", auto_load_env=True)\n```\n\nPrompt files can carry prompt slots and output contracts:\n\n```yaml\n.request:\n  instruct: |\n    You are a concise editor. Keep facts intact.\n  output:\n    title:\n      $type: str\n      $ensure: true\n    body:\n      $type: str\n      $ensure: true\n```\n\n## Examples\n\nRecommended model-app examples call a real model through DeepSeek or local Ollama and include an `Expected key output` source comment with stable key values from one real run.\n\nUseful entry points:\n\n| Directory | Use it for |\n|---|---|\n| `examples/cookbook/` | model-backed application patterns |\n| `examples/agent_auto_orchestration/` | one Agent turn coordinating Actions, Skills, Dynamic Task, and process streams |\n| `examples/skills_executor/` | remote Skills, effort-aware planning, MCP/script mounting, and model pool examples |\n| `examples/action_runtime/` | function, MCP, sandbox, and plugin action examples |\n| `examples/execution_environment/` | managed Python, shell, Node, SQLite, Browser, and provider lifecycle examples |\n| `examples/dynamic_task/` | validated Dynamic Task DAG planning and execution examples |\n| `examples/trigger_flow/` | focused TriggerFlow mechanics |\n| `examples/builtin_actions/` | Search/Browse package examples |\n| `examples/fastapi/` | service exposure examples |\n| `examples/devtools/` | optional DevTools observation examples |\n\nArchived examples live under `examples/archived/` and are compatibility references, not the recommended starting point for new apps.\n\n## Ecosystem\n\n### Agently Skills\n\nAgently-Skills gives coding agents current Agently implementation guidance.\n\n- Repository: https://github.com/AgentEra/Agently-Skills\n- Current catalog generation: `v2`\n- Recommended bundle: `app`\n- Agently 4.1.3 compatibility: Skills authoring protocol `agently-skills.authoring.v2`\n\nUse it when asking Codex, Claude Code, Cursor, or another coding agent to implement Agently patterns.\n\n### Agently DevTools\n\n`agently-devtools` is optional and covers local observation, evaluation, interactive wrappers, and project scaffolding.\n\n```bash\npip install agently-devtools\nagently-devtools init my_project\n```\n\n### Integrations\n\n| Integration | What it enables |\n|---|---|\n| `agently.integrations.chromadb` | `ChromaCollection` knowledge-base workflows |\n| `agently.integrations.fastapi` | POST, SSE, and WebSocket service exposure |\n| OpenAI-compatible requester | OpenAI, DeepSeek, Qwen, Ollama, Kimi, GLM, MiniMax, Doubao, SiliconFlow, Groq, ERNIE, Gemini-via-OpenAI |\n| Anthropic-compatible requester | Claude through Anthropic's native API |\n\n## FAQ\n\n**What makes Agently different from direct SDK calls?**\n\nDirect SDK calls are excellent when the app only needs a small number of prompts. Agently adds contracts around those calls: prompt slots, output parsing, validation, retries, response reuse, action logs, session memory, configuration, service helpers, and TriggerFlow.\n\n**How is Agently different from LangChain?**\n\nLangChain provides broad integrations, prebuilt agents, and flexible building blocks. Agently is narrower and more opinionated about the model request boundary: provider setup, prompt slots, structured output, parser feedback, retries, validation, response reuse, action execution, settings, and observability are designed to line up as one contract. The goal is to let teams change the underlying model or provider without forcing downstream business logic to relearn output or tool-call shape.\n\n**How is Agently different from LangGraph?**\n\nLangGraph is strong when the central problem is graph-based agent state and durable execution. TriggerFlow is designed as Agently's signal-driven workflow layer: model-side `instant` structured events, action results, external events, pause/resume, runtime stream items, execution state, and close snapshots can all participate in the same orchestration story.\n\n**How is Agently different from CrewAI or AutoGen?**\n\nCrewAI and AutoGen are strong choices when the primary design is collaboration among agents. Agently is a lower-level application framework: multi-agent collaboration can be built as one pattern on top of structured model requests, Actions, TriggerFlow signals, sub-flows, Session, runtime resources, and service-facing execution handles.\n\n**Do I need TriggerFlow for every multi-step task?**\n\nNo. Use plain Python or async functions for simple linear work. Use TriggerFlow when you need branches, fan-out, external events, pause/resume, runtime stream, persistence, or restart-safe execution.\n\n**Can I keep using older tool APIs?**\n\nYes. The old tool family remains a compatibility surface and maps into the current action runtime. New code should prefer `@agent.action_func`, `agent.use_actions(...)`, and the `enable_*` helpers.\n\n**How do I deploy an Agently service?**\n\nUse the async request APIs directly or wrap agents, requests, generators, TriggerFlow definitions, or TriggerFlow executions with `FastAPIHelper`. See the FastAPI docs and `examples/fastapi/`.\n\n## Documentation\n\n| Resource | Link |\n|---|---|\n| Documentation (EN) | https://agently.tech/docs |\n| Documentation (中文) | https://agently.cn/docs |\n| Quickstart | https://agently.tech/docs/en/start/quickstart.html |\n| Model Setup | https://agently.tech/docs/en/start/model-setup.html |\n| Project Framework | https://agently.tech/docs/en/start/project-framework.html |\n| Output Control | https://agently.tech/docs/en/requests/output-control.html |\n| Model Response and Streaming | https://agently.tech/docs/en/requests/model-response.html |\n| Session Memory | https://agently.tech/docs/en/requests/session-memory.html |\n| Actions | https://agently.tech/docs/en/actions/overview.html |\n| Execution Environment | https://agently.tech/docs/en/actions/execution-environment.html |\n| TriggerFlow | https://agently.tech/docs/en/triggerflow/overview.html |\n| FastAPI Helper | https://agently.tech/docs/en/services/fastapi.html |\n| Observability | https://agently.tech/docs/en/observability/overview.html |\n| Coding Agents | https://agently.tech/docs/en/development/coding-agents.html |\n| Agently Skills | https://github.com/AgentEra/Agently-Skills |\n\n## Compatibility Notes\n\n- The current package version is `4.1.3`.\n- The current release manifest is `compatibility/releases/4.1.3.json`.\n- Development-line planning belongs in `compatibility/in-development.json`; do not treat planned future versions as released.\n- README examples use the current Action and TriggerFlow close-snapshot paths.\n- Deprecated APIs emit warnings once per Python process unless `runtime.show_deprecation_warnings` is disabled.\n\n## Community\n\n- Discussions: https://github.com/AgentEra/Agently/discussions\n- Issues: https://github.com/AgentEra/Agently/issues\n- WeChat group: https://doc.weixin.qq.com/forms/AIoA8gcHAFMAScAhgZQABIlW6tV3l7QQf\n- Twitter / X: https://x.com/AgentlyTech\n\n## License\n\nAgently follows an open-core model:\n\n- Open-source core: [Apache 2.0](LICENSE)\n- Trademark usage policy: [TRADEMARK.md](TRADEMARK.md)\n- Contributor rights agreement: [CLA.md](CLA.md)\n- Enterprise extensions and services: separate commercial agreements\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagentera%2Fagently","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fagentera%2Fagently","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagentera%2Fagently/lists"}