agently 4.0.7.1__py3-none-any.whl → 4.0.7.2__py3-none-any.whl

agently/utils/AGENT_UTILS_GUIDE.md

@@ -0,0 +1,175 @@
+# Agently Utils Guide (Agent-Readable)
+
+Use this as a compact, agent-oriented guide to the utilities in `agently/utils`. It is intentionally brief and practical.
+
+## Quick Map (TL;DR)
+- data shaping: `DataFormatter`, `RuntimeData`, `SerializableRuntimeData`, `Settings`
+- path and JSON helpers: `DataLocator`, `DataPathBuilder`, `StreamingJSONCompleter`, `StreamingJSONParser`
+- async/sync bridging: `FunctionShifter`, `GeneratorConsumer`
+- dynamic deps: `LazyImport`
+- storage: `Storage`, `AsyncStorage`
+- misc: `Logger`, `Messenger`, `PythonSandbox`
+- legacy: `old_RuntimeData` (avoid unless you must keep backward behavior)
+
+## Utilities
+
+### DataFormatter
+Purpose: normalize complex values into safe, serializable, or string forms, and do placeholder substitution.
+
+Key methods:
+- `sanitize(value, remain_type=False)`: convert complex objects into JSON-ish values. Handles `datetime`, `RuntimeData`, `pydantic.BaseModel`, and typing constructs like `list[T]`, `Union`, `Literal`.
+- `to_str_key_dict(value, value_format=None, default_key=None, default_value=None)`: ensure dict keys are strings and values optionally sanitized or stringified. If input is not a dict, can wrap with `default_key`.
+- `from_schema_to_kwargs_format(schema)`: convert JSON Schema object fields into Agently kwargs-style `(type, desc)` mapping.
+- `substitute_placeholder(obj, variable_mappings, placeholder_pattern=None)`: recursive replace `${key}` placeholders in strings, dicts, lists, sets, tuples.
+
+When to use:
+- Before logging/serialization.
+- When building structured prompts from schemas.
+- When injecting env variables into settings or prompts.
+
+### DataLocator
+Purpose: locate values by path, and extract JSON blocks from mixed text.
+
+Key methods:
+- `locate_path_in_dict(dict, path, style="dot"|"slash", default=None)`: safe deep lookup with `a.b[0]` or `/a/b/0` styles.
+- `locate_all_json(text)`: scan text and return all JSON-like blocks.
+- `locate_output_json(text, output_prompt_dict)`: pick the most likely JSON block matching your output schema.
+
+When to use:
+- Parsing LLM responses that mix text + JSON.
+- Robust extraction for streaming parsers.
+
+### DataPathBuilder
+Purpose: convert and reason about dot/slash paths, and extract expected parsing paths from a schema-like dict.
+
+Key methods:
+- `build_dot_path(keys)`, `build_slash_path(keys)`
+- `convert_dot_to_slash(dot_path)`, `convert_slash_to_dot(slash_path)`
+- `extract_possible_paths(schema, style="dot")`: find all possible paths.
+- `extract_parsing_key_orders(schema, style="dot")`: paths in definition order (used by streaming parser).
+- `get_value_by_path(data, path, style="dot")`: retrieve values, supports `[*]` wildcard expansion.
+
+When to use:
+- Streaming JSON parsing with ordered fields.
+- Mapping UI updates to schema paths.
+
+### FunctionShifter
+Purpose: bridge sync/async code and run async work safely from sync contexts.
+
+Key methods:
+- `syncify(func)`: wrap an async function so it can be called in sync code. Uses `asyncio.run` or a thread when a loop is running.
+- `asyncify(func)`: wrap a sync function so it can be awaited via `asyncio.to_thread`.
+- `future(func)`: return a `Future` for the function execution; ensures there is a loop.
+- `syncify_async_generator(async_gen)`: consume an async generator from sync code via a background thread.
+- `auto_options_func(func)`: drop extra kwargs that the function does not accept.
+
+When to use:
+- Tool functions that may be sync or async.
+- Adapters between streaming generators and sync APIs.
+
+### GeneratorConsumer
+Purpose: fan out a generator or async generator to multiple consumers, replay history, and handle errors.
+
+Usage:
+- Wrap a generator, then call `get_async_generator()` for multiple async consumers or `get_generator()` for sync.
+- `get_result()` waits for completion and returns full history.
+- `close()` cancels and notifies listeners.
+
+When to use:
+- Broadcast streaming output to multiple subscribers.
+- Merge history + live updates reliably.
+
+### LazyImport
+Purpose: import optional deps and optionally auto-install via pip with version constraints.
+
+Key methods:
+- `from_import(from_package, target_modules, auto_install=True, version_constraint=None, install_name=None)`
+- `import_package(package_name, auto_install=True, version_constraint=None, install_name=None)`
+
+Notes:
+- This prompts for installation in interactive use; plan for non-interactive runtime accordingly.
+
+### Logger
+Purpose: create a consistent logger with optional uvicorn integration.
+
+Key pieces:
+- `create_logger(app_name="Agently", log_level="INFO")` returns `AgentlyLogger` with `raise_error` helper.
+
+### Messenger
+Purpose: convenience wrapper for event center messaging.
+
+Key method:
+- `create_messenger(module_name)` delegates to `agently.base.event_center`.
+
+### PythonSandbox
+Purpose: execute small snippets safely with restricted builtins and whitelisted return types.
+
+Key behaviors:
+- `run(code)` executes in a sandbox; raises if a return type is not in `allowed_return_types`.
+- `preset_objects` are wrapped to block private attributes and enforce safe return types.
+
+When to use:
+- Run short user-defined expressions or filters with safety checks.
+
+### RuntimeData / RuntimeDataNamespace
+Purpose: runtime-scoped hierarchical data with inheritance, dot-path access, and merge-friendly set semantics.
+
+Key behaviors:
+- `get(key, default=None, inherit=True)`: inherited view by default.
+- `set` and `__setitem__` merge dict/list/set values rather than replace (unless you use `cover=True` internally).
+- dot-path access: `data["a.b.c"]`.
+- `namespace("path")` returns a namespace view.
+- `dump("json"|"yaml"|"toml")`, `load(...)` support.
+
+When to use:
+- Store workflow state, memo, runtime configs.
+
+### SerializableRuntimeData / SerializableRuntimeDataNamespace
+Purpose: same API as `RuntimeData` but value types restricted to JSON-serializable shapes.
+
+When to use:
+- Settings and serialized runtime state.
+
+### Settings / SettingsNamespace
+Purpose: settings with mapping shortcuts and env substitution.
+
+Key behaviors:
+- `register_path_mappings("short", "actual.path")`: alias keys.
+- `register_kv_mappings("key", "value", actual_settings)`: map a key+value to a settings dict.
+- `set_settings(key, value, auto_load_env=False)`: apply mappings and optionally expand `${ENV.X}`.
+
+When to use:
+- Global or per-agent configuration with shortcuts.
+
+### Storage / AsyncStorage
+Purpose: simple SQLModel-based persistence with sync/async APIs.
+
+Key behaviors:
+- requires `sqlmodel`, `sqlalchemy`, `aiosqlite` via `LazyImport`.
+- `set(obj|list)` merges into DB.
+- `get(model, where=..., first=False, limit=..., offset=..., order_by=...)`.
+- `create_tables()` calls `SQLModel.metadata.create_all`.
+
+When to use:
+- local state persistence for agents or tools.
+
+### StreamingJSONCompleter
+Purpose: complete partial JSON strings by closing open strings, comments, or brackets.
+
+Key method:
+- `append(data)` then `complete()` to get best-effort JSON.
+
+When to use:
+- streaming LLM output where JSON is partial.
+
+### StreamingJSONParser
+Purpose: parse streaming JSON and emit incremental updates (`delta`) and completion events (`done`).
+
+Key behaviors:
+- Uses `DataLocator` + `StreamingJSONCompleter` to find and parse JSON in noisy streams.
+- Tracks schema order via `DataPathBuilder.extract_parsing_key_orders`.
+- `parse_chunk(chunk)` yields `StreamingData` events.
+- `parse_stream(chunk_stream)` yields events and finalizes at end.
+
+When to use:
+- UI streaming updates for structured output.

agently/utils/DataFormatter.py

@@ -242,9 +242,11 @@ class DataFormatter:
 
             if "additionalProperties" in input_schema:
                 additional_properties = input_schema["additionalProperties"]
-                if additional_properties is True or additional_properties is None:
+                if additional_properties is False:
+                    pass
+                elif additional_properties is True or additional_properties is None:
                     kwargs_format["<*>"] = (Any, "")
-                else:
+                elif isinstance(additional_properties, dict):
                     additional_type = additional_properties.pop("type", Any)
                     additional_properties.pop("title", None)
                     additional_desc = (
@@ -253,6 +255,8 @@ class DataFormatter:
                         else ""
                     )
                     kwargs_format["<*>"] = (additional_type, additional_desc)
+                else:
+                    kwargs_format["<*>"] = (Any, "")
 
             return kwargs_format or None
 

agently/utils/FunctionShifter.py

@@ -76,8 +76,9 @@ class FunctionShifter:
 
         @wraps(func)
         async def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
-            assert inspect.isfunction(func)
-            return await asyncio.to_thread(func, *args, **kwargs)
+            if not callable(func):
+                raise TypeError(f"Expected a callable, got {type(func)}")
+            return await asyncio.to_thread(func, *args, **kwargs)  # type: ignore
 
         return wrapper
 

agently/utils/TimeInfo.py

@@ -0,0 +1,22 @@
+# Copyright 2023-2025 AgentEra(Agently.Tech)
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+from datetime import datetime
+
+
+class TimeInfo:
+    @staticmethod
+    def get_current_time():
+        return datetime.now().strftime("%Y-%m-%d %H:%M:%S %A")

agently/utils/__init__.py

@@ -28,3 +28,4 @@ from .GeneratorConsumer import GeneratorConsumer
 from .StreamingJSONCompleter import StreamingJSONCompleter
 from .StreamingJSONParser import StreamingJSONParser
 from .PythonSandbox import PythonSandbox
+from .TimeInfo import TimeInfo

agently-4.0.7.2.dist-info/METADATA

@@ -0,0 +1,433 @@
+Metadata-Version: 2.4
+Name: agently
+Version: 4.0.7.2
+Summary: 
+License: Apache-2.0
+License-File: LICENSE
+Author: Agently Team
+Author-email: developer@agently.tech
+Requires-Python: >=3.10
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: greenlet (>=3.2.3,<4.0.0)
+Requires-Dist: httpx (>=0.28.1,<0.29.0)
+Requires-Dist: httpx-sse (>=0.4.1,<0.5.0)
+Requires-Dist: json5 (>=0.12.0,<0.13.0)
+Requires-Dist: packaging (>=25.0,<26.0)
+Requires-Dist: pydantic (>=2.11.7,<3.0.0)
+Requires-Dist: pyyaml (>=6.0.2,<7.0.0)
+Requires-Dist: stamina (>=25.1.0,<26.0.0)
+Requires-Dist: toml (>=0.10.2,<0.11.0)
+Description-Content-Type: text/markdown
+
+<img width="640" alt="image" src="https://github.com/user-attachments/assets/c645d031-c8b0-4dba-a515-9d7a4b0a6881" />
+
+# Agently 4
+
+[English Introduction](https://github.com/AgentEra/Agently/blob/main/README.md) | [中文介绍](https://github.com/AgentEra/Agently/blob/main/README_CN.md)
+
+
+> *Speed Up Your GenAI Application Development*
+
+[![license](https://img.shields.io/badge/license-Apache2.0-blue.svg?style=flat-square)](https://github.com/AgentEra/Agently/blob/main/LICENSE)
+[![PyPI - Downloads](https://img.shields.io/pypi/dm/agently?style=flat-square)](https://pypistats.org/packages/agently)
+[![GitHub star chart](https://img.shields.io/github/stars/agentera/agently?style=flat-square)](https://star-history.com/#agentera/agently)
+[![Twitter](https://img.shields.io/twitter/url/https/twitter.com/AgentlyTech.svg?style=social&label=Follow%20%40AgentlyTech)](https://x.com/AgentlyTech)
+<a href="https://doc.weixin.qq.com/forms/AIoA8gcHAFMAScAhgZQABIlW6tV3l7QQf">
+<img alt="WeChat" src="https://img.shields.io/badge/WeChat%20Group-Apply-brightgreen?logo=wechat&style=flat-square">
+</a>
+
+<p>
+  <a href="https://github.com/AgentEra/Agently/discussions/categories/general">
+    <img alt="Discussions" src="https://img.shields.io/badge/Agently%20General%20Discussions-JOIN-brightgreen.svg?style=for-the-badge" />
+  </a>
+  <a href="https://github.com/AgentEra/Agently/discussions/categories/contribute-to-agently-4">
+    <img alt="Contribute" src="https://img.shields.io/badge/Contribute%20to%20Agently%204%20-Join-blueviolet.svg?style=for-the-badge">
+  </a>
+  <a href="https://github.com/AgentEra/Agently/issues">
+    <img alt="Issues" src="https://img.shields.io/badge/Report%20Issues-Report-red.svg?style=for-the-badge">
+  </a>
+</p>
+
+<hr />
+
+<p align="center">
+    <b><a href = "https://Agently.tech">💥 Official WebSite</a> - Everything about Agently and what's coming next</b>
+</p>
+
+<hr />
+
+## Getting Started
+
+Agently is a Python-based framework for building GenAI applications. You can install it via pip and import features using `from agently import Agently`.
+
+Install the latest version via pip:
+
+```shell
+pip install -U agently
+```
+
+> ℹ️ If you're looking for Agently v3's code and documents, please visit branch [`v3-final`](https://github.com/AgentEra/Agently/tree/v3-final)
+
+Clone the repository and install locally:
+
+```shell
+git clone git@github.com:AgentEra/Agently.git
+cd Agently
+pip install -e .
+```
+
+## Documentation
+
+- Docs Site: https://Agently.tech/docs
+- Step-by-step tutorials: `examples/step_by_step/`
+- Auto Loop FastAPI (SSE/WS/POST, Docker-ready): `examples/step_by_step/13-auto_loop_fastapi/`
+
+## What is Agently?
+
+Agently aims to provide an intuitive, efficient, and developer-friendly framework for GenAI application development. By deeply understanding the runtime control needs of model outputs, Agently bridges the gap between large language models and real-world applications.
+
+Agently abstracts away the complexities of:
+- Varying model parameters
+- Output formatting
+- Communication between engineering modules and GenAI logic
+
+...while giving developers full control over business logic and integration with existing systems.
+
+We believe GenAI is not a generational replacement for current systems but a powerful extension. Engineers and tools are key to turning GenAI's possibilities into reality.
+
+Our mission is to build the best developer experience (DX) for GenAI application engineers.
+
+## From Demo to Production
+
+In real teams, the hardest part is rarely “can the model answer?”—it’s whether the system can survive real traffic, real data, and real dependencies while staying testable, observable, and maintainable. Agently is built to pull LLM uncertainty back inside an engineering boundary.
+
+- **Contract-first structured outputs (framework-native, provider-agnostic)**: define schemas with `output()`, enforce critical paths with `ensure_keys`, and parse/repair in the framework pipeline (no hard dependency on provider-specific `response_format` / JSON-schema switches). This keeps interfaces stable even when you switch models or inference servers.
+- **Tool planning + traceability without vendor lock-in**: deciding whether to use a tool, selecting a tool, and building kwargs is a built-in planning step in the framework, not something that requires function-calling support. Every run leaves evidence in `extra` (`tool_logs` / tool calls) for debugging and audit.
+- **Workflow orchestration you can maintain**: TriggerFlow translates visual “low-code graphs” (n8n/Dify/Coze style) into readable code with events, branching, joins, loops, and concurrency limits. Combined with Instant-mode partial node capture + signal-driven execution, you can do real-time UX like “companion robot speaks while actions trigger”.
+- **Grounded answers with citations**: KB retrieval results are structured (`id/document/metadata`) and can be turned into enforced citations (e.g. `source_id` + `quote`) so answers are traceable and reviewable.
+
+## Core Features Overview
+
+These are the production pain points we keep seeing across teams:
+- **“I asked for JSON, got a paragraph.”** Missing keys, format drift, extra prose → broken parsers.
+- **Tools that work… until they don’t.** Failures become hard to reproduce, debug, and audit.
+- **Low-code graphs that outgrow themselves.** More branches, more state, less confidence to change.
+- **RAG without accountability.** You can’t answer: “Which doc supports this claim?”
+
+Agently turns them into engineering primitives you can ship with confidence: schema-first outputs (`output()` + `ensure_keys`), Instant-mode structured streaming, framework-native tool planning with traces, TriggerFlow orchestration, and KB grounding with citations.
+
+### Structured and Streamed Output Control for LLMs
+
+Schema-first outputs are often the difference between a demo and an API: you define what the system must return, and the framework enforces it at runtime.
+
+Agently allows you to control and consume model outputs using a developer-centric pattern:
+
+```python
+from agently import Agently
+
+agent = Agently.create_agent()
+
+(
+    agent
+        .input("What time is it now?", always=True)
+        .info({
+            "default_timezone": "",
+            "tool_list": [{
+                "name": "get_current_time",
+                "desc": "Get current time by time zone provided",
+                "kwargs": {
+                    "timezone_str": (str, "time zone string in ZoneInfo()"),
+                },
+            }]
+        })
+        .output({
+            "first_time_response": (str, ),
+            "tool_using_judgement": (bool, ),
+            "tool_using_command": (
+                {
+                    "name": (str, "Decide which tool to use by tool name:{tool_list.[].name}"),
+                    "kwargs": (dict, "According {tool_list.[].args} to output kwargs dictionary"),
+                },
+                "If {tool_using_judgement}==False, just output {}",
+            ),
+        })
+)
+```
+
+Then, consume the model response:
+
+```python
+response = agent.get_response()
+
+# Get raw text
+response_text = response.get_text()
+
+# Get parsed structured data
+response_data = response.get_data()
+
+# Instant parsing mode (structured streaming)
+instant_response_generator = response.get_generator(type="instant")
+
+use_tool = False
+
+for instant_message in instant_response_generator:
+    if instant_message.path == "first_time_response":
+        if instant_message.delta is not None:
+            print(instant_message.delta, end="", flush=True)
+    elif instant_message.path == "tool_using_judgement":
+        use_tool = instant_message.value
+        print()
+        if use_tool:
+            print("[USE TOOL!]")
+        else:
+            print("[NO NEED TO USE TOOL!]")
+    if use_tool:
+        if instant_message.path == "tool_using_command.name" and instant_message.is_complete:
+            print(f"I want to use: '{ instant_message.value }'")
+        elif instant_message.path == "tool_using_command":
+            print(f"call: { instant_message.value }")
+            print(f"kwargs: { instant_message.value }")
+```
+
+```shell
+I can check the current time for you. Please specify a timezone (e.g., 'America/New_York') so I can provide the accurate time.
+[NO NEED TO USE TOOL!]
+```
+
+### Provider Compatibility (Local / Hosted / Proxy)
+
+Agently unifies model configuration via `OpenAICompatible`, so you can switch between providers while keeping the same developer experience. It also supports common “production reality” knobs like `full_url` and custom auth headers.
+
+- Minimal example:
+```python
+from agently import Agently
+
+Agently.set_settings(
+    "OpenAICompatible",
+    {
+        "base_url": "https://api.deepseek.com/v1",
+        "model": "deepseek-chat",
+        "auth": "DEEPSEEK_API_KEY",
+    },
+)
+```
+
+- Example configs: `examples/model_configures/`
+- Step-by-step: `examples/step_by_step/01-settings.py`
+
+### Output Reliability (ensure_keys + retries)
+
+In batch tasks and pipelines, a missing field can crash the whole job. Agently provides `ensure_keys` + retries for structured output so you can enforce required fields (including wildcard paths for list items).
+
+- Minimal example:
+```python
+from agently import Agently
+
+agent = Agently.create_agent()
+result = (
+    agent.input("Give me 3 todos")
+    .output({"todos": [("str", "todo item")]})
+    .start(ensure_keys=["todos[*]"], max_retries=2, raise_ensure_failure=False)
+)
+print(result)
+```
+```text
+Output (qwen2.5:7b):
+{'todos': ['Schedule morning exercise routine', 'Prepare presentation slides for the meeting', 'Respond to emails from clients']}
+```
+
+- Step-by-step: `examples/step_by_step/03-output_format_control.py`
+
+### Streaming UX (delta / instant / typed_delta)
+
+Agently streaming is designed for real applications: reduce waiting, expose decisions early, and route structured fields to different UI regions. For example in a “companion robot” HCI scenario, you often want to mix user-facing text with machine/behavior commands, and consume them as soon as they are parsed.
+
+- Minimal example:
+```python
+from agently import Agently
+
+agent = Agently.create_agent()
+response = (
+    agent.input("Act as a companion robot: greet me and propose a small action you can do next.")
+    .output(
+        {
+            "thinking": ("str", "internal planning (not for users)"),
+            "say": ("str", "what the user sees/hears"),
+            "actions": [("str", "robot action command(s) for your app to execute")],
+        }
+    )
+    .get_response()
+)
+
+say_label_printed = False
+
+def execute_action(action: str) -> None:
+    # In real apps, route this to your robot controller / UI event bus.
+    print(f"\n[action] {action}")
+
+for msg in response.get_generator(type="instant"):
+    if msg.path == "say" and msg.delta:
+        if not say_label_printed:
+            print("[say] ", end="")
+            say_label_printed = True
+        print(msg.delta, end="", flush=True)
+    if msg.path.startswith("actions[") and msg.is_complete:
+        execute_action(msg.value)
+print()
+```
+```text
+Output (qwen2.5:7b):
+[say] Hello! Nice to meet you. How about we start with some light conversation? Do you have any favorite hobbies or interests that we could talk about?
+[action] initiate_conversation
+```
+
+- Step-by-step: `examples/step_by_step/06-streaming.py`
+- Reference patterns: `examples/basic/streaming_print.py`
+
+### Tools (built-in + custom + traceable)
+
+When a project grows from 1 tool to 20 tools, “it worked yesterday” isn’t enough—you need predictable planning and a trail you can audit.
+
+Tools let the model call external functions deterministically. Agently supports:
+- built-in `Search` / `Browse`
+- custom tools via decorator
+- tool call tracing from response metadata (`extra`)
+
+Unlike workflows that rely on provider-side function calling, Agently can run a framework-native “tool planning” step even on plain chat endpoints, so tool orchestration stays portable across most modern models.
+
+- Minimal example:
+```python
+from agently import Agently
+
+agent = Agently.create_agent()
+
+@agent.tool_func
+def add(*, a: int, b: int) -> int:
+    return a + b
+
+agent.use_tools(add)
+print(agent.input("Use the add tool to calculate 12 + 34.").start())
+```
+```text
+Output (qwen2.5:7b):
+The sum of 12 and 34 is calculated as follows:
+
+12
++34
+-----
+46
+
+Therefore, the result of 12 + 34 is **46**. 
+
+No external sources were used in this calculation.
+```
+
+- Step-by-step: `examples/step_by_step/07-tools.py`
+
+### Workflow Orchestration (TriggerFlow)
+
+TriggerFlow is for the moment your workflow stops being a sketch: you need events, joins, loops, concurrency limits, and long-term maintainability (including migrating from n8n/Dify/Coze-style graphs into code).
+
+TriggerFlow is Agently’s event-driven workflow engine, designed for:
+- branching (`when`, `if_condition`, `match`)
+- concurrency limits (`batch`, `for_each`)
+- loops (`emit` + `when`)
+- runtime stream events (`put_into_stream`)
+
+- Minimal example:
+```python
+from agently import TriggerFlow
+
+flow = TriggerFlow()
+flow.to(lambda d: f"Hello, {d.value}").end()
+print(flow.start("Agently"))
+```
+```text
+Output (qwen2.5:7b):
+Hello, Agently
+```
+
+- TriggerFlow series: `examples/step_by_step/11-triggerflow-01_basics.py`
+
+### Knowledge Base (embeddings + vector DB)
+
+In enterprise RAG, the question is rarely “can we retrieve?”—it’s “can we cite and defend the answer?”.
+
+Agently integrates KB pipelines (e.g., Chroma) to ground responses with real documents and metadata.
+
+- Minimal example:
+```python
+from agently import Agently
+from agently.integrations.chromadb import ChromaCollection
+
+embedding = Agently.create_agent()
+embedding.set_settings(
+    "OpenAICompatible",
+    {
+        "model": "qwen3-embedding:0.6b",
+        "base_url": "http://127.0.0.1:11434/v1/",
+        "auth": "nothing",
+        "model_type": "embeddings",
+    },
+)
+kb = ChromaCollection(collection_name="demo", embedding_agent=embedding)
+kb.add([{"document": "Agently is a GenAI framework.", "metadata": {"source": "demo"}}])
+print(kb.query("What is Agently?"))
+```
+
+- Step-by-step: `examples/step_by_step/09-knowledge_base.py`
+
+### Deployment Templates (FastAPI, Docker)
+
+For engineering delivery, the repo includes a docker-ready FastAPI project that exposes Auto Loop through:
+- SSE streaming
+- WebSocket
+- POST
+
+- Minimal example:
+```shell
+cd examples/step_by_step/13-auto_loop_fastapi
+uvicorn app.main:app --reload
+```
+
+- Project: `examples/step_by_step/13-auto_loop_fastapi/`
+
+### Learn by Examples (Recommended Path)
+
+Start with these step-by-step chapters (runnable code + explanations in docs):
+- Settings → `examples/step_by_step/01-settings.py`
+- Prompt Methods → `examples/step_by_step/02-prompt_methods.py`
+- Output Control → `examples/step_by_step/03-output_format_control.py`
+- Streaming → `examples/step_by_step/06-streaming.py`
+- Tools → `examples/step_by_step/07-tools.py`
+- TriggerFlow → `examples/step_by_step/11-triggerflow-01_basics.py`
+- Auto Loop → `examples/step_by_step/12-auto_loop.py`
+
+## Agently Helper (Desktop)
+
+Agently Helper is a desktop tool to help you quickly **understand** and **test** Agently capabilities without setting up a full project first:
+- Multi-model management and switching
+- Switching between different prompt styles
+- Structured output
+- Streaming output
+
+- Windows: https://1drv.ms/u/c/13d5207d1b13e4d3/IQC9XITZl83hR5vU9Z_t-0oKAd3jtMh_fYRypp7T2k8JhCY?e=I72GVH
+- macOS (Apple Silicon): https://1drv.ms/u/c/13d5207d1b13e4d3/IQBhdxYw9Ev1R6qTWb-esVK2AY8PwCxnBHLNuf06Ic4w7sw?e=unMjaD
+- macOS (Intel): https://1drv.ms/u/c/13d5207d1b13e4d3/IQDqUPSqRq7LR7gpCjK60FOSASl4PBsRZPGtHvBAA63U_js?e=EmwVMA
+- Linux: https://1drv.ms/u/c/13d5207d1b13e4d3/IQDVenHvItjFTqnlv294MPD9AUQDvkAKwvBcNufEXSl1nAs?e=Ti5aJ7
+
+## 💬 WeChat Group (Join Us)
+
+> [Click Here to Apply](https://doc.weixin.qq.com/forms/AIoA8gcHAFMAScAhgZQABIlW6tV3l7QQf)
+> or Scan the QR Code Below:
+
+<p align="center">
+  <img width="120" alt="WeChat QR" src="https://github.com/AgentEra/Agently/assets/4413155/7f4bc9bf-a125-4a1e-a0a4-0170b718c1a6">
+</p>
+