Skip to content

v1.4.1 — DX overhaul

Choose a tag to compare

View all tags
@shibing624 shibing624 released this 28 Apr 07:27
· 97 commits to main since this release
v1.4.1
a990877

v1.4.1 — DX overhaul: top-level exports, sync-first docs, history filter

Highlights

Simpler imports — no more deep paths

OpenAIChat and the 6 default Builtin*Tools are now eager top-level exports:

from agentica import (
    Agent, DeepAgent, Workspace, tool,
    OpenAIChat,
    BuiltinFileTool, BuiltinExecuteTool, BuiltinFetchUrlTool,
    BuiltinWebSearchTool, BuiltinTodoTool, BuiltinTaskTool,
    HistoryConfig, WorkspaceMemoryConfig, RunConfig,
)

Other model providers (Claude / Ollama / LiteLLM / Kimi) stay in their submodules to avoid pulling heavy SDKs at startup.

Sync-first quickstart

run_sync is now the default in README and examples/basic/. Internally it still runs the full async agentic loop with parallel tool calls — the sync wrapper just hides the event loop.

from agentica import Agent, OpenAIChat
agent = Agent(model=OpenAIChat(id="gpt-4o-mini"))
print(agent.run_sync("Hello").content)

NEW: customizable history filtering

Two layers, both opt-in. Drop noisy tool results, truncate long replies, or write a Python callable for full control:

from agentica import Agent, OpenAIChat, HistoryConfig

agent = Agent(
    model=OpenAIChat(id="gpt-4o-mini"),
    add_history_to_context=True,
    history_config=HistoryConfig(
        excluded_tools=["search_*", "web_search"],   # drop matching tool results, paired tool_calls auto-stripped
        assistant_max_chars=200,                      # truncate AI replies in history
    ),
    history_filter=lambda history: [...],             # advanced: any Python callable
)

Pipeline: excluded_tools → assistant_max_chars → user callable → automatic tool_calls consistency fix (so the OpenAI API contract is never violated).

See examples/memory/03_history_filter.py.

NEW: configuration consistency warnings

The most common silent-failure trap is now caught at construction time:

  • Setting long_term_memory_config with auto_archive=True but forgetting enable_long_term_memory=True → warn loudly.
  • Setting enable_long_term_memory=True but no workspace → warn loudly.

NEW: Agent Recipes

README and docs/guides/best_practices.md now ship 5 copy-paste-ready Agent configurations covering: one-shot scripts, multi-turn chat, custom tool sets, multi-user + long-term memory, and long-session token saving.

Other changes

  • README rewrite (CN + EN + JP) with sync vs async section
  • examples/basic/01_hello_world.py and 03_stream_output.py reordered to lead with sync
  • New examples/basic/07b_function_calling_sync.py — minimal sync function-calling demo
  • tests/test_history_filter.py — 10 unit tests for the filter pipeline
  • agentica/api_registry.py — moved exports to eager block

Upgrade

pip install -U agentica

No breaking changes. All existing imports continue to work.

Assets 2
Loading