flowra 0.0.92.dev109__tar.gz → 0.0.93__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {flowra-0.0.92.dev109 → flowra-0.0.93}/CHANGELOG.md +36 -20
- {flowra-0.0.92.dev109 → flowra-0.0.93}/PKG-INFO +1 -1
- {flowra-0.0.92.dev109 → flowra-0.0.93}/context7.json +3 -3
- {flowra-0.0.92.dev109 → flowra-0.0.93}/docs/agents.md +17 -16
- {flowra-0.0.92.dev109 → flowra-0.0.93}/docs/observability.md +102 -67
- {flowra-0.0.92.dev109 → flowra-0.0.93}/docs/tools.md +49 -8
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/lib/turn/agent.py +30 -25
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/lib/turn/hook_events.py +5 -1
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/lib/turn/tool_call/agent.py +13 -20
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/lib/turn/tool_call/agent_tool.py +2 -5
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/tools/__init__.py +11 -1
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/tools/local_tool.py +54 -33
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/tools/types.py +16 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/version.py +1 -1
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/lib/test_tool_call_agent_call_agent.py +45 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/lib/test_turn_agent.py +105 -7
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/tools/test_local_tool.py +180 -2
- {flowra-0.0.92.dev109 → flowra-0.0.93}/.agents/skills/source-command-update-pricing/SKILL.md +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/.claude/commands/update-pricing.md +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/.env.example +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/.github/CODEOWNERS +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/.github/workflows/master.yml +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/.github/workflows/publish.yml +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/.github/workflows/pull_request.yml +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/.gitignore +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/.python-version +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/AGENTS.md +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/CLAUDE.md +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/LICENSE +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/Makefile +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/README.md +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/docs/architecture.md +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/docs/getting-started.md +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/docs/llm.md +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/docs/patterns.md +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/docs/research/agent_async_init.md +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/docs/research/agent_tool_errors.md +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/docs/research/anthropic_web_search.md +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/docs/research/e2e_security.md +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/docs/research/enum_slot_values.md +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/docs/research/final_tools.md +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/docs/research/langchain_comparison.md +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/docs/research/lifecycle_hooks_and_conversation.md +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/docs/research/llm_retry_backoff.md +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/docs/research/named_scope_lazy_hydration.md +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/docs/research/named_scope_type_registry.md +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/docs/research/named_scopes.md +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/docs/research/pricing_complexity.md +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/docs/research/pydantic_ai_comparison.md +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/docs/research/strands_comparison.md +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/docs/research/tool_error_signals.md +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/docs/research/tool_errors_vs_failures.md +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/docs/research/tool_registry_redesign.md +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/docs/research/tool_search_tool.md +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/docs/research/voice_stt.md +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/docs/review_prompts/step1_structure.md +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/docs/review_prompts/step2_code_style.md +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/docs/review_prompts/step3_documentation.md +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/docs/review_prompts/step4_doc_readability.md +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/docs/review_prompts/step5_doc_audit.md +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/docs/review_prompts/step6_tests.md +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/docs/todo.md +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/docs/video_script.md +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/examples/TRACING_COMBINATIONS.md +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/examples/__init__.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/examples/agent_as_tool.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/examples/app_agent.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/examples/console_chat.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/examples/docs/__init__.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/examples/docs/agents_custom.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/examples/docs/agents_parallel.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/examples/docs/getting_started_chat.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/examples/docs/getting_started_streaming.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/examples/docs/getting_started_tools.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/examples/docs/llm_streaming.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/examples/docs/llm_structured_output.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/examples/docs/tools_service_injection.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/examples/escalation.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/examples/llm_logging.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/examples/llm_routing.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/examples/menu_agent.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/examples/menu_agent_class.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/examples/mlflow_demo.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/examples/mlflow_dual_export_demo.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/examples/mlflow_nested_demo.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/examples/mlflow_otel_both_demo.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/examples/mlflow_otel_nested_demo.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/examples/mlflow_parallel_demo.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/examples/model_registry.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/examples/otel_demo.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/examples/otel_jaeger_demo.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/examples/otel_nested_demo.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/examples/otel_visualize.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/examples/race.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/examples/span_crash_demo.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/examples/span_demo.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/examples/system_prompt.txt +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/examples/tools/__init__.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/examples/tools/calculator.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/examples/tools/random_numbers.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/examples/tools/switch_model.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/examples/tui_chat.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/__init__.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/_sentinel.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/_typing.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/agent/__init__.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/agent/definition/__init__.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/agent/definition/_path.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/agent/definition/actions.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/agent/definition/agent.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/agent/definition/agent_arg.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/agent/definition/compile/__init__.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/agent/definition/compile/compiler.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/agent/definition/compile/contract.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/agent/definition/compile/init_params.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/agent/definition/compile/instance.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/agent/definition/compile/step_params.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/agent/definition/compile/step_validation.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/agent/definition/compile/steps.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/agent/definition/compile/type_registry.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/agent/definition/model.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/agent/definition/registry.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/agent/definition/shared_persistent.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/agent/definition/spawn.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/agent/definition/step.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/agent/definition/step_helpers.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/agent/flow/__init__.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/agent/flow/context.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/agent/flow/flowing_registry.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/agent/flow/hooks.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/agent/flow/interrupt.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/agent/flow/interrupt_helpers.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/agent/flow/timeout.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/agent/runtime/__init__.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/agent/runtime/engine.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/agent/runtime/execution.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/agent/runtime/instance_factory.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/agent/runtime/key_locks.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/agent/runtime/runtime.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/agent/runtime/scope.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/agent/runtime/serialization.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/agent/runtime/spans.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/agent/runtime/spawn_satisfaction.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/agent/runtime/spawn_tree.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/agent/runtime/visibility.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/agent/services.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/agent/session_state.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/agent/state/__init__.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/agent/state/markers.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/agent/state/persistent.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/agent/state/store.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/agent/state/values.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/agent/storage/__init__.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/agent/storage/file.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/agent/storage/in_memory.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/agent/storage/session_storage.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/ext/__init__.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/ext/_session.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/ext/mlflow.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/ext/otel.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/lib/__init__.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/lib/chat/__init__.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/lib/chat/agent.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/lib/chat/config.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/lib/chat/conversation.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/lib/chat/hook_events.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/lib/chat/spec.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/lib/config_value.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/lib/llm_call/__init__.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/lib/llm_call/agent.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/lib/llm_call/config.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/lib/llm_call/spec.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/lib/llm_caller.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/lib/llm_config.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/lib/observability/__init__.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/lib/observability/llm_hooks.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/lib/turn/__init__.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/lib/turn/config.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/lib/turn/context.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/lib/turn/spec.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/lib/turn/tool_call/__init__.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/lib/turn/tool_call/context.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/llm/__init__.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/llm/_schema_nodes.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/llm/base.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/llm/blocks.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/llm/errors.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/llm/ext/__init__.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/llm/ext/anthropic/__init__.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/llm/ext/anthropic/cache.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/llm/ext/anthropic/presets.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/llm/ext/anthropic/tool_search.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/llm/ext/anthropic/web_search.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/llm/ext/openai/__init__.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/llm/ext/openai/tool_search.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/llm/gemini_schema.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/llm/messages.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/llm/openai_schema.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/llm/pricing/__init__.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/llm/pricing/bundled.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/llm/pricing/data/custom/anthropic.json +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/llm/pricing/data/custom/vertex.json +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/llm/pricing/data/generated/anthropic.json +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/llm/pricing/data/generated/azure_openai.json +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/llm/pricing/data/generated/bedrock.json +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/llm/pricing/data/generated/gemini_api.json +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/llm/pricing/data/generated/inception.json +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/llm/pricing/data/generated/openai.json +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/llm/pricing/data/generated/vertex.json +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/llm/pricing/model_pricing.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/llm/pricing/price_list.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/llm/provider.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/llm/providers/__init__.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/llm/providers/_openai_common.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/llm/providers/anthropic.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/llm/providers/anthropic_bedrock.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/llm/providers/anthropic_foundry.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/llm/providers/anthropic_vertex.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/llm/providers/azure_openai.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/llm/providers/google_vertex.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/llm/providers/openai.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/llm/providers/openai_responses.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/llm/request.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/llm/response.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/llm/schema_formatting.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/llm/schema_validation.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/llm/stream.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/llm/tools.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/py.typed +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/tools/_mcp_content.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/tools/_mcp_headers.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/tools/mcp_connection.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/tools/result_format.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/tools/tool_arg.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/tools/tool_filter.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/flowra/tools/tool_registry.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/pyproject.toml +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/__init__.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/agent/__init__.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/agent/definition/__init__.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/agent/definition/compile/__init__.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/agent/definition/compile/test_compile.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/agent/definition/test_actions.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/agent/definition/test_agent.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/agent/definition/test_registry.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/agent/definition/test_spawn.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/agent/definition/test_step_helpers.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/agent/flow/__init__.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/agent/flow/test_context.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/agent/flow/test_flowing_registry.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/agent/flow/test_flowing_registry_tasks.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/agent/flow/test_flowing_sync.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/agent/flow/test_hooks.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/agent/flow/test_interrupt.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/agent/flow/test_interruptible.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/agent/flow/test_spans.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/agent/flow/test_timeout.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/agent/flow/test_with_interrupt.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/agent/runtime/__init__.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/agent/runtime/test_engine.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/agent/runtime/test_engine_spans.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/agent/runtime/test_ephemeral_isolation.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/agent/runtime/test_hook_context.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/agent/runtime/test_named_scope_persistence.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/agent/runtime/test_named_scope_registry.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/agent/runtime/test_named_scopes.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/agent/runtime/test_parallel_failure.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/agent/runtime/test_persistence.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/agent/runtime/test_primitive_join.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/agent/runtime/test_runtime.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/agent/runtime/test_scope.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/agent/runtime/test_serialization.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/agent/runtime/test_spec_in_constructor.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/agent/state/__init__.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/agent/state/test_values.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/agent/storage/__init__.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/agent/storage/test_file.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/agent/storage/test_in_memory.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/agent/test_missing_scenarios.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/agent/test_session_state.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/examples/__init__.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/examples/test_menu_agent.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/ext/__init__.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/ext/_mlflow.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/ext/test_mlflow.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/ext/test_mlflow_cross_task.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/ext/test_otel.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/lib/__init__.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/lib/_helpers.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/lib/ext/__init__.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/lib/ext/anthropic/__init__.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/lib/ext/anthropic/test_anthropic.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/lib/ext/openai/__init__.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/lib/ext/openai/test_openai_tool_search.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/lib/test_chat_agent.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/lib/test_chat_spec.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/lib/test_config_value.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/lib/test_conversation.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/lib/test_llm_call_agent.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/lib/test_llm_caller.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/lib/test_matches_tool_filter.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/lib/test_tool_call_agent.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/lib/turn/__init__.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/lib/turn/test_per_call_headers.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/lib/turn/test_render.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/lib/turn/test_tool_errors.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/llm/__init__.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/llm/pricing/__init__.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/llm/pricing/test_bundled.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/llm/pricing/test_model_pricing.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/llm/pricing/test_price_list.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/llm/providers/__init__.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/llm/providers/_mock_http.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/llm/providers/_raw_body.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/llm/providers/_tool_result_blocks.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/llm/providers/test_anthropic.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/llm/providers/test_anthropic_bedrock.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/llm/providers/test_anthropic_bedrock_e2e.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/llm/providers/test_anthropic_e2e.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/llm/providers/test_anthropic_foundry.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/llm/providers/test_anthropic_foundry_e2e.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/llm/providers/test_anthropic_vertex.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/llm/providers/test_anthropic_vertex_locations_e2e.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/llm/providers/test_azure_openai_e2e.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/llm/providers/test_cross_provider_e2e.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/llm/providers/test_errors.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/llm/providers/test_fallback_e2e.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/llm/providers/test_google_vertex.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/llm/providers/test_google_vertex_e2e.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/llm/providers/test_history_across_models.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/llm/providers/test_openai_e2e.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/llm/providers/test_openai_provider.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/llm/providers/test_openai_responses.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/llm/providers/test_openai_responses_e2e.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/llm/providers/test_refusals.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/llm/providers/test_schemas_e2e.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/llm/test_blocks.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/llm/test_cost_breakdown.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/llm/test_gemini_schema.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/llm/test_metadata.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/llm/test_openai_schema.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/llm/test_response.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/llm/test_schema_formatting.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/llm/test_schema_nodes.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/llm/test_schema_validation.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/llm/test_stream.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/scripts/__init__.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/scripts/test_sync_pricing.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/test_typing.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/tools/__init__.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/tools/test_mcp_connection.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/tools/test_mcp_headers.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/tools/test_result_format.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/tools/test_tool_registry.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tests/tools/test_types.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/tools/sync_pricing.py +0 -0
- {flowra-0.0.92.dev109 → flowra-0.0.93}/uv.lock +0 -0
|
@@ -5,33 +5,49 @@ All notable changes to this project will be documented in this file.
|
|
|
5
5
|
The format is based on [Keep a Changelog](https://keepachangelog.com),
|
|
6
6
|
and this project adheres to [Semantic Versioning](https://semver.org).
|
|
7
7
|
|
|
8
|
-
## [
|
|
8
|
+
## [0.0.93] - 2026-10-23
|
|
9
|
+
|
|
10
|
+
### Added
|
|
11
|
+
- **`ToolErrorPolicy`: choose which exceptions of a `@tool` function reach the
|
|
12
|
+
model** (closes #139). `@tool(..., errors=ToolErrorPolicy(answer=(...),
|
|
13
|
+
failure="..."))`: an exception of a listed type is answered with its text, as
|
|
14
|
+
before; any other is answered with `failure`, which carries none of its text
|
|
15
|
+
(SQL, ids, customer data). `ToolError` and invalid arguments always reach the
|
|
16
|
+
model. Without a policy, every exception reaches the model, as before.
|
|
17
|
+
Details in [Internal failures](docs/tools.md#internal-failures).
|
|
18
|
+
|
|
19
|
+
### Changed
|
|
20
|
+
- **Arguments that don't load into a tool's input dataclass are
|
|
21
|
+
`SCHEMA_VALIDATION`, not `EXECUTION`**, for `@tool` and agent tools: whatever
|
|
22
|
+
the load raises, e.g. a `marshmallow` error for an invalid date or a
|
|
23
|
+
`ValueError` from the dataclass's `__post_init__`. The content is unchanged.
|
|
24
|
+
- **A `jsonschema.ValidationError` raised inside a `@tool` function is
|
|
25
|
+
`EXECUTION`, not `SCHEMA_VALIDATION`.** Only the tool's own arguments are
|
|
26
|
+
`SCHEMA_VALIDATION` now; before, a validation the function ran itself (e.g.
|
|
27
|
+
on an API response) was taken for an invalid call. The content is unchanged.
|
|
28
|
+
|
|
29
|
+
## [0.0.92] - 2026-10-22
|
|
9
30
|
|
|
10
31
|
### Added
|
|
11
32
|
- **`BeforeToolCallsEvent`: answer a model message's tool calls before any
|
|
12
|
-
runs
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
`BeforeToolCallEvent` and no `ToolCallSpan`; it goes through
|
|
19
|
-
`AfterToolCallEvent` and counts toward `max_consecutive_errors` like any
|
|
20
|
-
result. An error answered without an `error_kind` gets
|
|
21
|
-
`ToolErrorKind.EXECUTION`; a key that is not the id of a call in the message
|
|
22
|
-
raises `ValueError`. Answered calls are kept in the turn's state, so they
|
|
23
|
-
survive a resume before the results are collected.
|
|
33
|
+
runs** (#136). It fires once per model message that has tool calls, even when it
|
|
34
|
+
has only one, and lists them in `tool_uses`. A handler puts a `ToolResult`
|
|
35
|
+
into `results` under a call's id: that call does not run, and the model gets
|
|
36
|
+
the handler's answer. Use it for a rule about the message as a whole, such as
|
|
37
|
+
a tool that must be called alone. Details in
|
|
38
|
+
[Pre-built events](docs/observability.md#pre-built-events).
|
|
24
39
|
- **`AfterToolCallEvent.prefilled`**: true for a call answered in
|
|
25
40
|
`BeforeToolCallsEvent`, so a handler can tell that the tool did not run.
|
|
26
41
|
|
|
27
42
|
### Changed
|
|
28
|
-
- **A call's answer carries an `error_kind` exactly when it is an error.**
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
43
|
+
- **A call's answer carries an `error_kind` exactly when it is an error.** An
|
|
44
|
+
error that comes without a kind reaches `AfterToolCallEvent` and
|
|
45
|
+
`ToolCallSpan` as `ToolErrorKind.EXECUTION`, and an answer that is not an
|
|
46
|
+
error carries no kind. A consumer that tells an error by its kind now sees
|
|
47
|
+
every error. Details in [Error handling](docs/tools.md#errors-the-tool-chooses).
|
|
48
|
+
- **A `BeforeToolCallEvent` handler that changes a call's `id` raises
|
|
49
|
+
`ValueError`.** The id ties a call to its result, so a replaced `tool_use`
|
|
50
|
+
keeps it.
|
|
35
51
|
|
|
36
52
|
## [0.0.91] - 2026-10-20
|
|
37
53
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: flowra
|
|
3
|
-
Version: 0.0.
|
|
3
|
+
Version: 0.0.93
|
|
4
4
|
Summary: Flowra — flow infrastructure for building stateful LLM agents
|
|
5
5
|
Project-URL: Repository, https://github.com/anna-money/flowra
|
|
6
6
|
Project-URL: Changelog, https://github.com/anna-money/flowra/blob/master/CHANGELOG.md
|
|
@@ -48,7 +48,7 @@
|
|
|
48
48
|
"McpConnection connects to remote MCP servers for tool discovery over Streamable HTTP. McpConnection.snapshot() returns a frozen ToolRegistry; the tool list is refreshed in the background (server ttlMs, 60s default) with add_on_tools_changed(callback) for changes, and tools with invalid x-mcp-header annotations are dropped. Speaks both MCP protocol eras and detects on connect: stateless 2026-07-28 (no handshake/session; x-mcp-header args mirrored into Mcp-Param-* headers) and handshake-based 2025-03-26 to 2025-11-25 (any other version fails connect()). McpConnection.session (McpSession) exposes stateless: bool, protocol_version and session_id. A tool call needing client input (MRTR) returns a tool error; subscriptions/listen and MRTR are not implemented. McpConnection.call_tool(name, args, headers=..., meta=...) adds per-call HTTP headers and params._meta (kept on the reconnect retry; Content-Type/Accept/Mcp-* headers and the protocol's io.modelcontextprotocol/* _meta keys raise ValueError)",
|
|
49
49
|
"ToolCallInfo (flowra.tools) carries per-call headers and meta, empty by default — flowra sets none itself. Fill them in a BeforeToolCallEvent handler (event.data.headers / event.data.meta); they are stored in ToolCallSpec, so a resumed call gets the same values (generate idempotency keys there, not in the tool). ToolCallAgent passes ToolCallInfo in services: MCP snapshot tools send them with tools/call, a @tool reads them by declaring an info: ToolCallInfo parameter",
|
|
50
50
|
"ToolRegistry is immutable, accepts @tool-decorated functions or ExecutableTools: ToolRegistry([my_func, other_func])",
|
|
51
|
-
"TOOL ERRORS: the executor built by @tool catches the decorated function's exceptions (and argument validation/service binding errors) and returns ToolResult(content='Error: {e}', is_error=True, error_kind=EXECUTION, or SCHEMA_VALIDATION for invalid arguments) — so registry.execute and a direct get_tool(f).executor(...) call both return the error result. A ToolResult the function returns is the answer as it is (not serialized), except that what hooks and spans see (ToolCallResult, AfterToolCallEvent, ToolCallSpan) carries an error_kind exactly when it is an error — EXECUTION for an error given without one, None for a non-error; ToolResult.content is str | list[TextBlock | MediaBlock], and ToolCallAgent puts its blocks into the ToolResultBlock as they are (metadata and transient kept; a str is one TextBlock; ToolResult.blocks / ToolResult.text). A '-> ToolResult' annotation gives no output_schema; '-> Answer | ToolResult' gives Answer's. raise ToolError(content, error_kind=EXECUTION) (str or blocks) to answer with an error the tool chose: the executor returns exc.result (is_error=True, content as written, no 'Error: ' prefix, no log); only the @tool executor answers it — an agent behind an agent tool returns ToolResult(is_error=True) instead, and a ToolError raised in an agent fails the run like any exception. InterruptedError is the exception: the executor raises it, and ToolCallAgent answers 'Tool execution interrupted'. ToolRegistry.execute does not catch: an exception from code around an executor (a wrapper via dataclasses.replace(tool, executor=...), a custom ExecutableTool executor) propagates through ToolCallAgent to AgentRuntime.run/resume as itself (session stays resumable); return ToolResult(is_error=True) from such code to answer the model. ToolCallAgent answers InterruptedError raised around a tool with 'Tool execution interrupted'. McpConnection never raises for a call, except ValueError for invalid per-call headers/_meta (set by a BeforeToolCallEvent handler, it fails the run and a resume repeats it, since the values are stored with the call): unknown/removed tools → UNKNOWN_TOOL; a result's MCP content comes back as blocks (text and resource text → TextBlock; image, audio and resource blob → MediaBlock; resource_link and unknown types → TextBlock with the block as JSON), with what the flowra block does not carry in metadata['mcp'] (text/image/audio: every field but type, content (text/data) and, for media, mimeType (annotations, _meta, any other), no metadata when none, so plain text is a plain TextBlock; resource: the whole block but the resource's text/blob, uri and mimeType under metadata['mcp']['resource']; resource_link and unknown types: type, annotations, _meta); a malformed block makes the response invalid; isError → the server's blocks, JSON-RPC errors → the server's text; transport failures → 'temporarily unavailable' (retried once if the reconnect succeeds); invalid responses → 'returned an invalid response', not retried. When one of several parallel steps (e.g. parallel tool calls) raises, the engine cancels and awaits its siblings, then re-raises the original exception (no ExceptionGroup). Agent tool executors (make_agent_tool/@agent_tool) answer invalid arguments with SCHEMA_VALIDATION
|
|
51
|
+
"TOOL ERRORS: the executor built by @tool catches the decorated function's exceptions (and argument validation/service binding errors) and returns ToolResult(content='Error: {e}', is_error=True, error_kind=EXECUTION, or SCHEMA_VALIDATION for invalid arguments) — so registry.execute and a direct get_tool(f).executor(...) call both return the error result. A ToolResult the function returns is the answer as it is (not serialized), except that what hooks and spans see (ToolCallResult, AfterToolCallEvent, ToolCallSpan) carries an error_kind exactly when it is an error — EXECUTION for an error given without one, None for a non-error; ToolResult.content is str | list[TextBlock | MediaBlock], and ToolCallAgent puts its blocks into the ToolResultBlock as they are (metadata and transient kept; a str is one TextBlock; ToolResult.blocks / ToolResult.text). A '-> ToolResult' annotation gives no output_schema; '-> Answer | ToolResult' gives Answer's. raise ToolError(content, error_kind=EXECUTION) (str or blocks) to answer with an error the tool chose: the executor returns exc.result (is_error=True, content as written, no 'Error: ' prefix, no log); only the @tool executor answers it — an agent behind an agent tool returns ToolResult(is_error=True) instead, and a ToolError raised in an agent fails the run like any exception. Arguments that fail the schema or don't load into the input dataclass (any exception from the load: mr.ValidationError for an invalid date, a __post_init__ ValueError) are SCHEMA_VALIDATION, for @tool and agent tools. @tool(name, errors=ToolErrorPolicy(answer=(SomeError,), failure='...')) narrows the catch: an exception of a listed type (or subclass) still reaches the model as 'Error: {e}'; any other (incl. a missing service) is answered with failure; every exception is logged with its traceback either way (EXECUTION, none of its text; default 'Error: the tool failed with an internal error'); ToolError and invalid arguments reach the model whatever the policy; without errors= every exception reaches the model. InterruptedError is the exception: the executor raises it, and ToolCallAgent answers 'Tool execution interrupted'. ToolRegistry.execute does not catch: an exception from code around an executor (a wrapper via dataclasses.replace(tool, executor=...), a custom ExecutableTool executor) propagates through ToolCallAgent to AgentRuntime.run/resume as itself (session stays resumable); return ToolResult(is_error=True) from such code to answer the model. ToolCallAgent answers InterruptedError raised around a tool with 'Tool execution interrupted'. McpConnection never raises for a call, except ValueError for invalid per-call headers/_meta (set by a BeforeToolCallEvent handler, it fails the run and a resume repeats it, since the values are stored with the call): unknown/removed tools → UNKNOWN_TOOL; a result's MCP content comes back as blocks (text and resource text → TextBlock; image, audio and resource blob → MediaBlock; resource_link and unknown types → TextBlock with the block as JSON), with what the flowra block does not carry in metadata['mcp'] (text/image/audio: every field but type, content (text/data) and, for media, mimeType (annotations, _meta, any other), no metadata when none, so plain text is a plain TextBlock; resource: the whole block but the resource's text/blob, uri and mimeType under metadata['mcp']['resource']; resource_link and unknown types: type, annotations, _meta); a malformed block makes the response invalid; isError → the server's blocks, JSON-RPC errors → the server's text; transport failures → 'temporarily unavailable' (retried once if the reconnect succeeds); invalid responses → 'returned an invalid response', not retried. When one of several parallel steps (e.g. parallel tool calls) raises, the engine cancels and awaits its siblings, then re-raises the original exception (no ExceptionGroup). Agent tool executors (make_agent_tool/@agent_tool) answer invalid arguments with SCHEMA_VALIDATION results like @tool; with valid arguments, one called outside ToolCallAgent raises RuntimeError",
|
|
52
52
|
"ToolRegistry.builder() returns ToolRegistryBuilder with .add(source, prefix=..., filter=..., on_duplicate='error'|'skip') and .build() for composing registries from multiple sources. filter is a single Callable[[ExecutableTool], bool]; use the `tool_filter` module for common cases: tool_filter.INCLUDE_SUFFIX(*names) whitelists, tool_filter.EXCLUDE_SUFFIX(*names) blacklists (both match exact name or __name suffix), tool_filter.ALL_OF(*filters)/tool_filter.ANY_OF(*filters) compose. Import: from flowra.tools import tool_filter",
|
|
53
53
|
"Duplicate tool names are detected eagerly at the ToolRegistryBuilder.add() call where the collision is introduced. Default on_duplicate='error' raises ValueError; on_duplicate='skip' silently drops repeats (first occurrence wins). ToolRegistry(...) constructor also raises on duplicate names. OnDuplicate type alias is exported from flowra.tools",
|
|
54
54
|
"ToolRegistry is a ConfigValue[ToolRegistry | None] in ChatConfig and TurnConfig (field name: tools)",
|
|
@@ -134,7 +134,7 @@
|
|
|
134
134
|
"RENDER: ChatConfig.render / TurnConfig.render (PromptRender = Callable[[Prompt], Prompt | Awaitable[Prompt]]; Prompt from flowra.lib.turn has system and messages) is called once per LLM call of the turn (not per fallback attempt), before LLMCaller, with the system messages and the conversation (history, then turn messages). What it returns is sent to every fallback link; each link's request_extensions apply after it, and each attempt's LLMCallSpan carries the request with them applied. Stored history and turn messages are not changed, so a marker block can be rendered from live state on each call; build new messages, never edit the given ones. Messages left with no blocks are not sent, none left at all is a ValueError before the call; a tool call must still be followed straight away by its results (Claude and OpenAI Chat Completions reject anything in between); an error in render is raised from the turn as is; an interrupt stops an async render and ends the turn INTERRUPTED",
|
|
135
135
|
"TurnAgent lifecycle: __post_init__ emits TurnReadyEvent(context, turn_messages) — fires on both creation and crash recovery. ChatAgent subscribes and emits ConversationReadyEvent(conversation, context) with a Conversation view combining history + turn messages",
|
|
136
136
|
"Conversation class (from flowra.lib.chat): read-only Sequence view over history + turn_messages. Supports len(), indexing, slicing, forward/reverse iteration. Live — reflects changes to underlying lists. Properties: history_len, turn_len. Method without_pending_tool_use() -> list[UserMessage | AssistantMessage] returns messages with ToolUseBlocks stripped from the last AssistantMessage (drops the message entirely if it becomes empty) — use it inside an agent-as-tool to feed the parent conversation to a child LLM call without the unresolved tool-use that spawned it",
|
|
137
|
-
"TurnAgent hook events: StartTurnEvent (messages, metadata — mutate messages to augment input), MessageAcceptedEvent, StartIterationEvent, TextReasoningEvent (each TextBlock with text in response), ThinkingEvent (each ThinkingBlock with text; not redacted or signature-only thoughts), ServerToolCallEvent (server-side tool call from intermediate messages, e.g. tool search), ServerToolResultEvent (server-side tool result), ResultMessageEvent, BeforeToolCallsEvent (once per model message
|
|
137
|
+
"TurnAgent hook events: StartTurnEvent (messages, metadata — mutate messages to augment input), MessageAcceptedEvent, StartIterationEvent, TextReasoningEvent (each TextBlock with text in response), ThinkingEvent (each ThinkingBlock with text; not redacted or signature-only thoughts), ServerToolCallEvent (server-side tool call from intermediate messages, e.g. tool search), ServerToolResultEvent (server-side tool result), ResultMessageEvent, BeforeToolCallsEvent (once per model message that has tool calls, even when it has only one, before any runs; tool_uses is every call of the message, a cut-off call included (an answer under its id is not used); put a ToolResult into results under a call's id to answer it without running it — that call gets no BeforeToolCallEvent and no ToolCallSpan, its result goes through AfterToolCallEvent with prefilled=True and max_consecutive_errors in message order, an error without error_kind gets EXECUTION; an answered call never reaches the tool, so neither the registry nor allowed_tools/denied_tools apply: an answer to an unknown or denied tool reaches the model as given, not as Unknown tool; a key not among the message's call ids raises ValueError), BeforeToolCallEvent (has tool_definition: ToolDefinition | None; mutable tool_use (a replacement keeps the call's id; changing it raises ValueError), headers, meta — see ToolCallInfo; not emitted for a call answered in BeforeToolCallsEvent), AfterToolCallEvent (fires after execution, and for a call answered in BeforeToolCallsEvent; has error_kind; prefilled is true for a call answered in BeforeToolCallsEvent; result is a single ToolResultBlock; append TextBlock/MediaBlock to additional_blocks to attach them to this call's result — they go at the end of its content, also when max_consecutive_errors replaces it, so they stay with their call and never land between the results of parallel calls; mark one transient to keep it out of saved history; being part of the result, a MediaBlock there takes the providers' rules for media in a tool result (Chat Completions raises, Gemini before 3 does not see it) and a transient block ends the non-transient cache prefix before the result). Delta events: TextDeltaEvent, ThinkingDeltaEvent (from flowra.lib.observability — shared with LLMCallAgent). UsageEvent emitted after each LLM call + subscribed to accumulate usage from child agents (e.g. agent_as_tool). Span-hooks: LLMCallSpan, ToolCallSpan. Request transforms (prompt caching, tool search) are NOT hooks — they live on LLMConfig.request_extensions. A conversation transform for every fallback link goes in ChatConfig.render / TurnConfig.render (see RENDER)",
|
|
138
138
|
"When TextDeltaEvent or ThinkingDeltaEvent handlers are registered, TurnAgent automatically uses provider.stream() instead of provider.call()",
|
|
139
139
|
|
|
140
140
|
"AGENTS AS TOOLS: Tools can delegate to sub-agents via ToolCallAgentContext.call_agent(). make_agent_tool(AgentClass, name, description) creates an ExecutableTool with input_schema from spec type and output_schema from result type (ToolResult excluded). @agent_tool decorator marks an agent class as a tool, get_agent_tool() extracts the ExecutableTool. ToolCallAgent spawns the sub-agent and serializes its result as a ToolResultBlock. Agent tools can return ToolResult directly to signal errors to the parent LLM or answer with blocks (e.g. return ToolResult(content='...', is_error=True)) — the agent completes normally; with is_error=True the parent LLM sees a tool error and can retry. Compile-time validation: step return types must be a subset of Agent's generic result type parameter. The sub-agent must be declared by the agent running the tool or one of its registry ancestors (top level works); it receives services of its own registry ancestors, not the calling chat's (unless the chat is one of them)",
|
|
@@ -157,7 +157,7 @@
|
|
|
157
157
|
"Import LLM types: from flowra.llm import LLMProvider, SystemMessage, TextBlock, Usage, TextDelta, ThinkingDelta, ContentComplete",
|
|
158
158
|
"Import agent runtime: from flowra.agent import AgentRuntime, FileSessionStorage, InMemorySessionSnapshot, InMemorySessionStorage",
|
|
159
159
|
"InMemorySessionStorage.snapshot() returns InMemorySessionSnapshot (frozen dataclass with execution and node_states). InMemorySessionStorage(snapshot) constructs a new storage from snapshot (deep copy). Clone: InMemorySessionStorage(storage.snapshot())",
|
|
160
|
-
"Import tools: from flowra.tools import ToolRegistry, get_tool, tool, ToolError, ToolErrorKind, ToolResult",
|
|
160
|
+
"Import tools: from flowra.tools import ToolRegistry, get_tool, tool, ToolError, ToolErrorKind, ToolErrorPolicy, ToolResult",
|
|
161
161
|
|
|
162
162
|
"FlowingRegistry + FlowingVar: from flowra.agent import FlowingRegistry. Registry of flowing variables, passed as service to AgentRuntime. FlowingVar[T] created via registry.create_var(default=..., on_enter=..., on_exit=...). Engine manages lifecycle via registry.fork()/restore()/snapshot()/apply() (fork/restore for sibling isolation, snapshot/apply for task inheritance). on_enter/on_exit callbacks fire on context switches, keeping external ContextVars in sync. Used by tracing integrations for parent span tracking. Usage: flowing = FlowingRegistry(); my_var = flowing.create_var(default=None); services={FlowingRegistry: flowing, HookSubscription: hooks}",
|
|
163
163
|
|
|
@@ -793,24 +793,25 @@ there needs `../` or a leading `/`.
|
|
|
793
793
|
|
|
794
794
|
Lifecycle events (from `flowra.lib.turn`):
|
|
795
795
|
|
|
796
|
-
| Event
|
|
797
|
-
|
|
798
|
-
| `StartTurnEvent`
|
|
799
|
-
| `MessageAcceptedEvent`
|
|
800
|
-
| `StartIterationEvent`
|
|
801
|
-
| `TextReasoningEvent`
|
|
802
|
-
| `ThinkingEvent`
|
|
803
|
-
| `ServerToolCallEvent`
|
|
804
|
-
| `ServerToolResultEvent`
|
|
805
|
-
| `BeforeToolCallsEvent`
|
|
806
|
-
| `BeforeToolCallEvent`
|
|
807
|
-
| `AfterToolCallEvent`
|
|
808
|
-
| `ResultMessageEvent`
|
|
796
|
+
| Event | When | Mutable fields |
|
|
797
|
+
|-------------------------|--------------------------------------------------------|------------------------------------------------------|
|
|
798
|
+
| `StartTurnEvent` | Start of turn (before first iter) | `messages` |
|
|
799
|
+
| `MessageAcceptedEvent` | After message accepted | — |
|
|
800
|
+
| `StartIterationEvent` | Each tool loop iteration | `additional_messages` |
|
|
801
|
+
| `TextReasoningEvent` | Non-empty text block in LLM response | — |
|
|
802
|
+
| `ThinkingEvent` | Non-empty thinking block in LLM response | — |
|
|
803
|
+
| `ServerToolCallEvent` | Server-side tool call (e.g. tool search) | — |
|
|
804
|
+
| `ServerToolResultEvent` | Server-side tool result | — |
|
|
805
|
+
| `BeforeToolCallsEvent` | Model message with tool calls, before any of them runs | `results` |
|
|
806
|
+
| `BeforeToolCallEvent` | Before one tool call runs | `tool_use`, `headers`, `meta` |
|
|
807
|
+
| `AfterToolCallEvent` | After one tool call, or after a handler answered it | `result`, `additional_blocks`, `additional_messages` |
|
|
808
|
+
| `ResultMessageEvent` | LLM finished (END_TURN) | `continue_messages` |
|
|
809
809
|
|
|
810
810
|
A tool call cut off by the output limit appears in `BeforeToolCallsEvent` but
|
|
811
|
-
fires no `BeforeToolCallEvent` or `AfterToolCallEvent
|
|
812
|
-
`BeforeToolCallsEvent` does not run;
|
|
813
|
-
[Pre-built events](observability.md#pre-built-events)
|
|
811
|
+
fires no `BeforeToolCallEvent` or `AfterToolCallEvent`. A call a handler answers
|
|
812
|
+
in `BeforeToolCallsEvent.results` does not run; it still fires
|
|
813
|
+
`AfterToolCallEvent`. See [Pre-built events](observability.md#pre-built-events)
|
|
814
|
+
in Observability.
|
|
814
815
|
|
|
815
816
|
Streaming events (from `flowra.lib.observability`):
|
|
816
817
|
|
|
@@ -18,6 +18,9 @@ runtime = AgentRuntime(agents={...}, services={...})
|
|
|
18
18
|
runtime.hooks.on(TextDeltaEvent, lambda e: print(e.data.text, end="", flush=True))
|
|
19
19
|
```
|
|
20
20
|
|
|
21
|
+
A handler receives an `Event`: the event itself is in `.data`, and `.context`
|
|
22
|
+
says which agent emitted it (see [Event context](#event-context)).
|
|
23
|
+
|
|
21
24
|
Some events are **mutable** — your handler can modify the event data to influence
|
|
22
25
|
execution. For example, `StartTurnEvent` lets you rewrite messages before the
|
|
23
26
|
LLM sees them.
|
|
@@ -26,64 +29,45 @@ LLM sees them.
|
|
|
26
29
|
|
|
27
30
|
Events from `TurnAgent` (and `ChatAgent`, which uses it internally):
|
|
28
31
|
|
|
29
|
-
| Event
|
|
30
|
-
|
|
31
|
-
| `StartTurnEvent`
|
|
32
|
-
| `MessageAcceptedEvent`
|
|
33
|
-
| `StartIterationEvent`
|
|
34
|
-
| `TextReasoningEvent`
|
|
35
|
-
| `ThinkingEvent`
|
|
36
|
-
| `ServerToolCallEvent`
|
|
37
|
-
| `ServerToolResultEvent`
|
|
38
|
-
| `BeforeToolCallsEvent`
|
|
39
|
-
| `BeforeToolCallEvent`
|
|
40
|
-
| `AfterToolCallEvent`
|
|
41
|
-
| `ResultMessageEvent`
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
block stays with the call it is about and never lands between the results of
|
|
45
|
-
parallel calls (providers require tool results to come first in a message). Mark
|
|
46
|
-
a block transient if it should reach the model but not the saved history (see
|
|
47
|
-
[Tool results](llm.md#tool-results)). Two things follow from the blocks being
|
|
48
|
-
part of the result:
|
|
49
|
-
|
|
50
|
-
- A `MediaBlock` makes it a result with media: Chat Completions rejects it and
|
|
51
|
-
Gemini before 3 does not see it (see the table in
|
|
52
|
-
[Tool results](llm.md#tool-results)). To show those models a picture, add a
|
|
53
|
-
`UserMessage` to `additional_messages`.
|
|
54
|
-
- With the `*_non_transient_*` caching extensions, a transient block ends the
|
|
55
|
-
cached prefix before this result, so its content is not cached on the turn's
|
|
56
|
-
later calls. For a large result, prefer a hint that is not transient.
|
|
57
|
-
|
|
58
|
-
```python
|
|
59
|
-
from flowra.agent import Event
|
|
60
|
-
from flowra.lib.turn import AfterToolCallEvent
|
|
61
|
-
from flowra.llm import TextBlock
|
|
32
|
+
| Event | When | Mutable? |
|
|
33
|
+
|-------------------------|--------------------------------------------------------|------------------------------------------------------|
|
|
34
|
+
| `StartTurnEvent` | Start of turn (before first iter) | `messages` |
|
|
35
|
+
| `MessageAcceptedEvent` | After message accepted | — |
|
|
36
|
+
| `StartIterationEvent` | Each tool loop iteration | `additional_messages` |
|
|
37
|
+
| `TextReasoningEvent` | Non-empty text block in LLM response | — |
|
|
38
|
+
| `ThinkingEvent` | Non-empty thinking block in LLM response | — |
|
|
39
|
+
| `ServerToolCallEvent` | Server-side tool call (e.g. tool search) | — |
|
|
40
|
+
| `ServerToolResultEvent` | Server-side tool result | — |
|
|
41
|
+
| `BeforeToolCallsEvent` | Model message with tool calls, before any of them runs | `results` |
|
|
42
|
+
| `BeforeToolCallEvent` | Before one tool call runs | `tool_use`, `headers`, `meta` |
|
|
43
|
+
| `AfterToolCallEvent` | After one tool call, or after a handler answered it | `result`, `additional_blocks`, `additional_messages` |
|
|
44
|
+
| `ResultMessageEvent` | LLM finished (END_TURN) | `continue_messages` |
|
|
45
|
+
|
|
46
|
+
Streaming events, emitted while the model's response arrives:
|
|
62
47
|
|
|
48
|
+
| Event | When |
|
|
49
|
+
|----------------------|------------------------------|
|
|
50
|
+
| `TextDeltaEvent` | Each streamed text chunk |
|
|
51
|
+
| `ThinkingDeltaEvent` | Each streamed thinking chunk |
|
|
63
52
|
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
event.data.additional_blocks.append(TextBlock(text="Quote the balance in GBP.", transient=True))
|
|
53
|
+
Import the lifecycle events from `flowra.lib.turn` and the streaming events
|
|
54
|
+
from `flowra.lib.observability`.
|
|
67
55
|
|
|
56
|
+
#### Answering tool calls before they run
|
|
68
57
|
|
|
69
|
-
|
|
70
|
-
|
|
58
|
+
The model often asks for several tools in one message, and `TurnAgent` runs
|
|
59
|
+
them all at once. `BeforeToolCallsEvent` fires before any of them starts and
|
|
60
|
+
lists the message's calls in `tool_uses`, so a handler can apply a rule about
|
|
61
|
+
the message as a whole — for example, a tool that must be called alone. It
|
|
62
|
+
fires for every message with tool calls, even one with a single call.
|
|
71
63
|
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
`
|
|
79
|
-
call included, before any of them runs. A handler answers a call itself by
|
|
80
|
-
putting a `ToolResult` into `results` under the call's id: that call does not
|
|
81
|
-
run, and the others run as usual. An answered call gets no `BeforeToolCallEvent`
|
|
82
|
-
and no `ToolCallSpan`; its result goes through `AfterToolCallEvent` (with
|
|
83
|
-
`prefilled=True`) and `max_consecutive_errors` like any other, in the message's
|
|
84
|
-
order. An error answered without an `error_kind` arrives with
|
|
85
|
-
`ToolErrorKind.EXECUTION`, as any error a tool gives without one does. A key that is not the id of a call in the message
|
|
86
|
-
fails the step with `ValueError`.
|
|
64
|
+
To answer a call instead of running it, put a
|
|
65
|
+
[`ToolResult`](tools.md#answering-with-blocks) into `results` under the call's
|
|
66
|
+
id. The model gets that answer as the tool's result; the other calls run as
|
|
67
|
+
usual. The answer can be an error (a refusal, as below) or not (say, a cached
|
|
68
|
+
result). Every handler of the event sees the same `results`, so a later
|
|
69
|
+
handler sees what an earlier one answered. A key that is not the id of a call
|
|
70
|
+
in `tool_uses` raises `ValueError`.
|
|
87
71
|
|
|
88
72
|
```python
|
|
89
73
|
from flowra.agent import Event
|
|
@@ -97,27 +81,76 @@ def reply_alone(event: Event[BeforeToolCallsEvent]) -> None:
|
|
|
97
81
|
for tool_use in event.data.tool_uses:
|
|
98
82
|
if tool_use.name == "send_reply":
|
|
99
83
|
event.data.results[tool_use.id] = ToolResult(
|
|
100
|
-
content="Call send_reply on its own, in a message with no other tool calls.",
|
|
84
|
+
content="Call send_reply on its own, in a message with no other tool calls.",
|
|
85
|
+
is_error=True,
|
|
101
86
|
)
|
|
102
87
|
|
|
103
88
|
|
|
104
89
|
runtime.hooks.on(BeforeToolCallsEvent, reply_alone)
|
|
105
90
|
```
|
|
106
91
|
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
92
|
+
An answered call skips the tool entirely. There is no `BeforeToolCallEvent` or
|
|
93
|
+
`ToolCallSpan` for it, and nothing checks whether the tool exists or is allowed
|
|
94
|
+
(the [tool registry](tools.md#registering-tools) and
|
|
95
|
+
[`allowed_tools`/`denied_tools`](tools.md#tool-filtering) are not consulted), so
|
|
96
|
+
a handler can answer a call to any tool name, even one the model made up. Its
|
|
97
|
+
answer is then treated like a tool's: `AfterToolCallEvent` fires for it, with
|
|
98
|
+
`prefilled=True` to say the tool did not run, and an error answer counts toward
|
|
99
|
+
`max_consecutive_errors` (a `TurnConfig` / `ChatConfig` setting: after that
|
|
100
|
+
many errors from one tool in a row, the model gets "try a different approach"
|
|
101
|
+
in place of that call's result; the turn goes on).
|
|
102
|
+
|
|
103
|
+
A call the response cut off at the output limit is listed in `tool_uses` too,
|
|
104
|
+
but an answer under its id is ignored (without a `ValueError`): that call
|
|
105
|
+
always gets an error, see below.
|
|
106
|
+
|
|
107
|
+
#### Adding to a tool's result
|
|
108
|
+
|
|
109
|
+
To add something to a tool's result after the call, append blocks to
|
|
110
|
+
`AfterToolCallEvent.additional_blocks`. They go at the end of that call's
|
|
111
|
+
result, so a block stays with the call it is about and never lands between the
|
|
112
|
+
results of parallel calls (providers require tool results to come first in a
|
|
113
|
+
message). Mark a block transient if it should reach the model but not the saved
|
|
114
|
+
history (see [Tool results](llm.md#tool-results)). Two things follow from the
|
|
115
|
+
blocks being part of the result:
|
|
111
116
|
|
|
112
|
-
|
|
117
|
+
- A `MediaBlock` makes it a result with media: Chat Completions rejects it and
|
|
118
|
+
Gemini models before 3 do not see it (see the table in
|
|
119
|
+
[Tool results](llm.md#tool-results)). To show those models a picture, add a
|
|
120
|
+
`UserMessage` to `additional_messages`.
|
|
121
|
+
- With the `*_non_transient_*` caching extensions (see
|
|
122
|
+
[Prompt caching](llm.md#prompt-caching-anthropic)), a transient block ends the
|
|
123
|
+
cached prefix before this result, so its content is not cached on the turn's
|
|
124
|
+
later calls. For a large result, prefer a hint that is not transient.
|
|
113
125
|
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
126
|
+
```python
|
|
127
|
+
from flowra.agent import Event
|
|
128
|
+
from flowra.lib.turn import AfterToolCallEvent
|
|
129
|
+
from flowra.llm import TextBlock
|
|
130
|
+
|
|
131
|
+
|
|
132
|
+
def add_hint(event: Event[AfterToolCallEvent]) -> None:
|
|
133
|
+
if event.data.tool_use.name == "get_balance" and not event.data.result.is_error:
|
|
134
|
+
event.data.additional_blocks.append(TextBlock(text="Quote the balance in GBP.", transient=True))
|
|
135
|
+
|
|
136
|
+
|
|
137
|
+
runtime.hooks.on(AfterToolCallEvent, add_hint)
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
#### Tool calls that skip `AfterToolCallEvent`
|
|
141
|
+
|
|
142
|
+
Two kinds of tool call never reach `AfterToolCallEvent`, so hooks that audit or
|
|
143
|
+
rewrite tool results don't see them:
|
|
118
144
|
|
|
119
|
-
|
|
120
|
-
|
|
145
|
+
- A call the response cut off at the output limit (see
|
|
146
|
+
[TurnAgent](agents.md#turnagent)) is never run. It gets an error saying its
|
|
147
|
+
arguments arrived incomplete, with no `BeforeToolCallEvent`,
|
|
148
|
+
`AfterToolCallEvent` or `ToolCallSpan`.
|
|
149
|
+
- A call that fails the run (an exception raised in code you put around a tool,
|
|
150
|
+
such as a wrapper of its executor; see
|
|
151
|
+
[What fails the run](tools.md#what-fails-the-run)) has no result at all. It
|
|
152
|
+
got its `BeforeToolCallEvent`, and its `ToolCallSpan` closes with `error` set
|
|
153
|
+
and `result` empty.
|
|
121
154
|
|
|
122
155
|
### Event context
|
|
123
156
|
|
|
@@ -137,8 +170,10 @@ runtime = AgentRuntime(agents={...}, services={...})
|
|
|
137
170
|
runtime.hooks.on(BeforeToolCallEvent, on_before_tool)
|
|
138
171
|
```
|
|
139
172
|
|
|
140
|
-
A `BeforeToolCallEvent` handler can
|
|
141
|
-
|
|
173
|
+
A `BeforeToolCallEvent` handler can replace `tool_use` to change a call's input,
|
|
174
|
+
but the new block keeps the call's `id`: changing the id raises `ValueError`.
|
|
175
|
+
It can also fill `headers` and `meta` to pass per-call data to the
|
|
176
|
+
tool — see [ToolCallInfo](tools.md#toolcallinfo).
|
|
142
177
|
|
|
143
178
|
Use `event.context.find_spec(SpecType)` to walk the execution stack and find
|
|
144
179
|
the spec of a parent agent — useful for identifying which model or session is
|
|
@@ -630,7 +630,9 @@ answers: raised in an agent, it fails the run.
|
|
|
630
630
|
When a `@tool` function raises, the executor `@tool` builds catches it and
|
|
631
631
|
returns an error result (except `InterruptedError`, see
|
|
632
632
|
[InterruptToken](#interrupttoken)), so the model can retry or adjust and the conversation
|
|
633
|
-
goes on. The same happens for invalid arguments and a missing service.
|
|
633
|
+
goes on. The same happens for invalid arguments and a missing service. A
|
|
634
|
+
[`ToolErrorPolicy`](#internal-failures) keeps the text of internal failures from
|
|
635
|
+
the model. Both
|
|
634
636
|
`registry.execute()` and a direct call to the executor return the result:
|
|
635
637
|
|
|
636
638
|
```python
|
|
@@ -647,11 +649,11 @@ print(result.error_kind) # ToolErrorKind.EXECUTION
|
|
|
647
649
|
|
|
648
650
|
`error_kind` says what went wrong:
|
|
649
651
|
|
|
650
|
-
| `ToolErrorKind` | When
|
|
651
|
-
|
|
652
|
-
| `UNKNOWN_TOOL` | The tool is not in the registry, is filtered out, or is unknown to the MCP server
|
|
653
|
-
| `SCHEMA_VALIDATION` | The arguments are not a JSON object or don't
|
|
654
|
-
| `EXECUTION` | The tool failed: the `@tool` function raised (`ToolError` with its own kind), or an MCP server returned an error or no valid answer
|
|
652
|
+
| `ToolErrorKind` | When |
|
|
653
|
+
|---------------------|------------------------------------------------------------------------------------------------------------------------------------------------|
|
|
654
|
+
| `UNKNOWN_TOOL` | The tool is not in the registry, is filtered out, or is unknown to the MCP server |
|
|
655
|
+
| `SCHEMA_VALIDATION` | The arguments are not a JSON object, don't match the schema, or don't load into the input dataclass (an invalid date, a `__post_init__` check) |
|
|
656
|
+
| `EXECUTION` | The tool failed: the `@tool` function raised (`ToolError` with its own kind), or an MCP server returned an error or no valid answer |
|
|
655
657
|
|
|
656
658
|
Agent tools (`@agent_tool`, `make_agent_tool`) answer invalid arguments the
|
|
657
659
|
same way. The agent they start runs as a child agent: an exception inside it
|
|
@@ -685,13 +687,52 @@ async def respond(params: RespondParams) -> Sent:
|
|
|
685
687
|
list of blocks; `exc.result` is the `ToolResult` it stands for. Returning
|
|
686
688
|
`ToolResult(content=..., is_error=True, error_kind=ToolErrorKind.EXECUTION)`
|
|
687
689
|
gives the same answer. Without `error_kind`, an error still reaches hooks and
|
|
688
|
-
spans as `EXECUTION
|
|
689
|
-
|
|
690
|
+
spans as `EXECUTION`. What they receive (`ToolCallResult`, `AfterToolCallEvent`,
|
|
691
|
+
`ToolCallSpan`) carries a kind exactly when it is an error, so there
|
|
692
|
+
`error_kind is not None` and `is_error` never disagree. The `ToolResult` that
|
|
693
|
+
`registry.execute` returns keeps the kind the tool gave it.
|
|
690
694
|
|
|
691
695
|
`ToolError` is for `@tool` functions: only their executor answers it. An agent
|
|
692
696
|
behind an [agent tool](#agents-as-tools) returns its error as a `ToolResult`
|
|
693
697
|
instead; a `ToolError` raised in an agent fails the run like any exception.
|
|
694
698
|
|
|
699
|
+
### Internal failures
|
|
700
|
+
|
|
701
|
+
By default every exception a `@tool` function raises reaches the model with its
|
|
702
|
+
text. That suits errors meant for the model, but not internal failures (a
|
|
703
|
+
database error, a failed HTTP call, a bug): the model can't act on them, and
|
|
704
|
+
their text can hold SQL, internal ids or customer data that the model may
|
|
705
|
+
repeat to the customer. A `ToolErrorPolicy` says which exception types are
|
|
706
|
+
answers for the model:
|
|
707
|
+
|
|
708
|
+
```python
|
|
709
|
+
from flowra.tools import ToolErrorPolicy, tool
|
|
710
|
+
|
|
711
|
+
ERRORS = ToolErrorPolicy(
|
|
712
|
+
answer=(TaskNotFoundError,),
|
|
713
|
+
failure="Error: the action failed, and it is unknown whether it took effect. Check before repeating it.",
|
|
714
|
+
)
|
|
715
|
+
|
|
716
|
+
@tool("create_task", errors=ERRORS)
|
|
717
|
+
async def create_task(params: CreateTaskParams, db: DatabaseClient) -> Created:
|
|
718
|
+
"""Create a support task."""
|
|
719
|
+
...
|
|
720
|
+
```
|
|
721
|
+
|
|
722
|
+
Every exception is logged with its traceback, as without a policy. One of a
|
|
723
|
+
type in `answer` (or a subclass) reaches the model as `"Error: {exception}"`;
|
|
724
|
+
any other is answered with `failure` (`EXECUTION`), which carries none of its
|
|
725
|
+
text; without `failure`, the answer is
|
|
726
|
+
`"Error: the tool failed with an internal error"`. `ToolError` and invalid
|
|
727
|
+
arguments (`SCHEMA_VALIDATION`) reach the model whatever the policy, so
|
|
728
|
+
`answer=()` is enough for a tool that raises `ToolError` for every error it
|
|
729
|
+
means for the model. A missing service is an internal failure.
|
|
730
|
+
|
|
731
|
+
The policy belongs to the decorator: define it once and pass it to every tool
|
|
732
|
+
it covers. A tool without one keeps the default: every exception's text reaches
|
|
733
|
+
the model, which suits tools whose exceptions are written for it, such as a fake
|
|
734
|
+
that stands in for an MCP server and raises the server's error text.
|
|
735
|
+
|
|
695
736
|
### What fails the run
|
|
696
737
|
|
|
697
738
|
Only the code inside a `@tool` executor is covered. An exception from code you
|
|
@@ -36,7 +36,7 @@ from ...llm import (
|
|
|
36
36
|
Usage,
|
|
37
37
|
UserMessage,
|
|
38
38
|
)
|
|
39
|
-
from ...tools import ToolRegistry
|
|
39
|
+
from ...tools import ToolRegistry
|
|
40
40
|
from ..config_value import resolve_config_value
|
|
41
41
|
from ..llm_caller import DEFAULT_LLM_CALLER, LLMCaller
|
|
42
42
|
from ..observability import UsageEvent
|
|
@@ -64,10 +64,18 @@ __all__ = ["TurnAgent"]
|
|
|
64
64
|
logger = logging.getLogger(__name__)
|
|
65
65
|
|
|
66
66
|
|
|
67
|
+
@dataclasses.dataclass(frozen=True, slots=True, kw_only=True)
|
|
68
|
+
class _AnsweredCalls:
|
|
69
|
+
"""The calls a ``BeforeToolCallsEvent`` handler answered, with the ids of the message's calls that can run,
|
|
70
|
+
in the message's order."""
|
|
71
|
+
|
|
72
|
+
results: list[ToolCallResult]
|
|
73
|
+
call_order: list[str]
|
|
74
|
+
|
|
75
|
+
|
|
67
76
|
class TurnAgent(Agent[TurnSpec, TurnResult]):
|
|
68
77
|
__slots__ = (
|
|
69
|
-
"
|
|
70
|
-
"__call_order",
|
|
78
|
+
"__answered_calls",
|
|
71
79
|
"__caller",
|
|
72
80
|
"__config",
|
|
73
81
|
"__consecutive_errors",
|
|
@@ -100,8 +108,7 @@ class TurnAgent(Agent[TurnSpec, TurnResult]):
|
|
|
100
108
|
self.__usage = store.ephemeral.slot(Scalar[Usage | None], "usage")
|
|
101
109
|
self.__consecutive_errors = store.ephemeral.slot(Scalar[dict[str, int]], "consecutive_errors")
|
|
102
110
|
self.__incomplete_tool_result = store.ephemeral.slot(Scalar[ToolResultBlock | None], "incomplete_tool_result")
|
|
103
|
-
self.
|
|
104
|
-
self.__call_order = store.ephemeral.slot(Scalar[list[str]], "call_order")
|
|
111
|
+
self.__answered_calls = store.ephemeral.slot(Scalar[_AnsweredCalls | None], "answered_calls")
|
|
105
112
|
self.__interrupt = interrupt
|
|
106
113
|
self.__context = TurnAgentContext()
|
|
107
114
|
self.__config = config
|
|
@@ -296,9 +303,9 @@ class TurnAgent(Agent[TurnSpec, TurnResult]):
|
|
|
296
303
|
consecutive_errors = dict(self.__consecutive_errors.get({}))
|
|
297
304
|
max_consecutive = await resolve_config_value(self.__config.max_consecutive_errors)
|
|
298
305
|
|
|
299
|
-
answered = self.
|
|
300
|
-
answered_ids = {tc_result.tool_use.id for tc_result in answered}
|
|
301
|
-
collected = self.__in_call_order(
|
|
306
|
+
answered = self.__answered_calls.get(None)
|
|
307
|
+
answered_ids = {tc_result.tool_use.id for tc_result in answered.results} if answered is not None else set()
|
|
308
|
+
collected = self.__in_call_order(answered, results) if answered is not None else results
|
|
302
309
|
for tc_result in collected:
|
|
303
310
|
after_event = await self.__hooks.emit(
|
|
304
311
|
AfterToolCallEvent(
|
|
@@ -343,9 +350,8 @@ class TurnAgent(Agent[TurnSpec, TurnResult]):
|
|
|
343
350
|
if incomplete_result is not None:
|
|
344
351
|
result_blocks.append(incomplete_result)
|
|
345
352
|
self.__incomplete_tool_result.set(None)
|
|
346
|
-
if answered:
|
|
347
|
-
self.
|
|
348
|
-
self.__call_order.set([])
|
|
353
|
+
if answered is not None:
|
|
354
|
+
self.__answered_calls.set(None)
|
|
349
355
|
|
|
350
356
|
self.__consecutive_errors.set(consecutive_errors)
|
|
351
357
|
user_message = UserMessage(blocks=list(result_blocks))
|
|
@@ -398,13 +404,14 @@ class TurnAgent(Agent[TurnSpec, TurnResult]):
|
|
|
398
404
|
raise ValueError(f"No tool call {tool_use_id!r} in this message")
|
|
399
405
|
# Answers are taken from the calls that can run, so the cut-off call keeps its own error result
|
|
400
406
|
answered = [
|
|
401
|
-
|
|
407
|
+
ToolCallResult.from_tool_result(tool_use, calls_event.results[tool_use.id])
|
|
402
408
|
for tool_use in tool_uses
|
|
403
409
|
if tool_use.id in calls_event.results
|
|
404
410
|
]
|
|
405
411
|
if answered:
|
|
406
|
-
self.
|
|
407
|
-
|
|
412
|
+
self.__answered_calls.set(
|
|
413
|
+
_AnsweredCalls(results=answered, call_order=[tool_use.id for tool_use in tool_uses])
|
|
414
|
+
)
|
|
408
415
|
|
|
409
416
|
amendments: dict[str, ToolUseBlock] = {}
|
|
410
417
|
final_calls: list[BeforeToolCallEvent] = []
|
|
@@ -418,6 +425,11 @@ class TurnAgent(Agent[TurnSpec, TurnResult]):
|
|
|
418
425
|
context=self.__context,
|
|
419
426
|
)
|
|
420
427
|
)
|
|
428
|
+
if before_event.tool_use.id != tool_use.id:
|
|
429
|
+
raise ValueError(
|
|
430
|
+
f"A BeforeToolCallEvent handler changed the id of tool call {tool_use.id!r} to "
|
|
431
|
+
f"{before_event.tool_use.id!r}; a call's id must stay as the model gave it"
|
|
432
|
+
)
|
|
421
433
|
final_calls.append(before_event)
|
|
422
434
|
if before_event.tool_use is not tool_use:
|
|
423
435
|
amendments[tool_use.id] = before_event.tool_use
|
|
@@ -447,19 +459,12 @@ class TurnAgent(Agent[TurnSpec, TurnResult]):
|
|
|
447
459
|
]
|
|
448
460
|
return Spawn(children=children, then=self.collect_results)
|
|
449
461
|
|
|
450
|
-
|
|
462
|
+
@staticmethod
|
|
463
|
+
def __in_call_order(answered: _AnsweredCalls, results: list[ToolCallResult]) -> list[ToolCallResult]:
|
|
451
464
|
# By the order the message's calls had when they were made, kept beside the answers: it holds
|
|
452
465
|
# whatever the history looks like by the time the results are collected
|
|
453
|
-
position = {tool_use_id: i for i, tool_use_id in enumerate(
|
|
454
|
-
return sorted(results, key=lambda tc_result: position[tc_result.tool_use.id])
|
|
455
|
-
|
|
456
|
-
@staticmethod
|
|
457
|
-
def __answered_result(tool_use: ToolUseBlock, result: ToolResult) -> ToolCallResult:
|
|
458
|
-
return ToolCallResult(
|
|
459
|
-
tool_use=tool_use,
|
|
460
|
-
result=ToolResultBlock(tool_use_id=tool_use.id, content=result.blocks, is_error=result.is_error),
|
|
461
|
-
error_kind=result.error_kind,
|
|
462
|
-
)
|
|
466
|
+
position = {tool_use_id: i for i, tool_use_id in enumerate(answered.call_order)}
|
|
467
|
+
return sorted([*answered.results, *results], key=lambda tc_result: position[tc_result.tool_use.id])
|
|
463
468
|
|
|
464
469
|
@staticmethod
|
|
465
470
|
def __incomplete_tool_use_message(stop_reason: StopReason) -> str:
|