Skip to content
Back to search

Agently

[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

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/AgentEra/Agently with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/AgentEra/Agently'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/agentera--agently/badge.svg)](/listings/agentera--agently)

HTML

<a href="/listings/agentera--agently"><img src="/api/listings/agentera--agently/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Install:

pip install -U agently

Use DeepSeek or another OpenAI-compatible hosted endpoint:

from agently import Agently

Agently.set_settings(
    "OpenAICompatible",
    {
        "base_url": "https://api.deepseek.com/v1",
        "model": "deepseek-v4-flash",
        "api_key": "${ENV.DEEPSEEK_API_KEY}",
        "model_type": "chat",
        "request_options": {
            "thinking": {"type": "disabled"},
            "temperature": 0.2,
        },
    },
)

agent = Agently.create_agent()

result = (
    agent
    .input("Introduce Python in one sentence and state three distinct strengths.")
    .output({
        "intro": (str, "one sentence", True),
        "strengths": {
            "first": (str, "first strength", True),
            "second": (str, "second strength", True),
            "third": (str, "third strength", True),
        },
    })
    .get_result()
)

print(result.get_data())

Use local Ollama by changing provider settings:

ollama pull qwen2.5:7b
Agently.set_settings(
    "OpenAICompatible",
    {
        "base_url": "http://127.0.0.1:11434/v1",
        "model": "qwen2.5:7b",
        "api_key": "ollama",
        "model_type": "chat",
    },
)

Use a Model Pool when the same application needs multiple models:

Agently.set_settings("model_pool", {
    "support-chat": "deepseek-v4-flash-prod",
    "reasoning": "deepseek-reason-prod",
})
Agently.set_settings("model_profiles", {
    "deepseek-v4-flash-prod": {
        "provider": "OpenAICompatible",
        "base_url": "https://api.deepseek.com/v1",
        "model": "deepseek-v4-flash",
        "api_key_pool": "deepseek-prod",
        "request_options": {"thinking": {"type": "disabled"}},
    },
    "deepseek-reason-prod": {
        "provider": "OpenAICompatible",
        "base_url": "https://api.deepseek.com/v1",
        "model": "deepseek-v4-flash",
        "api_key_pool": "deepseek-prod",
        "request_options": {
            "thinking": {"type": "enabled"},
            "reasoning_effort": "high",
        },
    },
})
Agently.set_settings("api_key_pools", {
    "deepseek-prod": {
        "selection": {"strategy": "round_robin"},
        "failover": {
            "strategy": "try_next",
            "max_attempts": 2,
            "retry_status_codes": [401, 403, 429],
        },
        "keys": [
            {"id": "a", "value": "${ENV.DEEPSEEK_API_KEY_A}"},
            {"id": "b", "value": "${ENV.DEEPSEEK_API_KEY_B}"},
        ],
    },
})

agent.activate_model("reasoning")

`activate_model(...)` changes the default model key for subsequent Agent-owned requests. Use `agent.create_request(model_key="support-chat")` for a one-off override.

For file-backed settings, prefer:

from agently import Agently

Agently.load_settings("yaml_file", "settings.yaml", auto_load_env=True)

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 812 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <img width="640" alt="Agently" src="https://github.com/user-attachments/assets/c645d031-c8b0-4dba-a515-9d7a4b0a6881" />
  2. # Agently 4.1.4.11 - AI Application Runtime Framework
  3. > Build AI service backends with structured outputs, observable Actions, runtime Skills, MCP capabilities, process streams, and recoverable workflows.
  4. [English](https://github.com/AgentEra/Agently/blob/main/README.md) | [中文介绍](https://github.com/AgentEra/Agently/blob/main/README_CN.md)
  5. [![license](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](https://github.com/AgentEra/Agently/blob/main/LICENSE)
  6. [![PyPI version](https://img.shields.io/pypi/v/agently.svg)](https://pypi.org/project/agently/)
  7. [![Downloads](https://img.shields.io/pypi/dm/agently.svg)](https://pypistats.org/packages/agently)
  8. [![GitHub Stars](https://img.shields.io/github/stars/AgentEra/Agently.svg?style=social)](https://github.com/AgentEra/Agently/stargazers)
  9. [![Twitter Follow](https://img.shields.io/twitter/follow/AgentlyTech?style=social)](https://x.com/AgentlyTech)
  10. <a href="https://doc.weixin.qq.com/forms/AIoA8gcHAFMAScAhgZQABIlW6tV3l7QQf">
  11. <img alt="WeChat" src="https://img.shields.io/badge/WeChat%20Group-Join-brightgreen?logo=wechat&style=flat-square">
  12. </a>
  13. <p align="center">
  14. <b><a href="https://agently.tech/docs">Docs</a> · <a href="#quickstart">Quickstart</a> · <a href="#why-agently">Why Agently</a> · <a href="#core-capabilities">Capabilities</a> · <a href="#architecture">Architecture</a> · <a href="#ecosystem">Ecosystem</a></b>
  15. </p>
  16. ---
  17. ## Who This README Is For
  18. Agently is for teams moving from "the model can do it once" to "the application must do it reliably":
  19. - product engineers building assistants, internal copilots, knowledge tools, operation workflows, or AI-backed APIs
  20. - platform teams that need clear extension points for model providers, tools, MCP servers, sandboxes, workflows, and observability
  21. - technical leads comparing AI frameworks for maintainability, explicit control, debuggability, and production handoff
  22. - coding-agent users who want a framework whose recommended patterns can be encoded as reusable project guidance
  23. The 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?
  24. Agently 4.1.4.11 improves state copying and nested data sanitization. It still supports Python 3.10 and shows a startup notice about the Python 3.11 minimum in Agently 4.2.
  25. Agently 4.1.4.10 fixes long-task file delivery and supports FastMCP 3/4 while retaining the existing 4.1 APIs. Content accuracy and business completion judgment still require application-level review.
  26. The existing one-run Agent composition remains available:
  27. Actions and Skills preserve `AgentExecution` fluent typing, built-in Execution,
  28. effort, strategy, Action protocol, and concurrency choices appear in IDEs, and
  29. stable interaction, review, final validation, and artifact delivery APIs now have
  30. complete examples. It also adds accepted retry-stream replay, fail-closed model
  31. aliases, execution-scoped Skills, programmatic Action calling, and clearer
  32. concurrent debug output. Read the
  33. [4.1.4.11 Release Notes](docs/en/development/release-notes-4.1.4.11.md), [4.1.4.10 Release Notes](docs/en/development/release-notes-4.1.4.10.md), [4.1.4.9 Release Notes](docs/en/development/release-notes-4.1.4.9.md), [4.1.4.8 Release Notes](docs/en/development/release-notes-4.1.4.8.md),
  34. [4.1.4.7 Release Notes](docs/en/development/release-notes-4.1.4.7.md),
  35. [4.1.4.6 Release Notes](docs/en/development/release-notes-4.1.4.6.md),
  36. [4.1.4.5 Release Notes](docs/en/development/release-notes-4.1.4.5.md),
  37. [4.1.4.4 Release Notes](docs/en/development/release-notes-4.1.4.4.md),
  38. [4.1.4.3 Release Notes](docs/en/development/release-notes-4.1.4.3.md), and
  39. [4.1.4 Release Notes](docs/en/development/release-notes-4.1.4.md) for the
  40. current release and upgrade path.
  41. ## Why Agently
  42. Many 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.
  43. Agently is a good fit when you care about:
  44. - **AI services should be runtime executions, not prompt glue** - `AgentExecution` owns one run's prompt, strategy, Actions, Skill bindings, process stream, TaskContext evidence, and result views across direct, flat, and TaskBoard strategies. Read [4.1.4.8 Release Notes](docs/en/development/release-notes-4.1.4.8.md), [4.1.4 Release Notes](docs/en/development/release-notes-4.1.4.md), and [Agent Auto Orchestration examples](examples/agent_auto_orchestration/).
  45. - **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).
  46. - **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/).
  47. - **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/).
  48. - **Actions should be observable and model-portable** - local functions, built-in actions, MCP servers, shell/Python/Node/SQLite/TaskWorkspace 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/).
  49. - **Skills should be immutable guidance, not a hidden execution route** - `SkillLibrary` owns installed revisions, AgentExecution owns selection and exact-revision binding, and TaskContext owns disclosure. `Agently.skills_executor` remains management/context compatibility only. Read [Skills](docs/en/development/skills-executor.md) and [`examples/skills_executor/`](examples/skills_executor/).
  50. - **Execution dependencies should have lifecycle owners** - Execution Resource providers manage reusable resources such as MCP processes, browser sessions, shell/Python/Node runtimes, SQLite handles, and sandboxes. Built-in gVisor, Seatbelt, and Landlock candidates stay inactive until selected and probe their external mechanism on demand. Read [Execution Resource](docs/en/actions/execution-environment.md) and [`examples/execution_resource/`](examples/execution_resource/).
  51. - **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/).
  52. - **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/).
  53. - **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/).
  54. - **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).
  55. Current framework version: `4.1.4.8`.
  56. Python: `>=3.10`.
  57. ## Framework Positioning
  58. The point is not that other frameworks are wrong. They choose different centers of gravity.
  59. | Framework | Primary strength | Where Agently is intentionally different |
  60. |---|---|---|
  61. | 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/). |
  62. | 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/). |
  63. | 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/). |
  64. | 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. |
  65. | 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. |
  66. Use 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.
  67. The practical differences show up in four layers:
  68. - **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, reusable result 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).
  69. - **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).
  70. - **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.
  71. - **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/).
  72. ## Quickstart
  73. Install:
  74. ```bash
  75. pip install -U agently
  76. ```
  77. Use DeepSeek or another OpenAI-compatible hosted endpoint:
  78. ```python
  79. from agently import Agently
  80. Agently.set_settings(
  81. "OpenAICompatible",
  82. {
  83. "base_url": "https://api.deepseek.com/v1",
  84. "model": "deepseek-v4-flash",
  85. "api_key": "${ENV.DEEPSEEK_API_KEY}",
  86. "model_type": "chat",
  87. "request_options": {
  88. "thinking": {"type": "disabled"},
  89. "temperature": 0.2,
  90. },
  91. },
  92. )
  93. agent = Agently.create_agent()
  94. result = (
  95. agent
  96. .input("Introduce Python in one sentence and state three distinct strengths.")
  97. .output({
  98. "intro": (str, "one sentence", True),
  99. "strengths": {
  100. "first": (str, "first strength", True),
  101. "second": (str, "second strength", True),
  102. "third": (str, "third strength", True),
  103. },
  104. })
  105. .get_result()
  106. )
  107. print(result.get_data())
  108. ```
  109. Use local Ollama by changing provider settings:
  110. ```bash
  111. ollama pull qwen2.5:7b
  112. ```
  113. ```python
  114. Agently.set_settings(
  115. "OpenAICompatible",
  116. {
  117. "base_url": "http://127.0.0.1:11434/v1",
  118. "model": "qwen2.5:7b",
  119. "api_key": "ollama",
  120. "model_type": "chat",
  121. },
  122. )
  123. ```
  124. Use a Model Pool when the same application needs multiple models:
  125. ```python
  126. Agently.set_settings("model_pool", {
  127. "support-chat": "deepseek-v4-flash-prod",
  128. "reasoning": "deepseek-reason-prod",
  129. })
  130. Agently.set_settings("model_profiles", {
  131. "deepseek-v4-flash-prod": {
  132. "provider": "OpenAICompatible",
  133. "base_url": "https://api.deepseek.com/v1",
  134. "model": "deepseek-v4-flash",
  135. "api_key_pool": "deepseek-prod",
  136. "request_options": {"thinking": {"type": "disabled"}},
  137. },
  138. "deepseek-reason-prod": {
  139. "provider": "OpenAICompatible",
  140. "base_url": "https://api.deepseek.com/v1",
  141. "model": "deepseek-v4-flash",
  142. "api_key_pool": "deepseek-prod",
  143. "request_options": {
  144. "thinking": {"type": "enabled"},
  145. "reasoning_effort": "high",
  146. },
  147. },
  148. })
  149. Agently.set_settings("api_key_pools", {
  150. "deepseek-prod": {
  151. "selection": {"strategy": "round_robin"},
  152. "failover": {
  153. "strategy": "try_next",
  154. "max_attempts": 2,
  155. "retry_status_codes": [401, 403, 429],
  156. },
  157. "keys": [
  158. {"id": "a", "value": "${ENV.DEEPSEEK_API_KEY_A}"},
  159. {"id": "b", "value": "${ENV.DEEPSEEK_API_KEY_B}"},
  160. ],
  161. },
  162. })
  163. agent.activate_model("reasoning")
  164. ```
  165. `activate_model(...)` changes the default model key for subsequent Agent-owned
  166. requests. Use `agent.create_request(model_key="support-chat")` for a one-off
  167. override.
  168. For file-backed settings, prefer:
  169. ```python
  170. from agently import Agently
  171. Agently.load_settings("yaml_file", "settings.yaml", auto_load_env=True)
  172. ```
  173. ## Core Capabilities
  174. ### 1. Structured Requests
  175. Prompts are composed from named slots. That keeps application intent, constraints, context, and output contracts reviewable:
  176. ```python
  177. result = (
  178. agent
  179. .role("You are a concise release-note writer.")
  180. .info({"version": "4.1.4.8", "audience": "framework users"})
  181. .instruct("Return only facts grounded in the input.")
  182. .input("Summarize this release line for an engineering changelog.")
  183. .output({
  184. "headline": (str, "short headline", True),
  185. "bullets": [(str, "one stable fact")],
  186. })
  187. .get_result()
  188. )
  189. data = result.get_data()
  190. full_data = result.get_full_data()
  191. text = result.get_text()
  192. meta = result.get_meta()
  193. ```
  194. Use `get_result()` when the same model call will be inspected in more than one
  195. way. For `AgentExecutionResult`, `get_data()` returns the business result across
  196. direct, flat, and TaskBoard strategies; use `get_full_data()` only when the
  197. caller needs the full route/task envelope. `get_text()` remains the user-facing
  198. final-text view.
  199. ### 2. Contract-First Output Control
  200. Fixed required leaves belong directly in `.output(...)` as the third tuple item:
  201. ```python
  202. ticket = (
  203. agent
  204. .input("The billing export fails for accounts with archived invoices.")
  205. .output({
  206. "category": (str, "billing / auth / data / unknown", True),
  207. "severity": (int, "1-5", True),
  208. "next_actions": [(str, "recommended action")],
  209. })
  210. .start()
  211. )
  212. ```
  213. Use `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.
  214. YAML and JSON prompt files can carry the same contract through `$ensure: true`, so teams can review prompt and response shape outside Python code.
  215. ### 3. Structured Streaming
  216. Instant events let a UI, service, or downstream consumer react as each structured field changes:
  217. ```python
  218. result = (
  219. agent
  220. .input("Explain recursion with two examples.")
  221. .output({
  222. "definition": (str, "one sentence", True),
  223. "examples": [(str, "example with explanation")],
  224. })
  225. .get_result()
  226. )
  227. for event in result.get_generator(type="instant"):
  228. if event.path == "definition" and event.delta:
  229. print(event.delta, end="", flush=True)
  230. if event.wildcard_path == "examples[*]" and event.is_complete:
  231. print("\nEXAMPLE:", event.value)
  232. ```
  233. This is useful for dashboards, chat UIs, SSE responses, and workflows that need partial structured results before the final response is complete.
  234. Treat `instant` updates as provisional. Use `get_data()` / `async_get_data()`
  235. when the caller does not publish or parse progressive fields; draining an
  236. `instant` generator without consuming its updates only wastes work. Final
  237. validation must complete before irreversible side effects or business
  238. decisions.
  239. ### 4. Actions and Tool Use
  240. Actions are model-callable capabilities. New code should start with `@agent.action_func` and `agent.use_actions(...)`:
  241. ```python
  242. from agently import Agently
  243. agent = Agently.create_agent()
  244. @agent.action_func
  245. def calculate_total(price: float, quantity: int) -> float:
  246. """Calculate an order total."""
  247. return price * quantity
  248. agent.use_actions(calculate_total)
  249. result = (
  250. agent
  251. .input("Use the available action to calculate 19.5 * 4, then explain the result.")
  252. .get_result()
  253. )
  254. print(result.get_text())
  255. full_data = result.get_full_data()
  256. print(full_data.get("extra", {}).get("action_logs", []))
  257. ```
  258. Common capability helpers:
  259. ```python
  260. agent.enable_python()
  261. agent.enable_shell(root=".", commands=["pwd", "rg"])
  262. agent.enable_workspace(root=".", read=True, write=False)
  263. agent.enable_nodejs()
  264. agent.enable_sqlite(database="app.db")
  265. ```
  266. Built-in action packages:
  267. ```python
  268. from agently.builtins.actions import Browse, Search
  269. agent.use_actions(Search(timeout=15, backend="duckduckgo"))
  270. agent.use_actions(Browse())
  271. ```
  272. Use `agent.use_mcp(...)` for MCP servers. Use `agent.register_action(..., executor=..., execution_resources=[...])` when building a custom backend with explicit managed resources.
  273. Instruction-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:
  274. ```python
  275. turn = agent.input("Use the shell action and summarize the result.")
  276. records = agent.get_action_result(prompt=turn.prompt)
  277. artifact_ref = records[0]["artifact_refs"][0]
  278. raw = agent.action.read_action_artifact(
  279. artifact_id=artifact_ref["artifact_id"],
  280. action_call_id=artifact_ref["action_call_id"],
  281. )
  282. ```
  283. The older `tool_func` / `use_tools` / `use_mcp` / `use_sandbox` family remains a compatibility surface, but new examples use actions.
  284. ### 5. Runtime Skills
  285. Skills are reusable task guidance packages. In the current release, `SkillLibrary` owns
  286. immutable installed revisions, AgentExecution owns selection and exact-revision
  287. binding, and TaskContext owns progressive disclosure. `agent.use_skills(...)`
  288. is the normal candidate-binding surface; `agent.require_skills(...)` binds a
  289. known exact revision. `Agently.skills_executor` remains a thin compatibility
  290. facade for installation, inspection, and context projection. In 4.1.4.8, as in
  291. 4.1.4.7, its legacy TaskDAG `skill` resolver helper is not an executor-ready
  292. integration: it still needs a host adapter from the real `TaskDAGContext` before
  293. node selectors reach the compatibility projection.
  294. ```python
  295. result = (
  296. agent
  297. .use_skills(
  298. [
  299. {"source": "GarethManning/education-agent-skills"},
  300. {"source": "anthropics/skills", "subpath": "skills/docx"},
  301. {"source": "anthropics/skills", "subpath": "skills/pptx"},
  302. {"source": "anthropics/skills", "subpath": "skills/xlsx"},
  303. ],
  304. mode="model_decision",
  305. )
  306. .goal(
  307. "Create a four-week B1 business English course package.",
  308. ["Include a course plan, teacher guide, and progress tracker"],
  309. )
  310. .effort("medium")
  311. .output({
  312. "course_plan": (dict, "course goals and weekly structure", True),
  313. "teacher_guide": (str, "teacher-facing guide summary", True),
  314. "progress_tracker": ([str], "tracking columns and checkpoints", True),
  315. })
  316. .get_result()
  317. )
  318. data = await result.async_get_data()
  319. ```
  320. Business value: reusable Skills can turn a model call into a deliverable
  321. business process such as an education package, research memo, QA evidence pack,
  322. travel plan, or operational review. Application code stays focused on business
  323. inputs and output contracts instead of cloning remote repositories, parsing
  324. Skill files, or manually wiring each tool.
  325. Skill capability requirements do not authorize side effects by themselves.
  326. Host code must explicitly mount the required Actions, MCP services, or
  327. ExecutionResource providers and apply policy before execution. Unavailable,
  328. ambiguous, low-confidence, or policy-denied capabilities fail closed with
  329. diagnostics; side effects remain owned by Action Runtime, ExecutionResource,
  330. TaskWorkspace, RecordStore, or TriggerFlow.
  331. ### 6. TriggerFlow Orchestration
  332. TriggerFlow is Agently's workflow layer for explicit stages, branching, fan-out, event-driven input, runtime streams, pause/resume, persistence, and restart-safe execution.
  333. ```python
  334. import asyncio
  335. from agently import TriggerFlow, TriggerFlowRuntimeData
  336. flow = TriggerFlow(name="ticket-flow")
  337. async def classify(data: TriggerFlowRuntimeData):
  338. text = data.input["text"]
  339. category = "billing" if "invoice" in text.lower() else "unknown"
  340. await data.async_set_state("category", category)
  341. return category
  342. async def route(data: TriggerFlowRuntimeData):
  343. category = data.input
  344. await data.async_set_state("handler", f"{category}-team")
  345. flow.to(classify).to(route)
  346. async def main():
  347. execution = flow.create_execution()
  348. await execution.async_start({"text": "Invoice export failed."})
  349. snapshot = await execution.async_close()
  350. print(snapshot)
  351. asyncio.run(main())
  352. ```
  353. For services, workers, webhooks, human review, or SSE/WebSocket routes, keep the execution handle and close it explicitly:
  354. ```python
  355. execution = flow.create_execution(auto_close=False)
  356. await execution.async_start(initial_input)
  357. await execution.async_emit("UserApproved", {"approved": True})
  358. snapshot = await execution.async_close()
  359. ```
  360. `close()` / `async_close()` is the canonical completion path in the 4.1 line. The close snapshot is the durable result contract.
  361. TriggerFlow is the right tool when you need:
  362. | Need | TriggerFlow surface |
  363. |---|---|
  364. | Branches based on intermediate results | `if_condition`, `elif_condition`, `else_condition`, `match`, `case` |
  365. | Parallel work over many items | `for_each(concurrency=...)`, `batch(...)` |
  366. | External events or human review | `when(...)`, `emit(...)`, `pause_for(...)`, `continue_with(...)` |
  367. | Live UI or service output | runtime stream APIs |
  368. | Restart safety | `save(...)`, `load(...)`, close snapshots |
  369. | Reusable workflow topology | blueprint export/import |
  370. For complex services, map real serial and parallel dependencies before writing
  371. the flow. Run independent work concurrently and expose pressure controls where
  372. they are owned: host in-flight coroutine limits, TriggerFlow execution and
  373. fan-out concurrency, model rate/concurrency limits, and thread-pool sizes for
  374. blocking code.
  375. ### 7. Dynamic Task
  376. Dynamic Task is Agently's convenience surface for model-generated or
  377. application-submitted DAG data; TaskDAG owns planning, validation, resolution,
  378. and execution. It is an application API, not a TriggerFlow sub-API. By default,
  379. `TaskDAGExecutor.async_run(...)` compiles the validated DAG directly to the
  380. TriggerFlow substrate. Blocks compilation is an explicit opt-in path when the
  381. caller needs Blocks lifecycle evidence or `ExecutionBlockGraph` output.
  382. ```python
  383. from agently import Agently
  384. async def local_handler(context):
  385. return {"task_id": context.task.id, "deps": dict(context.dependency_results)}
  386. task = Agently.create_dynamic_task(
  387. target="review policy",
  388. plan={
  389. "graph_id": "review",
  390. "task_schema_version": "task_dag/v1",
  391. "tasks": [
  392. {"id": "extract", "kind": "local", "binding": "local_handler"},
  393. {"id": "final", "kind": "local", "binding": "local_handler", "depends_on": ["extract"]},
  394. ],
  395. "semantic_outputs": {"final": "final"},
  396. },
  397. handlers={"local_handler": local_handler},
  398. )
  399. snapshot = await task.async_start(timeout=10)
  400. ```
  401. Use Dynamic Task when the task plan itself is data that needs planning,
  402. validation, pruning, and execution. Never compile unvalidated runtime plan data
  403. directly into new TriggerFlow definitions. Use TriggerFlow directly when you
  404. own a stable workflow topology in trusted source code.
  405. ### 8. Session Memory
  406. Session keeps bounded multi-turn state when the problem is still one conversational thread, not a full workflow:
  407. ```python
  408. agent.activate_session(session_id="user-42")
  409. agent.set_settings("session.max_length", 10000)
  410. reply1 = agent.input("My name is Alice.").start()
  411. reply2 = agent.input("What is my name?").start()
  412. ```
  413. For long-running processes, event waits, fan-out, or human approvals, put TriggerFlow above the request layer instead of stretching Session into a workflow store.
  414. ### 9. Knowledge, Services, and Observability
  415. Agently includes integration surfaces around the request and workflow layers:
  416. - Knowledge base helpers for retrieval-backed context.
  417. - `FastAPIHelper` for POST, SSE, and WebSocket exposure of agents, requests, generators, TriggerFlow definitions, and TriggerFlow executions.
  418. - Observation events for request, action, execution environment, and TriggerFlow internals.
  419. - Optional `agently-devtools` for local observation, evaluation, playground workflows, and project scaffolding.
  420. ```bash
  421. pip install agently-devtools
  422. agently-devtools init my_project
  423. ```
  424. Agently 4.1.4.8 recommends `agently-devtools >=0.1.11,<0.2.0`.
  425. ## Architecture
  426. ### Layer Model
  427. Agently organizes AI application code into explicit layers. The layers can be used independently, but they are designed to compose:
  428. ```mermaid
  429. graph TB
  430. App["Application and business logic"]
  431. Settings["Settings files and environment"]
  432. Execution["AgentExecution: direct / flat / TaskBoard"]
  433. Request["ModelRequest: prompt and output control"]
  434. Model["Model requester plugins"]
  435. Result["AgentExecutionResult / ModelRequestResult"]
  436. Skills["SkillLibrary + AgentExecution\nimmutable revision binding"]
  437. Action["Action Runtime: planning, dispatch, logs"]
  438. Env["Execution Resource: MCP, Python, Bash, Node, Browser, SQLite"]
  439. Context["TaskContext / ContextReader\ntask information and disclosure"]
  440. TaskFiles["TaskWorkspace\ntask files and execution grants"]
  441. Records["RecordStore\nrecords, checkpoints, snapshots, events"]
  442. DAG["TaskDAG / DynamicTask\nvalidated acyclic plan data"]
  443. Flow["TriggerFlow: branch, fan-out, stream, pause/resume, persist"]
  444. Observe["RuntimeEvents and DevTools"]
  445. App --> Settings
  446. App --> Execution
  447. Settings --> Execution
  448. Execution --> Request
  449. Request --> Model
  450. Model --> Result
  451. Execution --> Result
  452. Execution --> Skills
  453. Execution --> Action
  454. Execution --> Context
  455. Execution --> TaskFiles
  456. Execution --> Records
  457. Action --> Env
  458. Action --> TaskFiles
  459. App --> DAG
  460. DAG --> Flow
  461. App --> Flow
  462. Flow --> Records
  463. Flow --> Execution
  464. Execution --> Observe
  465. Action --> Observe
  466. Env --> Observe
  467. Flow --> Observe
  468. ```
  469. ### Action Stack
  470. Action Runtime separates planning, loop orchestration, backend execution, and managed resource lifecycle:
  471. ```mermaid
  472. graph LR
  473. Agent["Agent"]
  474. Facade["Action facade"]
  475. Runtime["ActionRuntime plugin\nplanning and call normalization"]
  476. Flow["ActionFlow plugin\naction loop and orchestration bridge"]
  477. Executor["ActionExecutor plugin\nfunction, MCP, sandbox, Search/Browse, custom"]
  478. Env["ExecutionResourceProvider\nresource lifecycle"]
  479. Logs["action_logs and artifacts"]
  480. Agent --> Facade
  481. Facade --> Runtime
  482. Runtime --> Flow
  483. Flow --> Env
  484. Flow --> Executor
  485. Executor --> Logs
  486. ```
  487. Extension points:
  488. | Layer | Extension point |
  489. |---|---|
  490. | Agent | custom agent extension and lifecycle hooks |
  491. | Agent execution | strategies, lifecycle, result views, TaskContext evidence |
  492. | Request | prompt generator, model requester, response parser |
  493. | Actions | `ActionRuntime`, `ActionFlow`, `ActionExecutor` |
  494. | Managed resources | `ExecutionResourceProvider` |
  495. | Dynamic DAG | TaskDAG planner, validator, resolver, executor; DynamicTask facade |
  496. | Workflow | TriggerFlow chunks, conditions, events, runtime stream, persistence |
  497. | Observation | event hookers, sinks, DevTools bridge |
  498. ## Project Shape
  499. For anything beyond a small script, keep settings, prompts, actions, flows, and service code separate:
  500. ```text
  501. my-agently-app/
  502. pyproject.toml
  503. .env
  504. settings.yaml
  505. prompts/
  506. summarize.yaml
  507. triage.yaml
  508. app/
  509. agents.py
  510. actions.py
  511. api.py
  512. main.py
  513. flows/
  514. triage.py
  515. tests/
  516. test_triage_flow.py
  517. ```
  518. `settings.yaml`:
  519. ```yaml
  520. plugins:
  521. ModelRequester:
  522. OpenAICompatible:
  523. base_url: ${ENV.OPENAI_BASE_URL}
  524. api_key: ${ENV.OPENAI_API_KEY}
  525. model: ${ENV.OPENAI_MODEL}
  526. debug: false
  527. ```
  528. Load at startup:
  529. ```python
  530. from agently import Agently
  531. Agently.load_settings("yaml_file", "settings.yaml", auto_load_env=True)
  532. ```
  533. Prompt files can carry prompt slots and output contracts:
  534. ```yaml
  535. .request:
  536. instruct: |
  537. You are a concise editor. Keep facts intact.
  538. output:
  539. title:
  540. $type: str
  541. $ensure: true
  542. body:
  543. $type: str
  544. $ensure: true
  545. ```
  546. ## Examples
  547. Recommended 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.
  548. Useful entry points:
  549. | Directory | Use it for |
  550. |---|---|
  551. | `examples/cookbook/` | model-backed application patterns |
  552. | `examples/agent_auto_orchestration/` | one Agent turn coordinating Actions, Skills, Dynamic Task, and process streams |
  553. | `examples/skills_executor/` | remote Skills, effort-aware planning, MCP/script mounting, and model pool examples |
  554. | `examples/action_runtime/` | function, MCP, sandbox, and plugin action examples |
  555. | `examples/execution_resource/` | managed Python, shell, Node, SQLite, Browser, and provider lifecycle examples |
  556. | `examples/dynamic_task/` | validated Dynamic Task DAG planning and execution examples |
  557. | `examples/trigger_flow/` | focused TriggerFlow mechanics |
  558. | `examples/builtin_actions/` | Search/Browse package examples |
  559. | `examples/fastapi/` | service exposure examples |
  560. | `examples/devtools/` | optional DevTools observation examples |
  561. | `examples/release_pinned_usage/` | release-pinned developer usage checks; selected scripts require maintainer confirmation before usage-shape edits |
  562. Archived examples live under `examples/archived/` and are compatibility references, not the recommended starting point for new apps.
  563. ## Ecosystem
  564. ### Agently Skills
  565. Agently-Skills gives coding agents current Agently implementation guidance.
  566. - Repository: https://github.com/AgentEra/Agently-Skills
  567. - Current catalog generation: `v3`
  568. - Recommended bundle: `app`
  569. - Agently 4.1.4.8 compatibility: Skills authoring protocol `agently-skills.authoring.v3`
  570. Use it when asking Codex, Claude Code, Cursor, or another coding agent to implement Agently patterns.
  571. ### Agently DevTools
  572. `agently-devtools` is optional and covers local observation, evaluation, interactive wrappers, and project scaffolding.
  573. ```bash
  574. pip install agently-devtools
  575. agently-devtools init my_project
  576. ```
  577. ### Integrations
  578. | Integration | What it enables |
  579. |---|---|
  580. | `agently.integrations.chromadb` | `ChromaCollection` knowledge-base workflows |
  581. | `agently.integrations.fastapi` | POST, SSE, and WebSocket service exposure |
  582. | OpenAI-compatible requester | OpenAI, DeepSeek, Qwen, Ollama, Kimi, GLM, MiniMax, Doubao, SiliconFlow, Groq, ERNIE, Gemini-via-OpenAI |
  583. | Anthropic-compatible requester | Claude through Anthropic's native API |
  584. ## FAQ
  585. **What makes Agently different from direct SDK calls?**
  586. Direct 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.
  587. **How is Agently different from LangChain?**
  588. LangChain 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.
  589. **How is Agently different from LangGraph?**
  590. LangGraph 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.
  591. **How is Agently different from CrewAI or AutoGen?**
  592. CrewAI 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.
  593. **Do I need TriggerFlow for every multi-step task?**
  594. No. 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.
  595. **Can I keep using older tool APIs?**
  596. Yes. 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.
  597. **How do I deploy an Agently service?**
  598. Use the async request APIs directly or wrap agents, requests, generators, TriggerFlow definitions, or TriggerFlow executions with `FastAPIHelper`. See the FastAPI docs and `examples/fastapi/`.
  599. ## Documentation
  600. | Resource | Link |
  601. |---|---|
  602. | Documentation (EN) | https://agently.tech/docs |
  603. | Documentation (中文) | https://agently.cn/docs |
  604. | Quickstart | https://agently.tech/docs/en/start/quickstart.html |
  605. | Model Setup | https://agently.tech/docs/en/start/model-setup.html |
  606. | Project Framework | https://agently.tech/docs/en/start/project-framework.html |
  607. | Execution Layer Selection | https://agently.tech/docs/en/reference/execution-layer-selection.html |
  608. | Output Control | https://agently.tech/docs/en/requests/output-control.html |
  609. | Model Response and Streaming | https://agently.tech/docs/en/requests/model-response.html |
  610. | Session Memory | https://agently.tech/docs/en/requests/session-memory.html |
  611. | Actions | https://agently.tech/docs/en/actions/overview.html |
  612. | Execution Resource | https://agently.tech/docs/en/actions/execution-environment.html |
  613. | TriggerFlow | https://agently.tech/docs/en/triggerflow/overview.html |
  614. | FastAPI Helper | https://agently.tech/docs/en/services/fastapi.html |
  615. | Observability | https://agently.tech/docs/en/observability/overview.html |
  616. | Coding Agents | https://agently.tech/docs/en/development/coding-agents.html |
  617. | Agently Skills | https://github.com/AgentEra/Agently-Skills |
  618. ## Compatibility Notes
  619. - The current package version is `4.1.4.8`.
  620. - The current release manifest is `compatibility/releases/4.1.4.8.json`.
  621. - Development-line planning belongs in `compatibility/in-development.json`; do not treat planned future versions as released.
  622. - `AgentExecutionResult.get_data()` returns business data; callers that need status, TaskBoard, diagnostics, or other route/task internals use `get_full_data()`.
  623. - An explicitly captured `AgentExecution` represents one run. Create a fresh execution for the next request after it starts.
  624. - README examples use the current AgentExecution result, Action, TaskDAG, and TriggerFlow lifecycle paths.
  625. - Deprecated APIs emit warnings once per Python process unless `runtime.show_deprecation_warnings` is disabled.
  626. ## Community
  627. - Discussions: https://github.com/AgentEra/Agently/discussions
  628. - Issues: https://github.com/AgentEra/Agently/issues
  629. - WeChat group: https://doc.weixin.qq.com/forms/AIoA8gcHAFMAScAhgZQABIlW6tV3l7QQf
  630. - Twitter / X: https://x.com/AgentlyTech
  631. ## License
  632. Agently follows an open-core model:
  633. - Open-source core: [Apache 2.0](LICENSE)
  634. - Trademark usage policy: [TRADEMARK.md](TRADEMARK.md)
  635. - Contributor rights agreement: [CLA.md](CLA.md)
  636. - Enterprise extensions and services: separate commercial agreements

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.