agenticstar-platform 3.2.0__tar.gz → 3.2.1__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.
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/PKG-INFO +129 -5
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/README.md +128 -4
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/__init__.py +1 -1
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/workflow/child.py +10 -4
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/workflow/context.py +46 -2
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/workflow/envelope.py +60 -6
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/workflow/runner.py +39 -3
- agenticstar_platform-3.2.1/agenticstar_platform/workflow/testing.py +449 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/docs/examples/workflow_reply_agent.py +42 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/pyproject.toml +1 -1
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/workflow/agent_fixtures.py +87 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/workflow/test_child_failure_summary.py +9 -0
- agenticstar_platform-3.2.1/tests/workflow/test_workflow_incomplete.py +322 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/workflow/test_workflow_runner.py +14 -8
- agenticstar_platform-3.2.1/tests/workflow/test_workflow_testing.py +229 -0
- agenticstar_platform-3.2.0/.gitignore +0 -270
- agenticstar_platform-3.2.0/tests/workflow/fake_runtime.py +0 -267
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/LICENSE +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/_config_utils.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/audit/ROW_HASH_SPEC.md +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/audit/__init__.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/audit/action_audit.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/audit/guardrail_alerts.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/audit/row_hash_fixture.json +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/auth/__init__.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/auth/client.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/auth/config.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/auth/exceptions.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/auth/models.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/common/__init__.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/common/context_manager.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/common/secrets.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/common/validation.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/db/__init__.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/db/api_manager.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/db/completion_report.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/db/config.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/db/config_access.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/db/data_access.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/db/execution_access.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/db/factory.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/db/manager.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/db/pod_runtime.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/db/started_fence.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/db/telemetry_access.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/db/wire_types.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/events/__init__.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/events/emitter.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/events/handlers.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/events/models.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/events/types.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/lab/README.md +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/lab/__init__.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/lab/__main__.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/lab/checks.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/lab/docker-compose.yml +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/lab/doctor.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/lab/lab_config.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/lab/offline_embedding.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/lab/run_lab.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/lab/seed.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/memory/__init__.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/memory/semantic.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/metering/__init__.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/metering/meter.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/policy/__init__.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/policy/internal_operations.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/policy/model.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/rag/__init__.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/rag/base.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/rag/embedding.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/rag/qdrant_manager.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/runner.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/runtime.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/security/__init__.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/security/aws.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/security/azure.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/security/base.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/security/content_safety_validator.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/security/factory.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/security/gcp.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/storage/__init__.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/storage/azure.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/storage/base.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/storage/gcs.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/storage/paths.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/storage/s3.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/workflow/__init__.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/workflow/canonical.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/workflow/errors.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/workflow/files.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/workflow/runtime_client.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/workflow/schema.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/docs/agenticstar_platform.html +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/docs/examples/workflow_mock_send_agent.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/docs/index.html +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/docs/search.js +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/__init__.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/audit/__init__.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/audit/test_action_audit_30.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/audit/test_row_hash_fixture.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/auth/__init__.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/auth/test_auth_type_bearer_only.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/auth/test_get_user_path_encoding.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/auth/test_mcp_tokens_expiry.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/auth/test_mcp_tokens_rejected.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/db/__init__.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/db/test_api_manager_drain_and_headers.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/db/test_completion_report.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/db/test_data_access_identifier_validation.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/db/test_manager_execute_query_dispatch.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/db/test_telemetry_tools_used_contract.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/db/test_wire_param_types.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/events/__init__.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/events/test_handler_type_routing.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/lab/test_lab_contract.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/lab/test_lab_docker.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/memory/__init__.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/memory/test_semantic_converter_base_url.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/metering/__init__.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/metering/test_meter_cache_split.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/policy/__init__.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/policy/test_a2a_connection_rule.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/policy/test_decision_layer.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/policy/test_evaluate_decision_table.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/policy/test_policy_model.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/policy/test_scoped_forbid.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/rag/__init__.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/rag/test_embedding_dimensions.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/rag/test_qdrant_error_hierarchy.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/rag/test_qdrant_get_statistics.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/runner/__init__.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/runner/test_marketplace_runner_contract.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/runner/test_marketplace_runner_db_fallback.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/runner/test_marketplace_runner_started_fence.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/security/__init__.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/security/test_azure_connect_retry.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/security/test_azure_prompt_shield_documents.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/security/test_factory_vertex_ai_safety.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/security/test_gcp_vertex_ai_safety.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/storage/__init__.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/storage/test_azure_credential.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/test_lazy_import_contract.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/test_readme_quickstart.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/test_storage_provider_extra_contract.py +0 -0
- {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/workflow/__init__.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: agenticstar-platform
|
|
3
|
-
Version: 3.2.
|
|
3
|
+
Version: 3.2.1
|
|
4
4
|
Summary: AGENTICSTAR Platform SDK - Enterprise AI Agent Infrastructure
|
|
5
5
|
Project-URL: Homepage, https://developers.fd.agenticstar.tm.softbank.jp/
|
|
6
6
|
Project-URL: Documentation, https://developers.fd.agenticstar.tm.softbank.jp/
|
|
@@ -687,7 +687,9 @@ What `context` provides: correlation (`execution_id` / `run_id` / `operation_key
|
|
|
687
687
|
do not start an external write without that acknowledgement), `is_cancel_requested()` /
|
|
688
688
|
`ensure_can_act()` / `deadline_remaining()`, `skip(reason)` (a step with nothing to do: `no_target` /
|
|
689
689
|
`not_applicable` / `nothing_to_do` → `skipped`), `policy_unavailable()` (the policy could not be
|
|
690
|
-
checked before any external action → `skipped/policy_unavailable`), `
|
|
690
|
+
checked before any external action → `skipped/policy_unavailable`), `incomplete(reason, comment=None)` (SDK ≥ 3.2.1:
|
|
691
|
+
the step could not be completed and running it again would not help → `incomplete/<reason>`; see below),
|
|
692
|
+
`log(message)` (written to the runner's
|
|
691
693
|
log; `run()` sends SDK logs at INFO to stderr when the process has not configured logging),
|
|
692
694
|
`gate_decision` (SDK ≥ 3.0.9: the review decision that started this run — `None` unless the run follows a
|
|
693
695
|
review; otherwise a read-only mapping `{gate_id, decision, decided_by, note, decided_at}` where `decision` is
|
|
@@ -730,11 +732,46 @@ async def run(context):
|
|
|
730
732
|
...
|
|
731
733
|
```
|
|
732
734
|
|
|
735
|
+
**Ending a step as not completed** (SDK ≥ 3.2.1). When your agent cannot complete the step and running it again would
|
|
736
|
+
give the same result — the instructions are missing, a setting is wrong — call `context.incomplete(reason, comment)` and
|
|
737
|
+
return. The platform does not retry the step automatically; it asks a person to check it and shows the reason and the
|
|
738
|
+
comment in the execution record.
|
|
739
|
+
|
|
740
|
+
```python
|
|
741
|
+
async def run(context):
|
|
742
|
+
instructions = (context.work_dir / "instructions.md").read_text(encoding="utf-8")
|
|
743
|
+
if not instructions.strip():
|
|
744
|
+
await context.incomplete("missing_instructions",
|
|
745
|
+
comment="instructions.md is empty. Write the instructions and run the step again.")
|
|
746
|
+
return
|
|
747
|
+
...
|
|
748
|
+
```
|
|
749
|
+
|
|
750
|
+
- `reason` is a reason code with the same rules as `report_completion()` of cycle executions: lowercase snake_case of at
|
|
751
|
+
most 32 characters (`-` and spaces become `_`, upper case becomes lower case). Any other value (a sentence, an exception
|
|
752
|
+
string) becomes `incomplete` and a warning is logged
|
|
753
|
+
- `comment` (optional) is a short explanation for the person who checks the step. It is cut at 2,048 characters (counted
|
|
754
|
+
as UTF-16 code units, like JavaScript). Do not put secrets or personal data in it
|
|
755
|
+
- Declare once. A second call is not recorded (the first one is kept and the runner logs a warning). An exception after
|
|
756
|
+
the declaration still ends the step as `incomplete`
|
|
757
|
+
- An audit persistence failure, cancellation, the deadline, the execution being closed elsewhere, a pod stop signal and
|
|
758
|
+
a denied tool call decide the outcome before the declaration
|
|
759
|
+
- For a failure that may go away on its own (a timeout of an external service, a rate limit), raise an exception
|
|
760
|
+
instead: the platform retries `failed/agent_error` (up to its retry limit) when the contract's effect mode is
|
|
761
|
+
`read_only` or `idempotent_write` and the effects are known
|
|
762
|
+
|
|
763
|
+
The completion then carries an **end-of-run report**, `completion_report`, in the same form as the platform's own agents:
|
|
764
|
+
`{"completed": false, "reason_code": ..., "comment": ...}`. For `incomplete` the comment is yours (no `comment` key when
|
|
765
|
+
you gave none); for an exception (`failed/agent_error`) the comment is the cause chain the runner writes to stderr —
|
|
766
|
+
class names, the SDK's error code, the HTTP status and the destination host name only, never messages, URLs or tokens.
|
|
767
|
+
Other outcomes carry no report. A platform that does not read the report yet keeps the completion and drops the report.
|
|
768
|
+
|
|
733
769
|
The outcome describes how the run ended, with 7 values (`completed` / `incomplete` / `failed` /
|
|
734
770
|
`timeout` / `stopped` / `denied` / `skipped`). **Success means the agent ran to completion**: the agent
|
|
735
771
|
function returns normally → `completed/completed`, unless an audit persistence failure, a denied tool
|
|
736
|
-
call, an invalid declared output, a skip or a missing required output decides otherwise (failed writes,
|
|
737
|
-
unobserved effects or zero observations do not lower the outcome);
|
|
772
|
+
call, a declared `incomplete`, an invalid declared output, a skip or a missing required output decides otherwise (failed writes,
|
|
773
|
+
unobserved effects or zero observations do not lower the outcome); `context.incomplete(reason)` → `incomplete/<reason>`;
|
|
774
|
+
an exception → `failed/agent_error`; cancellation →
|
|
738
775
|
`stopped/cancelled`; deadline → `timeout/execution_timeout`; pod stop signal → `failed/runner_stopped`;
|
|
739
776
|
a call reported with `audit.tool_denied` → `denied`.
|
|
740
777
|
What was written is kept in `counts` / `tools` and `had_mutating_success` (true = success observed /
|
|
@@ -743,6 +780,83 @@ automatically and go to a human (effects that already happened are never undone)
|
|
|
743
780
|
source distribution: `docs/examples/workflow_reply_agent.py` (drafting a reply) /
|
|
744
781
|
`workflow_mock_send_agent.py` (a mock send).
|
|
745
782
|
|
|
783
|
+
**Testing an agent without ASTER** (SDK ≥ 3.2.1). `agenticstar_platform.workflow.testing.FakeRuntime` answers the
|
|
784
|
+
platform's runtime API in memory. Give it your contract, the step's parameters, the input files, the connection tokens,
|
|
785
|
+
the effect mode and the deadline, run one step with `arun(...)`, then read what the runner saved. With this layout:
|
|
786
|
+
|
|
787
|
+
```text
|
|
788
|
+
my_project/
|
|
789
|
+
my_agent/__init__.py (empty)
|
|
790
|
+
my_agent/main.py (your agent)
|
|
791
|
+
try_it.py (the script below)
|
|
792
|
+
```
|
|
793
|
+
|
|
794
|
+
```python
|
|
795
|
+
# my_agent/main.py
|
|
796
|
+
async def run(context):
|
|
797
|
+
instructions = (context.work_dir / "instructions.md").read_text(encoding="utf-8")
|
|
798
|
+
(context.output_dir / "reply.md").write_text(f"# Reply\n\n{instructions}", encoding="utf-8")
|
|
799
|
+
```
|
|
800
|
+
|
|
801
|
+
```python
|
|
802
|
+
# try_it.py
|
|
803
|
+
import asyncio
|
|
804
|
+
import tempfile
|
|
805
|
+
|
|
806
|
+
from agenticstar_platform.workflow import arun
|
|
807
|
+
from agenticstar_platform.workflow.testing import FakeRuntime
|
|
808
|
+
|
|
809
|
+
CONTRACT = {
|
|
810
|
+
"runtime_protocol": "mp-workflow/1", "effect_mode": "read_only",
|
|
811
|
+
"files": [{"name": "instructions", "path": "instructions.md", "format": "markdown", "required": True}],
|
|
812
|
+
"outputs": [{"name": "reply", "path": "reply.md", "format": "markdown", "required": True}],
|
|
813
|
+
"limits": {"execution_timeout_seconds": 600},
|
|
814
|
+
}
|
|
815
|
+
|
|
816
|
+
|
|
817
|
+
async def main():
|
|
818
|
+
fake = FakeRuntime(
|
|
819
|
+
contract=CONTRACT,
|
|
820
|
+
parameters={"product_code": "P-100", "language": "en"},
|
|
821
|
+
inputs={"instructions": b"Thank the customer.\n"}, # by the name of a contract file
|
|
822
|
+
connections={"crm": "test-access-token"}, # slot -> token, or (token, expires_at)
|
|
823
|
+
deadline_seconds=600,
|
|
824
|
+
)
|
|
825
|
+
with tempfile.TemporaryDirectory() as workspace:
|
|
826
|
+
result = await arun("my_agent.main:run", env=fake.runner_env(), workspace=workspace, transport=fake.transport)
|
|
827
|
+
print(result.outcome, result.outcome_reason_code) # completed completed
|
|
828
|
+
print(fake.saved_artifacts()["reply"]["content"]) # the saved output, by its name
|
|
829
|
+
print([e["event_type"] for e in fake.saved_audit_events()]) # context.manifest x2, then your audit events
|
|
830
|
+
print(fake.saved_completion()["envelope"]) # the completion_envelope
|
|
831
|
+
|
|
832
|
+
|
|
833
|
+
asyncio.run(main())
|
|
834
|
+
```
|
|
835
|
+
|
|
836
|
+
```bash
|
|
837
|
+
cd my_project
|
|
838
|
+
PYTHONPATH="$PWD" python try_it.py
|
|
839
|
+
```
|
|
840
|
+
|
|
841
|
+
- The runner starts your entrypoint in a child process whose current directory is the work directory, so `my_agent.main`
|
|
842
|
+
must be importable from `PYTHONPATH` **as an absolute path** (`PYTHONPATH="$PWD"`, not `PYTHONPATH=.`: the child would
|
|
843
|
+
look for `.` in the work directory) or installed. In a test, set `os.environ["PYTHONPATH"]` to the absolute path before
|
|
844
|
+
calling `arun`
|
|
845
|
+
- The fake copies the current behaviour of the runtime API (only declared outputs are saved, a `completed` outcome needs
|
|
846
|
+
the required outputs, writes after cancellation, the end of the run or the deadline are refused except the audit
|
|
847
|
+
records of what the agent already did (`tool.effect` / `tool.denied`), ...). It **does not check the parameters
|
|
848
|
+
against `parameters_schema` or validate the contract**: the platform checks those before a run (the admin console's
|
|
849
|
+
check before registration and the executor). Parameters are passed to your agent as given
|
|
850
|
+
- **Supported surface**: the constructor arguments, `runner_env()`, `transport`, `saved_artifacts()` /
|
|
851
|
+
`saved_audit_events()` / `saved_completion()`, `sample_contract()` / `sample_parameters()`, the constants
|
|
852
|
+
`EXECUTION_ID` / `TOKEN` / `BASE_URL`, and the attributes that simulate the platform, which you can change before or
|
|
853
|
+
during a run: `contract` (a copy of the one you passed; later requests see your changes), `cancel_requested_at` (an ISO time = cancellation
|
|
854
|
+
was requested), `run_closed`, `deadline_passed`, `gate_decision`, `start_input`, `fail_audit_types`,
|
|
855
|
+
`fail_upload_times`, `fail_completion_times`, `fail_download_times` (see the module's docstring). Everything else is
|
|
856
|
+
internal and may change
|
|
857
|
+
- Without arguments the fake uses the contract and parameters of `docs/examples/workflow_reply_agent.py`; run
|
|
858
|
+
`python docs/examples/workflow_reply_agent.py` (source distribution) to see one step end to end
|
|
859
|
+
|
|
746
860
|
### Policy Module — `agenticstar_platform.policy` (SDK ≥ 1.0.0a1)
|
|
747
861
|
|
|
748
862
|
Pure computation (no I/O, no agent framework): decide **allow / forbid** for a tool call from a two-layer policy.
|
|
@@ -993,6 +1107,16 @@ See the [developer portal](https://developers.fd.agenticstar.tm.softbank.jp/) fo
|
|
|
993
1107
|
|
|
994
1108
|
## Changelog
|
|
995
1109
|
|
|
1110
|
+
### 3.2.1 (2026-10-28) — workflow: end a step as not completed (`context.incomplete`) with an end-of-run report / a fake runtime for testing (`agenticstar_platform.workflow.testing`)
|
|
1111
|
+
|
|
1112
|
+
- **New `WorkflowContext.incomplete(reason, comment=None)`.** An agent that cannot complete its step, where running it again would give the same result (missing instructions, a wrong setting), ends the step as `incomplete` with `reason` as the reason code. The platform does not retry it automatically and asks a person to check it. `reason` follows the rules of `report_completion()` (lowercase snake_case of at most 32 characters; any other value becomes `incomplete` with a warning); `comment` is cut at 2,048 UTF-16 code units. The declaration comes after an audit persistence failure, cancellation, the deadline, the execution being closed elsewhere, a pod stop signal and a denied tool call, and before an exception (an exception after the declaration still ends as `incomplete`), an invalid output, a skip and a missing required output. A second declaration is not recorded. See "Ending a step as not completed" in the Workflow Runner section.
|
|
1113
|
+
- **The completion carries an end-of-run report** (`completion_report`: `completed: false`, `reason_code`, `comment`) for `incomplete` (the agent's comment) and for an agent exception, `failed/agent_error` (the redacted cause chain the child already writes to stderr since 3.1.3: class names, the SDK's error code, the HTTP status and the host name; at most 2,048 UTF-16 code units, also with `ASTER_WORKFLOW_DEBUG_TRACEBACK=1`). Other outcomes carry no report, so their completion is the same as in 3.2. A platform that does not read the report yet keeps the completion and drops the report. A `comment` that is not a string (an exception, for example) is left out with a warning, so its message never reaches the report.
|
|
1114
|
+
- **The cause chain shows an `error_code` only in the SDK's own form** (upper-case snake_case of at most 64 characters, such as `REQUEST_ERROR`), in stderr and in the report. An SDK exception that agent code created with another value no longer shows that value.
|
|
1115
|
+
- **New `agenticstar_platform.workflow.testing`**: `FakeRuntime`, an in-memory copy of the platform's runtime API for testing an agent without ASTER. It takes the contract, parameters, input files, connection tokens, effect mode, deadline and instructions as arguments, and `saved_artifacts()` / `saved_audit_events()` / `saved_completion()` read what the runner saved. It does not check the parameters or the contract (the platform checks them before a run). Like the platform, it accepts the audit records of what the agent already did (`tool.effect` / `tool.denied`) after cancellation, the end of the run or the deadline, and reports the end of the run in the context's `cancel_requested_at`. The supported surface (constructor arguments, `runner_env()`, `transport`, the `saved_*()` readers and the listed simulation attributes) is described in the module's docstring; everything else is internal. The SDK's own tests now use it. `import agenticstar_platform.workflow` does not import it.
|
|
1116
|
+
- The sample `docs/examples/workflow_reply_agent.py` ends as `incomplete/missing_instructions` when the instructions are empty, and running the file runs one step against `FakeRuntime`.
|
|
1117
|
+
- `build_envelope(...)` accepts an optional `completion_report`. Other public functions of the runner and the context are unchanged.
|
|
1118
|
+
- To use it, rebuild the agent image with this SDK.
|
|
1119
|
+
|
|
996
1120
|
### 3.2.0 (2026-10-26) — auth: the `api_key` authentication mode (`X-Internal-API-Key` header) is removed
|
|
997
1121
|
|
|
998
1122
|
The version follows the platform release (3.2.0).
|
|
@@ -1429,4 +1553,4 @@ Marketplace SDK reliability fixes (surfaced while building agents from the guide
|
|
|
1429
1553
|
|
|
1430
1554
|
## Version
|
|
1431
1555
|
|
|
1432
|
-
3.2.
|
|
1556
|
+
3.2.1
|
|
@@ -606,7 +606,9 @@ What `context` provides: correlation (`execution_id` / `run_id` / `operation_key
|
|
|
606
606
|
do not start an external write without that acknowledgement), `is_cancel_requested()` /
|
|
607
607
|
`ensure_can_act()` / `deadline_remaining()`, `skip(reason)` (a step with nothing to do: `no_target` /
|
|
608
608
|
`not_applicable` / `nothing_to_do` → `skipped`), `policy_unavailable()` (the policy could not be
|
|
609
|
-
checked before any external action → `skipped/policy_unavailable`), `
|
|
609
|
+
checked before any external action → `skipped/policy_unavailable`), `incomplete(reason, comment=None)` (SDK ≥ 3.2.1:
|
|
610
|
+
the step could not be completed and running it again would not help → `incomplete/<reason>`; see below),
|
|
611
|
+
`log(message)` (written to the runner's
|
|
610
612
|
log; `run()` sends SDK logs at INFO to stderr when the process has not configured logging),
|
|
611
613
|
`gate_decision` (SDK ≥ 3.0.9: the review decision that started this run — `None` unless the run follows a
|
|
612
614
|
review; otherwise a read-only mapping `{gate_id, decision, decided_by, note, decided_at}` where `decision` is
|
|
@@ -649,11 +651,46 @@ async def run(context):
|
|
|
649
651
|
...
|
|
650
652
|
```
|
|
651
653
|
|
|
654
|
+
**Ending a step as not completed** (SDK ≥ 3.2.1). When your agent cannot complete the step and running it again would
|
|
655
|
+
give the same result — the instructions are missing, a setting is wrong — call `context.incomplete(reason, comment)` and
|
|
656
|
+
return. The platform does not retry the step automatically; it asks a person to check it and shows the reason and the
|
|
657
|
+
comment in the execution record.
|
|
658
|
+
|
|
659
|
+
```python
|
|
660
|
+
async def run(context):
|
|
661
|
+
instructions = (context.work_dir / "instructions.md").read_text(encoding="utf-8")
|
|
662
|
+
if not instructions.strip():
|
|
663
|
+
await context.incomplete("missing_instructions",
|
|
664
|
+
comment="instructions.md is empty. Write the instructions and run the step again.")
|
|
665
|
+
return
|
|
666
|
+
...
|
|
667
|
+
```
|
|
668
|
+
|
|
669
|
+
- `reason` is a reason code with the same rules as `report_completion()` of cycle executions: lowercase snake_case of at
|
|
670
|
+
most 32 characters (`-` and spaces become `_`, upper case becomes lower case). Any other value (a sentence, an exception
|
|
671
|
+
string) becomes `incomplete` and a warning is logged
|
|
672
|
+
- `comment` (optional) is a short explanation for the person who checks the step. It is cut at 2,048 characters (counted
|
|
673
|
+
as UTF-16 code units, like JavaScript). Do not put secrets or personal data in it
|
|
674
|
+
- Declare once. A second call is not recorded (the first one is kept and the runner logs a warning). An exception after
|
|
675
|
+
the declaration still ends the step as `incomplete`
|
|
676
|
+
- An audit persistence failure, cancellation, the deadline, the execution being closed elsewhere, a pod stop signal and
|
|
677
|
+
a denied tool call decide the outcome before the declaration
|
|
678
|
+
- For a failure that may go away on its own (a timeout of an external service, a rate limit), raise an exception
|
|
679
|
+
instead: the platform retries `failed/agent_error` (up to its retry limit) when the contract's effect mode is
|
|
680
|
+
`read_only` or `idempotent_write` and the effects are known
|
|
681
|
+
|
|
682
|
+
The completion then carries an **end-of-run report**, `completion_report`, in the same form as the platform's own agents:
|
|
683
|
+
`{"completed": false, "reason_code": ..., "comment": ...}`. For `incomplete` the comment is yours (no `comment` key when
|
|
684
|
+
you gave none); for an exception (`failed/agent_error`) the comment is the cause chain the runner writes to stderr —
|
|
685
|
+
class names, the SDK's error code, the HTTP status and the destination host name only, never messages, URLs or tokens.
|
|
686
|
+
Other outcomes carry no report. A platform that does not read the report yet keeps the completion and drops the report.
|
|
687
|
+
|
|
652
688
|
The outcome describes how the run ended, with 7 values (`completed` / `incomplete` / `failed` /
|
|
653
689
|
`timeout` / `stopped` / `denied` / `skipped`). **Success means the agent ran to completion**: the agent
|
|
654
690
|
function returns normally → `completed/completed`, unless an audit persistence failure, a denied tool
|
|
655
|
-
call, an invalid declared output, a skip or a missing required output decides otherwise (failed writes,
|
|
656
|
-
unobserved effects or zero observations do not lower the outcome);
|
|
691
|
+
call, a declared `incomplete`, an invalid declared output, a skip or a missing required output decides otherwise (failed writes,
|
|
692
|
+
unobserved effects or zero observations do not lower the outcome); `context.incomplete(reason)` → `incomplete/<reason>`;
|
|
693
|
+
an exception → `failed/agent_error`; cancellation →
|
|
657
694
|
`stopped/cancelled`; deadline → `timeout/execution_timeout`; pod stop signal → `failed/runner_stopped`;
|
|
658
695
|
a call reported with `audit.tool_denied` → `denied`.
|
|
659
696
|
What was written is kept in `counts` / `tools` and `had_mutating_success` (true = success observed /
|
|
@@ -662,6 +699,83 @@ automatically and go to a human (effects that already happened are never undone)
|
|
|
662
699
|
source distribution: `docs/examples/workflow_reply_agent.py` (drafting a reply) /
|
|
663
700
|
`workflow_mock_send_agent.py` (a mock send).
|
|
664
701
|
|
|
702
|
+
**Testing an agent without ASTER** (SDK ≥ 3.2.1). `agenticstar_platform.workflow.testing.FakeRuntime` answers the
|
|
703
|
+
platform's runtime API in memory. Give it your contract, the step's parameters, the input files, the connection tokens,
|
|
704
|
+
the effect mode and the deadline, run one step with `arun(...)`, then read what the runner saved. With this layout:
|
|
705
|
+
|
|
706
|
+
```text
|
|
707
|
+
my_project/
|
|
708
|
+
my_agent/__init__.py (empty)
|
|
709
|
+
my_agent/main.py (your agent)
|
|
710
|
+
try_it.py (the script below)
|
|
711
|
+
```
|
|
712
|
+
|
|
713
|
+
```python
|
|
714
|
+
# my_agent/main.py
|
|
715
|
+
async def run(context):
|
|
716
|
+
instructions = (context.work_dir / "instructions.md").read_text(encoding="utf-8")
|
|
717
|
+
(context.output_dir / "reply.md").write_text(f"# Reply\n\n{instructions}", encoding="utf-8")
|
|
718
|
+
```
|
|
719
|
+
|
|
720
|
+
```python
|
|
721
|
+
# try_it.py
|
|
722
|
+
import asyncio
|
|
723
|
+
import tempfile
|
|
724
|
+
|
|
725
|
+
from agenticstar_platform.workflow import arun
|
|
726
|
+
from agenticstar_platform.workflow.testing import FakeRuntime
|
|
727
|
+
|
|
728
|
+
CONTRACT = {
|
|
729
|
+
"runtime_protocol": "mp-workflow/1", "effect_mode": "read_only",
|
|
730
|
+
"files": [{"name": "instructions", "path": "instructions.md", "format": "markdown", "required": True}],
|
|
731
|
+
"outputs": [{"name": "reply", "path": "reply.md", "format": "markdown", "required": True}],
|
|
732
|
+
"limits": {"execution_timeout_seconds": 600},
|
|
733
|
+
}
|
|
734
|
+
|
|
735
|
+
|
|
736
|
+
async def main():
|
|
737
|
+
fake = FakeRuntime(
|
|
738
|
+
contract=CONTRACT,
|
|
739
|
+
parameters={"product_code": "P-100", "language": "en"},
|
|
740
|
+
inputs={"instructions": b"Thank the customer.\n"}, # by the name of a contract file
|
|
741
|
+
connections={"crm": "test-access-token"}, # slot -> token, or (token, expires_at)
|
|
742
|
+
deadline_seconds=600,
|
|
743
|
+
)
|
|
744
|
+
with tempfile.TemporaryDirectory() as workspace:
|
|
745
|
+
result = await arun("my_agent.main:run", env=fake.runner_env(), workspace=workspace, transport=fake.transport)
|
|
746
|
+
print(result.outcome, result.outcome_reason_code) # completed completed
|
|
747
|
+
print(fake.saved_artifacts()["reply"]["content"]) # the saved output, by its name
|
|
748
|
+
print([e["event_type"] for e in fake.saved_audit_events()]) # context.manifest x2, then your audit events
|
|
749
|
+
print(fake.saved_completion()["envelope"]) # the completion_envelope
|
|
750
|
+
|
|
751
|
+
|
|
752
|
+
asyncio.run(main())
|
|
753
|
+
```
|
|
754
|
+
|
|
755
|
+
```bash
|
|
756
|
+
cd my_project
|
|
757
|
+
PYTHONPATH="$PWD" python try_it.py
|
|
758
|
+
```
|
|
759
|
+
|
|
760
|
+
- The runner starts your entrypoint in a child process whose current directory is the work directory, so `my_agent.main`
|
|
761
|
+
must be importable from `PYTHONPATH` **as an absolute path** (`PYTHONPATH="$PWD"`, not `PYTHONPATH=.`: the child would
|
|
762
|
+
look for `.` in the work directory) or installed. In a test, set `os.environ["PYTHONPATH"]` to the absolute path before
|
|
763
|
+
calling `arun`
|
|
764
|
+
- The fake copies the current behaviour of the runtime API (only declared outputs are saved, a `completed` outcome needs
|
|
765
|
+
the required outputs, writes after cancellation, the end of the run or the deadline are refused except the audit
|
|
766
|
+
records of what the agent already did (`tool.effect` / `tool.denied`), ...). It **does not check the parameters
|
|
767
|
+
against `parameters_schema` or validate the contract**: the platform checks those before a run (the admin console's
|
|
768
|
+
check before registration and the executor). Parameters are passed to your agent as given
|
|
769
|
+
- **Supported surface**: the constructor arguments, `runner_env()`, `transport`, `saved_artifacts()` /
|
|
770
|
+
`saved_audit_events()` / `saved_completion()`, `sample_contract()` / `sample_parameters()`, the constants
|
|
771
|
+
`EXECUTION_ID` / `TOKEN` / `BASE_URL`, and the attributes that simulate the platform, which you can change before or
|
|
772
|
+
during a run: `contract` (a copy of the one you passed; later requests see your changes), `cancel_requested_at` (an ISO time = cancellation
|
|
773
|
+
was requested), `run_closed`, `deadline_passed`, `gate_decision`, `start_input`, `fail_audit_types`,
|
|
774
|
+
`fail_upload_times`, `fail_completion_times`, `fail_download_times` (see the module's docstring). Everything else is
|
|
775
|
+
internal and may change
|
|
776
|
+
- Without arguments the fake uses the contract and parameters of `docs/examples/workflow_reply_agent.py`; run
|
|
777
|
+
`python docs/examples/workflow_reply_agent.py` (source distribution) to see one step end to end
|
|
778
|
+
|
|
665
779
|
### Policy Module — `agenticstar_platform.policy` (SDK ≥ 1.0.0a1)
|
|
666
780
|
|
|
667
781
|
Pure computation (no I/O, no agent framework): decide **allow / forbid** for a tool call from a two-layer policy.
|
|
@@ -912,6 +1026,16 @@ See the [developer portal](https://developers.fd.agenticstar.tm.softbank.jp/) fo
|
|
|
912
1026
|
|
|
913
1027
|
## Changelog
|
|
914
1028
|
|
|
1029
|
+
### 3.2.1 (2026-10-28) — workflow: end a step as not completed (`context.incomplete`) with an end-of-run report / a fake runtime for testing (`agenticstar_platform.workflow.testing`)
|
|
1030
|
+
|
|
1031
|
+
- **New `WorkflowContext.incomplete(reason, comment=None)`.** An agent that cannot complete its step, where running it again would give the same result (missing instructions, a wrong setting), ends the step as `incomplete` with `reason` as the reason code. The platform does not retry it automatically and asks a person to check it. `reason` follows the rules of `report_completion()` (lowercase snake_case of at most 32 characters; any other value becomes `incomplete` with a warning); `comment` is cut at 2,048 UTF-16 code units. The declaration comes after an audit persistence failure, cancellation, the deadline, the execution being closed elsewhere, a pod stop signal and a denied tool call, and before an exception (an exception after the declaration still ends as `incomplete`), an invalid output, a skip and a missing required output. A second declaration is not recorded. See "Ending a step as not completed" in the Workflow Runner section.
|
|
1032
|
+
- **The completion carries an end-of-run report** (`completion_report`: `completed: false`, `reason_code`, `comment`) for `incomplete` (the agent's comment) and for an agent exception, `failed/agent_error` (the redacted cause chain the child already writes to stderr since 3.1.3: class names, the SDK's error code, the HTTP status and the host name; at most 2,048 UTF-16 code units, also with `ASTER_WORKFLOW_DEBUG_TRACEBACK=1`). Other outcomes carry no report, so their completion is the same as in 3.2. A platform that does not read the report yet keeps the completion and drops the report. A `comment` that is not a string (an exception, for example) is left out with a warning, so its message never reaches the report.
|
|
1033
|
+
- **The cause chain shows an `error_code` only in the SDK's own form** (upper-case snake_case of at most 64 characters, such as `REQUEST_ERROR`), in stderr and in the report. An SDK exception that agent code created with another value no longer shows that value.
|
|
1034
|
+
- **New `agenticstar_platform.workflow.testing`**: `FakeRuntime`, an in-memory copy of the platform's runtime API for testing an agent without ASTER. It takes the contract, parameters, input files, connection tokens, effect mode, deadline and instructions as arguments, and `saved_artifacts()` / `saved_audit_events()` / `saved_completion()` read what the runner saved. It does not check the parameters or the contract (the platform checks them before a run). Like the platform, it accepts the audit records of what the agent already did (`tool.effect` / `tool.denied`) after cancellation, the end of the run or the deadline, and reports the end of the run in the context's `cancel_requested_at`. The supported surface (constructor arguments, `runner_env()`, `transport`, the `saved_*()` readers and the listed simulation attributes) is described in the module's docstring; everything else is internal. The SDK's own tests now use it. `import agenticstar_platform.workflow` does not import it.
|
|
1035
|
+
- The sample `docs/examples/workflow_reply_agent.py` ends as `incomplete/missing_instructions` when the instructions are empty, and running the file runs one step against `FakeRuntime`.
|
|
1036
|
+
- `build_envelope(...)` accepts an optional `completion_report`. Other public functions of the runner and the context are unchanged.
|
|
1037
|
+
- To use it, rebuild the agent image with this SDK.
|
|
1038
|
+
|
|
915
1039
|
### 3.2.0 (2026-10-26) — auth: the `api_key` authentication mode (`X-Internal-API-Key` header) is removed
|
|
916
1040
|
|
|
917
1041
|
The version follows the platform release (3.2.0).
|
|
@@ -1348,4 +1472,4 @@ Marketplace SDK reliability fixes (surfaced while building agents from the guide
|
|
|
1348
1472
|
|
|
1349
1473
|
## Version
|
|
1350
1474
|
|
|
1351
|
-
3.2.
|
|
1475
|
+
3.2.1
|
|
@@ -9,7 +9,7 @@ import importlib
|
|
|
9
9
|
import importlib.util
|
|
10
10
|
from typing import TYPE_CHECKING
|
|
11
11
|
|
|
12
|
-
__version__ = "3.2.
|
|
12
|
+
__version__ = "3.2.1"
|
|
13
13
|
|
|
14
14
|
# Common utilities are internal - not exported as public API
|
|
15
15
|
# Use agenticstar_platform.common for internal SDK development only
|
{agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/workflow/child.py
RENAMED
|
@@ -5,6 +5,8 @@ stdout / stderr は Agent の通常出力(本文は制御チャネルに混ざ
|
|
|
5
5
|
例外は既定でクラス名だけを stderr に出す(本文 / token を Pod ログへ写さない)。`ASTER_WORKFLOW_DEBUG_TRACEBACK=1` で全文。
|
|
6
6
|
クラス名の後ろに、原因の連鎖(クラス名・SDK の error_code / HTTP status・通信先のホスト名だけ)を 1 行で添える
|
|
7
7
|
(devdocs 3.2req reviews 06: `SecurityAPIError` だけでは、egress のサイドカーの 503 か Azure の障害かが分からなかった)。
|
|
8
|
+
同じ原因の連鎖は done の `failure_summary` で runner に渡し、終了時の報告(envelope の `completion_report.comment`)にも載る
|
|
9
|
+
(3.2.1。`ASTER_WORKFLOW_DEBUG_TRACEBACK=1` でも報告に載るのは連鎖だけで、traceback は載せない)。
|
|
8
10
|
"""
|
|
9
11
|
from __future__ import annotations
|
|
10
12
|
|
|
@@ -12,6 +14,7 @@ import asyncio
|
|
|
12
14
|
import importlib
|
|
13
15
|
import json
|
|
14
16
|
import os
|
|
17
|
+
import re
|
|
15
18
|
import sys
|
|
16
19
|
import traceback
|
|
17
20
|
|
|
@@ -19,6 +22,7 @@ from .context import WorkflowContext, _Ipc
|
|
|
19
22
|
|
|
20
23
|
|
|
21
24
|
_MAX_CAUSES = 5
|
|
25
|
+
_ERROR_CODE_RE = re.compile(r"[A-Z][A-Z0-9_]{0,63}") # SDK の error_code の語の形 (REQUEST_ERROR など)
|
|
22
26
|
|
|
23
27
|
|
|
24
28
|
def _safe_failure_summary(exc: BaseException) -> str:
|
|
@@ -49,9 +53,10 @@ def _failure_chain(exc: BaseException) -> str:
|
|
|
49
53
|
def _describe_exception(exc: BaseException) -> str:
|
|
50
54
|
"""例外 1 件を ``クラス名(error_code=..., status=..., host=...)`` にする (出せる属性が無ければクラス名だけ)。"""
|
|
51
55
|
attrs = []
|
|
52
|
-
# error_code は SDK 自身の例外 (SDK が決まった語を入れる) のときだけ。Agent
|
|
56
|
+
# error_code は SDK 自身の例外 (SDK が決まった語を入れる) のときだけ。Agent の例外の属性は文言と同じ扱いで出さない。
|
|
57
|
+
# SDK の例外クラスを Agent が自分の値で作ることもあるので、SDK の語の形 (大文字の snake_case) に合うものだけ出す
|
|
53
58
|
code = _attr(exc, "error_code") if type(exc).__module__.startswith("agenticstar_platform.") else None
|
|
54
|
-
if isinstance(code, str) and
|
|
59
|
+
if isinstance(code, str) and _ERROR_CODE_RE.fullmatch(code):
|
|
55
60
|
attrs.append(f"error_code={code}")
|
|
56
61
|
status = _attr(exc, "status_code")
|
|
57
62
|
if isinstance(status, int) and not isinstance(status, bool):
|
|
@@ -120,11 +125,12 @@ async def _main() -> int:
|
|
|
120
125
|
if asyncio.iscoroutine(result):
|
|
121
126
|
await result
|
|
122
127
|
except Exception as e: # noqa: BLE001
|
|
128
|
+
summary = _safe_failure_summary(e)
|
|
123
129
|
if os.environ.get("ASTER_WORKFLOW_DEBUG_TRACEBACK") == "1":
|
|
124
130
|
traceback.print_exc(file=sys.stderr)
|
|
125
131
|
else:
|
|
126
|
-
sys.stderr.write(f"agent entrypoint failed: {type(e).__name__} [{
|
|
127
|
-
await ipc.call("done", status="error", error_class=type(e).__name__)
|
|
132
|
+
sys.stderr.write(f"agent entrypoint failed: {type(e).__name__} [{summary}]\n")
|
|
133
|
+
await ipc.call("done", status="error", error_class=type(e).__name__, failure_summary=summary)
|
|
128
134
|
return 1
|
|
129
135
|
await ipc.call("done", status="ok")
|
|
130
136
|
return 0
|
{agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/workflow/context.py
RENAMED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
"""顧客 Agent の entrypoint に渡す `context`(marketplace-3.0 03 §2)。
|
|
2
2
|
|
|
3
3
|
read-only の相関、parameters、input/work/output_dir、operation_key、監査(tool.invoked / tool.effect / tool.denied)、
|
|
4
|
-
取消 / 期限の確認、permitted skip
|
|
4
|
+
取消 / 期限の確認、permitted skip と「完遂できなかった」(incomplete)の宣言、起動のきっかけになった確認の決定(`gate_decision`)、外から呼んだ run の
|
|
5
5
|
開始の入力(`start_input`)を提供する。
|
|
6
6
|
gate を決定するメソッドや任意 DB 接続は提供しない。
|
|
7
7
|
実体は子プロセス側にあり、監査と取消確認は親 runner へ IPC で委譲する。
|
|
@@ -26,11 +26,32 @@ from pathlib import Path
|
|
|
26
26
|
from types import MappingProxyType
|
|
27
27
|
from typing import Any, Callable, Mapping, Optional
|
|
28
28
|
|
|
29
|
-
from .envelope import PRE_ACTION_SKIP_REASONS, SKIP_REASONS
|
|
29
|
+
from .envelope import PRE_ACTION_SKIP_REASONS, SKIP_REASONS, reason_code, report_comment
|
|
30
30
|
from .errors import AuditNotPersisted, WorkflowError
|
|
31
31
|
|
|
32
32
|
logger = logging.getLogger(__name__)
|
|
33
33
|
|
|
34
|
+
INCOMPLETE = "incomplete"
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
def _incomplete_reason(reason: Any, execution_id: str) -> str:
|
|
38
|
+
"""`incomplete()` の理由コード。会話の `report_completion()`(`db/completion_report.normalize_reason`)と同じ正規化と検査:
|
|
39
|
+
前後の空白を除き、小文字にし、`-` と空白を `_` にして `^[a-z][a-z0-9_]{0,31}$` に合えばその値。省略・空は `incomplete`。
|
|
40
|
+
合わない値(文章・例外の文字列・長すぎる値)も `incomplete` にして警告する(値はログに出さない)。str の派生
|
|
41
|
+
(StrEnum など)は名前ではなく値を使う。db パッケージは asyncpg を読み込むので import せず、同じ規則をここに置く。"""
|
|
42
|
+
try:
|
|
43
|
+
text = str.__str__(reason) if isinstance(reason, str) else str(reason or "")
|
|
44
|
+
code: Optional[str] = text.strip().lower().replace("-", "_").replace(" ", "_")
|
|
45
|
+
except Exception: # noqa: BLE001 — 文字列にできない値も Agent の処理を止めない
|
|
46
|
+
code = None
|
|
47
|
+
if code == "":
|
|
48
|
+
return INCOMPLETE
|
|
49
|
+
if code is not None and reason_code(code, "") == code:
|
|
50
|
+
return code
|
|
51
|
+
logger.warning("[%s] incomplete reason is not a short snake_case code (^[a-z][a-z0-9_]{0,31}$); using %r",
|
|
52
|
+
execution_id, INCOMPLETE)
|
|
53
|
+
return INCOMPLETE
|
|
54
|
+
|
|
34
55
|
MUTATING_EFFECT_KINDS = ("write", "create", "update", "delete", "send", "mutate")
|
|
35
56
|
READ_EFFECT_KINDS = ("read", "list", "query", "fetch")
|
|
36
57
|
MAX_LINE = 256 * 1024
|
|
@@ -375,5 +396,28 @@ class WorkflowContext:
|
|
|
375
396
|
if not reply.get("ok"):
|
|
376
397
|
raise WorkflowError(f"skip not recorded: {reply.get('error') or 'unknown'}")
|
|
377
398
|
|
|
399
|
+
async def incomplete(self, reason: str, comment: Optional[str] = None) -> None:
|
|
400
|
+
"""「完遂できなかった」で工程を終える宣言(3.2.1)。指示が無い・設定の誤りのように、やり直しても同じ結果になる失敗に使う。
|
|
401
|
+
outcome は `incomplete`、理由コードは `reason`。front は自動で再実行せず、人の確認に回す。
|
|
402
|
+
|
|
403
|
+
宣言の後は関数から戻る(宣言の後に例外で抜けても `incomplete` のまま)。監査の保存の失敗・取消・期限・他所の終端・runner の停止・
|
|
404
|
+
拒否(tool.denied)はこの宣言より先に決まる。宣言は 1 回: 2 回目は記録されず、最初の宣言が残る(runner が警告を出す)。
|
|
405
|
+
reason: 理由コード(`report_completion()` と同じ: 小文字の snake_case、32 字まで。`-` と空白は `_` に、大文字は小文字に
|
|
406
|
+
する。合わない値は `incomplete` にして警告)
|
|
407
|
+
comment: 人が読む短い説明(任意)。終了時の報告(envelope の `completion_report.comment`)に載る。2,048 字(UTF-16 の
|
|
408
|
+
単位)を超えた分は切る。文字列でない値(例外など)は載せずに警告する。秘密の値や個人の情報を
|
|
409
|
+
書かない"""
|
|
410
|
+
code = _incomplete_reason(reason, self.execution_id)
|
|
411
|
+
text = None
|
|
412
|
+
if comment is not None:
|
|
413
|
+
# 文字列だけを載せる(例外などを渡すと、その本文が報告に載る)。runner も文字列でない comment を捨てる
|
|
414
|
+
text = report_comment(comment) if isinstance(comment, str) else None
|
|
415
|
+
if text is None and not (isinstance(comment, str) and comment == ""):
|
|
416
|
+
logger.warning("[%s] incomplete comment left out: it must be a str of valid UTF-8 text (got %s)",
|
|
417
|
+
self.execution_id, type(comment).__name__)
|
|
418
|
+
reply = await self._ipc.call("incomplete", reason=code, comment=text)
|
|
419
|
+
if not reply.get("ok"):
|
|
420
|
+
raise WorkflowError(f"incomplete not recorded: {reply.get('error') or 'unknown'}")
|
|
421
|
+
|
|
378
422
|
async def log(self, message: str) -> None:
|
|
379
423
|
await self._ipc.call("log", message=str(message)[:2000])
|
{agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/workflow/envelope.py
RENAMED
|
@@ -2,7 +2,10 @@
|
|
|
2
2
|
|
|
3
3
|
- outcome は「どう終わったか」の 7 値: completed / incomplete / failed / timeout / stopped / denied / skipped。
|
|
4
4
|
**成否 = Agent が完遂したか**。Agent の関数が正常に戻れば `completed`。write の失敗・未観測の効果・tool 記録が無いことは
|
|
5
|
-
outcome を下げない(Agent が完遂できなかったなら、Agent
|
|
5
|
+
outcome を下げない(Agent が完遂できなかったなら、Agent が `incomplete()` で宣言するか(3.2.1。やり直しても同じ結果になる失敗。
|
|
6
|
+
front は自動で再実行せず人の確認に回す)、例外で終わる)。何を書いたかは `counts` / `tools` / `had_mutating_success` の側に残す
|
|
7
|
+
- `incomplete` と、Agent の例外による `failed/agent_error` には、終了時の報告 `completion_report`(SaaS の worker と同じ形:
|
|
8
|
+
`completed: false`・`reason_code`・`comment`)を載せる(3.2.1)。ほかの終わり方では載せない(欄ごと無い)
|
|
6
9
|
- tally は runner が保存済み(ack 済み)監査から数える
|
|
7
10
|
- mutating な tool.invoked は **呼出し(invoked event_id)単位** で effect の status を対応付け、成功 / 失敗 / 不明を区別する
|
|
8
11
|
(`action_ref` は外部の冪等キーで、集計キーではない = 同じ action_ref を共有する 2 回の呼出しが結果を共有しない)
|
|
@@ -30,6 +33,8 @@ SKIP_REASONS = ("no_target", "not_applicable", "nothing_to_do")
|
|
|
30
33
|
# 外部行為の **前** に policy を照合できなかった: front は budget 内で再照合(retryOrHold)する。次工程へは進めない
|
|
31
34
|
PRE_ACTION_SKIP_REASONS = ("policy_unavailable",)
|
|
32
35
|
_REASON_RE = re.compile(r"^[a-z][a-z0-9_]{0,31}$")
|
|
36
|
+
# 終了時の報告の comment の上限。front は JS の length(UTF-16 の単位)で 2,048 まで残す
|
|
37
|
+
COMPLETION_REPORT_COMMENT_MAX = 2048
|
|
33
38
|
|
|
34
39
|
|
|
35
40
|
def reason_code(value: Any, default: str) -> str:
|
|
@@ -37,6 +42,40 @@ def reason_code(value: Any, default: str) -> str:
|
|
|
37
42
|
return v if _REASON_RE.match(v) else default
|
|
38
43
|
|
|
39
44
|
|
|
45
|
+
def cut_utf16(text: str, limit: int) -> str:
|
|
46
|
+
"""JS の length(UTF-16 の単位。BMP の外の文字は 2)で `limit` までに切る(runner の `_error_class` と同じ数え方)。"""
|
|
47
|
+
units = 0
|
|
48
|
+
for i, ch in enumerate(text):
|
|
49
|
+
units += 2 if ord(ch) > 0xFFFF else 1
|
|
50
|
+
if units > limit:
|
|
51
|
+
return text[:i]
|
|
52
|
+
return text
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
def report_comment(value: Any) -> Optional[str]:
|
|
56
|
+
"""終了時の報告の comment: 文字列だけを 2,048 単位までに切る。空・UTF-8 にできない値(孤立したサロゲート)は None
|
|
57
|
+
(front へ送れない値で completion ごと落とさない)。"""
|
|
58
|
+
if not isinstance(value, str):
|
|
59
|
+
return None
|
|
60
|
+
text = cut_utf16(value, COMPLETION_REPORT_COMMENT_MAX)
|
|
61
|
+
if not text:
|
|
62
|
+
return None
|
|
63
|
+
try:
|
|
64
|
+
text.encode("utf-8")
|
|
65
|
+
except UnicodeEncodeError:
|
|
66
|
+
return None
|
|
67
|
+
return text
|
|
68
|
+
|
|
69
|
+
|
|
70
|
+
def build_completion_report(reason: str, comment: Optional[str]) -> dict[str, Any]:
|
|
71
|
+
"""終了時の報告(SaaS の worker の `completion_report` と同じ形)。完遂できなかったときだけ作るので `completed` は false。
|
|
72
|
+
comment が無ければ欄なし。"""
|
|
73
|
+
report: dict[str, Any] = {"completed": False, "reason_code": reason}
|
|
74
|
+
if comment:
|
|
75
|
+
report["comment"] = comment
|
|
76
|
+
return report
|
|
77
|
+
|
|
78
|
+
|
|
40
79
|
@dataclass
|
|
41
80
|
class EffectTally:
|
|
42
81
|
"""保存済み(ack 済み)監査から集計する。ack されていない event は数えない。"""
|
|
@@ -47,6 +86,8 @@ class EffectTally:
|
|
|
47
86
|
denials: list[str] = field(default_factory=list) # reason codes
|
|
48
87
|
persist_failures: int = 0 # 必須監査(manifest / invoked / effect / denied)の保存失敗
|
|
49
88
|
skip_reason: Optional[str] = None # Agent が宣言した skip 理由(SKIP_REASONS / PRE_ACTION)
|
|
89
|
+
incomplete_reason: Optional[str] = None # Agent が宣言した「完遂できなかった」の理由(incomplete())
|
|
90
|
+
incomplete_comment: Optional[str] = None # その説明(終了時の報告の comment)
|
|
50
91
|
|
|
51
92
|
def record(self, event_type: str, event_id: str, metadata: dict[str, Any], reason: Optional[str] = None) -> None:
|
|
52
93
|
if event_type == "tool.invoked":
|
|
@@ -68,7 +109,8 @@ class EffectTally:
|
|
|
68
109
|
def to_dict(self) -> dict[str, Any]:
|
|
69
110
|
return {"invoked": self.invoked, "effects": self.effects, "orphan_effects": self.orphan_effects,
|
|
70
111
|
"effect_conflicts": self.effect_conflicts, "denials": list(self.denials),
|
|
71
|
-
"persist_failures": self.persist_failures, "skip_reason": self.skip_reason
|
|
112
|
+
"persist_failures": self.persist_failures, "skip_reason": self.skip_reason,
|
|
113
|
+
"incomplete_reason": self.incomplete_reason, "incomplete_comment": self.incomplete_comment}
|
|
72
114
|
|
|
73
115
|
@classmethod
|
|
74
116
|
def from_dict(cls, data: Any) -> "EffectTally":
|
|
@@ -85,6 +127,9 @@ class EffectTally:
|
|
|
85
127
|
t.persist_failures = int(data.get("persist_failures") or 0)
|
|
86
128
|
sr = data.get("skip_reason")
|
|
87
129
|
t.skip_reason = sr if sr in SKIP_REASONS + PRE_ACTION_SKIP_REASONS else None
|
|
130
|
+
ir = data.get("incomplete_reason")
|
|
131
|
+
t.incomplete_reason = ir if isinstance(ir, str) and _REASON_RE.match(ir) else None
|
|
132
|
+
t.incomplete_comment = report_comment(data.get("incomplete_comment")) if t.incomplete_reason else None
|
|
88
133
|
return t
|
|
89
134
|
|
|
90
135
|
@property
|
|
@@ -155,7 +200,8 @@ def decide_outcome(*, tally: EffectTally, agent_error: Optional[str], stop_reaso
|
|
|
155
200
|
outputs_collected: int, required_missing: list[str], effect_mode: str,
|
|
156
201
|
collection_failed: bool = False, effects_uncertain: bool = False) -> tuple[str, str, Optional[bool]]:
|
|
157
202
|
"""(outcome, outcome_reason_code, had_mutating_success)。優先順位(00 §7 / 03 §4):
|
|
158
|
-
監査保存失敗 → 取消 → 期限 → 他所終端 → runner 停止 → 拒否 →
|
|
203
|
+
監査保存失敗 → 取消 → 期限 → 他所終端 → runner 停止 → 拒否 → 宣言された incomplete(3.2.1。宣言の後に例外で抜けても
|
|
204
|
+
incomplete)→ 例外
|
|
159
205
|
→ 回収失敗(宣言 output が不正 / 読めない。skip でも隠さない)→ skip(成功が無い場合。skip = 成果物を作らないので
|
|
160
206
|
必須 output の **欠落** より先)→ 必須 output 欠落 → 完遂。
|
|
161
207
|
|
|
@@ -179,6 +225,9 @@ def decide_outcome(*, tally: EffectTally, agent_error: Optional[str], stop_reaso
|
|
|
179
225
|
return "failed", "runner_stopped", had
|
|
180
226
|
if tally.denied:
|
|
181
227
|
return "denied", tally.denials[0], had # 成功 / 必須 output より優先(front は hold / on_denied)
|
|
228
|
+
if tally.incomplete_reason:
|
|
229
|
+
# Agent が宣言した「完遂できなかった」。例外・回収の失敗・skip・必須 output の欠落より先(front は自動で再実行せず人へ)
|
|
230
|
+
return "incomplete", tally.incomplete_reason, had
|
|
182
231
|
if agent_error:
|
|
183
232
|
return "failed", "agent_error", had
|
|
184
233
|
if collection_failed:
|
|
@@ -195,11 +244,13 @@ def decide_outcome(*, tally: EffectTally, agent_error: Optional[str], stop_reaso
|
|
|
195
244
|
|
|
196
245
|
|
|
197
246
|
def build_envelope(*, outcome: str, reason: str, had_mutating_success: Optional[bool], tally: EffectTally,
|
|
198
|
-
error_class: Optional[str] = None, runner: Optional[dict[str, Any]] = None
|
|
199
|
-
|
|
247
|
+
error_class: Optional[str] = None, runner: Optional[dict[str, Any]] = None,
|
|
248
|
+
completion_report: Optional[dict[str, Any]] = None) -> dict[str, Any]:
|
|
249
|
+
"""`runner`: runner 自身の終わり方(停止理由 / 再起動 / cleanup 未完)。Agent の成否ではなく実行環境の記録。
|
|
250
|
+
`completion_report`: 終了時の報告(`build_completion_report`)。None なら欄ごと載せない(3.2 までと同じ envelope)。"""
|
|
200
251
|
if outcome not in OUTCOMES:
|
|
201
252
|
raise ValueError(f"unknown outcome {outcome}")
|
|
202
|
-
|
|
253
|
+
envelope = {
|
|
203
254
|
"version": ENVELOPE_VERSION,
|
|
204
255
|
"envelope_version": ENVELOPE_VERSION,
|
|
205
256
|
"outcome": outcome,
|
|
@@ -212,3 +263,6 @@ def build_envelope(*, outcome: str, reason: str, had_mutating_success: Optional[
|
|
|
212
263
|
"runner": runner,
|
|
213
264
|
"written_by": "agenticstar-platform-sdk",
|
|
214
265
|
}
|
|
266
|
+
if completion_report is not None:
|
|
267
|
+
envelope["completion_report"] = completion_report
|
|
268
|
+
return envelope
|