agentenv-framework 0.9.1254__py3-none-any.whl

agent_env/task_step/store.py

@@ -0,0 +1,129 @@
+"""TaskStep store for MongoDB persistence."""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING, Optional, Self, TypeVar
+
+from agent_env.plugins import _registration
+from agent_env.store.base import NotFoundError
+from agent_env.config import get_config
+from agent_env.store.document_store import VersionedEntityStore, VersionedEntityStoreCache
+from agent_env.store.query import QueryBuilder, to_document_query
+
+if TYPE_CHECKING:
+    from agent_env.task_step.task_step import TaskStep
+
+_S = TypeVar("_S", bound="TaskStep")
+
+logger = logging.getLogger(__name__)
+
+TASK_STEPS_COLLECTION = "task_steps"
+
+
+class TaskStepQuery(QueryBuilder["TaskStep"]):
+    def __init__(self, store: Optional["TaskStepStore"] = None) -> None:
+        super().__init__()
+        self._store = store
+
+    def _clone(self) -> Self:
+        clone = TaskStepQuery(self._store)
+        clone._filters = self._filters.copy()
+        clone._sort_field = self._sort_field
+        clone._sort_desc = self._sort_desc
+        clone._limit_value = self._limit_value
+        clone._offset_value = self._offset_value
+        return clone
+
+    def type(self, task_step_type: str) -> Self:
+        return self._add_filter("type", task_step_type)
+
+    def execute(self) -> list[TaskStep]:
+        if self._store is None:
+            self._store = get_task_step_store()
+        return self._store.execute_query(self)
+
+    def _execute_count(self) -> int:
+        if self._store is None:
+            self._store = get_task_step_store()
+        return self._store.execute_count(self)
+
+
+class TaskStepStore:
+    def __init__(self) -> None:
+        self._versioned_cache: VersionedEntityStoreCache[TaskStep] = VersionedEntityStoreCache(
+            TASK_STEPS_COLLECTION, self._serialize, self._deserialize, secondary_indexes=[["type"]],
+        )
+
+    @property
+    def _doc_store(self):
+        return get_config().get_document_store()
+
+    @property
+    def _versioned(self) -> VersionedEntityStore[TaskStep]:
+        return self._versioned_cache.for_store(self._doc_store)
+
+    def _serialize(self, task_step: TaskStep) -> dict:
+        doc = task_step.to_dict()
+        doc["created_at_utc"] = datetime.now(timezone.utc)
+        return doc
+
+    def get(self, id: str, version: Optional[int] = None) -> TaskStep:
+        task_step = self._versioned.get(id, version)
+        if task_step is None:
+            version_str = f" version={version}" if version is not None else ""
+            raise NotFoundError(f"TaskStep {id}{version_str} not found")
+        return task_step
+
+    def next_version(self, id: str) -> int:
+        return self._versioned.next_version(id)
+
+    def put_document(self, task_step: _S) -> _S:
+        task_step.version = self._versioned.put(task_step)
+        return task_step
+
+    def _deserialize(self, doc: dict) -> TaskStep:
+        from agent_env.task_step.registry import get_task_step_registry
+
+        doc.pop("_id", None)
+        doc.pop("created_at_utc", None)
+        task_step_type = doc["type"]
+        registry = get_task_step_registry()
+        cls = registry.get(task_step_type)
+        if cls is None:
+            raise ValueError(
+                f"Unknown task step type: {task_step_type}"
+                f"{_registration.failure_note(_registration.TASK_STEPS, task_step_type)}"
+            )
+        from agent_env.task_step.task_step import attach_retry_config
+
+        return attach_retry_config(cls.from_dict(doc), doc)
+
+    def execute_query(self, query: TaskStepQuery) -> list[TaskStep]:
+        filt, sort = to_document_query(query)
+        return self._versioned.query(filt, sort, query._limit_value, query._offset_value)
+
+    def execute_count(self, query: TaskStepQuery) -> int:
+        filt, _ = to_document_query(query)
+        return self._versioned.count(filt)
+
+
+_task_step_store: Optional[TaskStepStore] = None
+
+
+def get_task_step_store() -> TaskStepStore:
+    global _task_step_store
+    if _task_step_store is None:
+        _task_step_store = TaskStepStore()
+    return _task_step_store
+
+
+def set_task_step_store(store: TaskStepStore) -> None:
+    global _task_step_store
+    _task_step_store = store
+
+
+def reset_task_step_store() -> None:
+    global _task_step_store
+    _task_step_store = None

agent_env/task_step/task_step.py

@@ -0,0 +1,173 @@
+"""Base TaskStep model for AgentEnv."""
+
+from __future__ import annotations
+
+import dataclasses
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, ClassVar, Optional, Self
+
+from agent_env.task_step.context import TaskStepContext
+from agent_env.entity_refs import EntityRef
+
+if TYPE_CHECKING:
+    from agent_env.task_step.store import TaskStepQuery
+
+
+@dataclass
+class TaskStepDependency:
+    task_step_id: str
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "TaskStepDependency":
+        return cls(task_step_id=data["task_step_id"])
+
+
+def attach_retry_config(step: "TaskStep", data: dict[str, Any]) -> "TaskStep":
+    """Hydrate ``retry_config`` after ``step_cls.from_dict`` at the generic
+    parse sites, so the field survives round-trips on step types whose
+    ``__init__`` doesn't accept it. No-op if already set or absent."""
+    raw = data.get("retry_config")
+    if raw is not None and getattr(step, "retry_config", None) is None:
+        step.retry_config = RetryConfig.from_dict(raw)
+    return step
+
+
+@dataclass
+class RetryConfig:
+    """Where a step resumes from on a retry, and how many retries to allow.
+
+    ``retry_from_step_id`` is required. Set to the step itself it re-runs only
+    this step. Point it at an earlier dependency ancestor to roll the world back
+    to there and re-dispatch the span (``retry_from_step_id`` .. failed step) as
+    ordinary steps on a freshly redeployed world (see ``Task._drive_dag``). The
+    task author owns the resume point; the platform does not decide which steps
+    are safe to re-run.
+
+    ``max_retries`` (default 1) bounds how many times a step may trigger this
+    rollback-and-re-dispatch before the failure is treated as terminal."""
+
+    retry_from_step_id: str
+    max_retries: int = 1
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "RetryConfig":
+        # go_to_step_id = wire alias; retry_from_step_id canonical (only spelling emitted).
+        step_id = data.get("retry_from_step_id", data.get("go_to_step_id"))
+        if step_id is None:
+            raise ValueError("retry_config requires 'retry_from_step_id' (or 'go_to_step_id')")
+        max_retries = data.get("max_retries", 1)
+        # bool is an int subclass; reject it and non-ints so a bad value fails at
+        # parse time, not mid-run inside the scheduler's retry-budget comparison.
+        if isinstance(max_retries, bool) or not isinstance(max_retries, int):
+            raise ValueError(f"retry_config.max_retries must be an int, got {max_retries!r}")
+        if max_retries < 0:
+            raise ValueError(f"retry_config.max_retries must be >= 0, got {max_retries}")
+        return cls(retry_from_step_id=step_id, max_retries=max_retries)
+
+
+class TaskStep(ABC):
+    """Base class for all task steps. Immutable - each modification creates a new version."""
+
+    type: ClassVar[str] = "task_step"
+    DEFAULT_TTL_SECONDS: ClassVar[int] = 7200
+    DEFAULT_AGENT_NAME: ClassVar[str] = "default-agent"
+    # Fields holding env, A2A agent or artifact ids; None means undeclared.
+    entity_refs: ClassVar[tuple[EntityRef, ...] | None] = None
+
+    def __init_subclass__(cls, **kwargs) -> None:
+        super().__init_subclass__(**kwargs)
+        # Never inherited: a subclass may add id fields its parent's declaration misses.
+        if "entity_refs" not in vars(cls):
+            cls.entity_refs = None
+
+    def __init__(
+        self,
+        id: str,
+        version: Optional[int],
+        depends_on: Optional[list] = None,
+        fail_task_on_error: bool = True,
+        retry_config: Optional["RetryConfig | dict"] = None,
+    ):
+        self.id = id
+        self.version = version
+        if depends_on is not None:
+            depends_on = [
+                d if isinstance(d, TaskStepDependency) else TaskStepDependency.from_dict(d)
+                for d in depends_on
+            ]
+        self.depends_on = depends_on
+        self.fail_task_on_error = fail_task_on_error
+        if retry_config is not None and not isinstance(retry_config, RetryConfig):
+            retry_config = RetryConfig.from_dict(retry_config)
+        self.retry_config = retry_config
+
+    @abstractmethod
+    async def execute(self, context: TaskStepContext) -> TaskStepContext | None:
+        """Execute this task step."""
+        pass
+
+    def preflight(self) -> list[str]:
+        """Config problems detectable before a run, one message each; empty when fine.
+
+        Overrides must not need a sandbox or a deployed env.
+        """
+        return []
+
+    def step_param_overrides(self, context: TaskStepContext) -> dict[str, Any]:
+        """Per-run overrides for this step's params, from a run's ``step_overrides``.
+
+        Generic seam: a step opts in by reading the params it supports; an
+        override wins over the stored value. Empty dict when none set.
+        """
+        return (context.metadata.get("user_overrides") or {}).get("step_params", {}).get(self.id) or {}
+
+    def to_dict(self) -> dict[str, Any]:
+        base: dict[str, Any] = {"id": self.id, "type": self.type, "version": self.version, "fail_task_on_error": self.fail_task_on_error}
+        if self.depends_on is not None:
+            base["depends_on"] = [dataclasses.asdict(d) for d in self.depends_on]
+        if self.retry_config is not None:
+            base["retry_config"] = dataclasses.asdict(self.retry_config)
+        return base
+
+    @classmethod
+    def _base_from_dict(cls, data: dict) -> dict:
+        raw = data.get("depends_on")
+        depends_on = (
+            [TaskStepDependency.from_dict(d) for d in raw] if raw is not None else None
+        )
+        return {
+            "id": data["id"], "version": data.get("version"),
+            "depends_on": depends_on,
+            "fail_task_on_error": data.get("fail_task_on_error", True),
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "TaskStep":
+        raise NotImplementedError(f"{cls.__name__} must implement from_dict")
+
+    @classmethod
+    def get(cls, id: str, version: Optional[int] = None) -> "TaskStep":
+        from .store import get_task_step_store
+
+        return get_task_step_store().get(id, version)
+
+    @classmethod
+    def put(cls, **kwargs: Any) -> Self:
+        from .store import get_task_step_store
+
+        kwargs.setdefault("version", None)
+        # Most step __init__s don't accept retry_config (it lives on the base but
+        # subclasses don't forward it); construct without it, then hydrate so a
+        # retry_config on any step type round-trips through the step store.
+        retry_config_raw = kwargs.pop("retry_config", None)
+        instance = cls(**kwargs)
+        if retry_config_raw is not None:
+            attach_retry_config(instance, {"retry_config": retry_config_raw})
+        return get_task_step_store().put_document(instance)
+
+    @classmethod
+    def query(cls) -> "TaskStepQuery":
+        from .store import TaskStepQuery, get_task_step_store
+
+        return TaskStepQuery(get_task_step_store())

agent_env/task_step/task_steps/__init__.py

@@ -0,0 +1,27 @@
+from .mcp_cli_builder.build_mcp_cli import BuildMcpCliTaskStep
+from .deploy_agent import DeployAgentTaskStep
+from .deploy_env import DeployEnvTaskStep
+from .verifiers.env_outcome_verifier import EnvOutcomeVerifierTaskStep, ScoreAggregator
+from .load_artifact import LoadArtifactTaskStep
+from .modify_env_tool_access import ModifyEnvToolAccessStep
+from .prompt_agent import PromptAgentTaskStep
+from .verifiers.rubrics_verifier import RubricsVerifierTaskStep
+from .mcp_env_validator.verify_mcp_env_assessment import VerifyMCPEnvAssessmentStep
+from .mcp_env_validator.verify_mcp_tool_schema import VerifyMCPToolSchemaTaskStep
+from .mcp_env_validator.verify_spec_conformance import VerifySpecConformanceTaskStep
+from .mcp_env_validator.validation_gate_aggregator import ValidationGateAggregatorStep
+from .multienv_validator.verify_universe_roundtrip import VerifyUniverseLoadExportRoundtripStep
+from .multienv_validator.combine_universe_verdicts import CombineUniverseVerdictsStep
+from .env_card_validator.verify_env_card import VerifyEnvironmentCardStep
+from .env_card_validator.verify_env_core_protocol import VerifyCoreEnvironmentProtocolStep
+from .a2a_agent_validator.verify_a2a_agent_card import VerifyA2AAgentCardStep
+from .a2a_agent_validator.verify_a2a_agent_mcp import VerifyA2AAgentMCPStep
+from .a2a_agent_validator.verify_a2a_core_protocol import VerifyCoreA2AProtocolStep
+from .a2a_agent_validator.verify_a2a_skill_config import VerifyA2ASkillConfigStep
+from .a2a_agent_validator.verify_a2a_trajectory import VerifyA2ATrajectoryStep
+from .add_skills import AddSkillsTaskStep
+from .apply_server_config import ApplyServerConfigStep, ConfigDirective
+from .verifiers.agent_prompt_response_verifier import AgentPromptResponseVerifierTaskStep
+
+__all__ = ["AddSkillsTaskStep", "ApplyServerConfigStep", "ConfigDirective", "AgentPromptResponseVerifierTaskStep", "BuildMcpCliTaskStep",
+    "DeployAgentTaskStep", "DeployEnvTaskStep", "EnvOutcomeVerifierTaskStep", "LoadArtifactTaskStep", "ModifyEnvToolAccessStep", "PromptAgentTaskStep", "RubricsVerifierTaskStep", "VerifyMCPEnvAssessmentStep", "VerifyMCPToolSchemaTaskStep", "VerifySpecConformanceTaskStep", "ValidationGateAggregatorStep", "VerifyUniverseLoadExportRoundtripStep", "CombineUniverseVerdictsStep", "VerifyEnvironmentCardStep", "VerifyCoreEnvironmentProtocolStep", "VerifyA2AAgentCardStep", "VerifyA2AAgentMCPStep", "VerifyCoreA2AProtocolStep", "VerifyA2ASkillConfigStep", "VerifyA2ATrajectoryStep", "ScoreAggregator"]

agent_env/task_step/task_steps/a2a_agent_validator/__init__.py

@@ -0,0 +1,31 @@
+from .verify_a2a_agent_card import VerifyA2AAgentCardStep
+from .verify_a2a_agent_config_identity import VerifyA2AAgentConfigIdentityStep
+from .verify_a2a_agent_mcp import VerifyA2AAgentMCPStep
+from .verify_a2a_core_protocol import VerifyCoreA2AProtocolStep
+from .verify_a2a_install import VerifyA2AInstallStep
+from .verify_a2a_litellm_attribution import VerifyA2ALitellmAttributionStep
+from .verify_a2a_litellm_attribution_runtime import VerifyA2ALitellmAttributionRuntimeStep
+from .verify_a2a_modalities import VerifyA2AModalitiesStep
+from .verify_a2a_peer_agents import VerifyA2APeerAgentsStep
+from .verify_a2a_role import VerifyA2ARoleStep
+from .verify_a2a_skill_config import VerifyA2ASkillConfigStep
+from .verify_a2a_snapshot import VerifyA2ASnapshotStep
+from .verify_a2a_system_prompt import VerifyA2ASystemPromptStep
+from .verify_a2a_trajectory import VerifyA2ATrajectoryStep
+
+__all__ = [
+    "VerifyA2AAgentCardStep",
+    "VerifyA2AAgentConfigIdentityStep",
+    "VerifyA2AAgentMCPStep",
+    "VerifyCoreA2AProtocolStep",
+    "VerifyA2AInstallStep",
+    "VerifyA2ALitellmAttributionStep",
+    "VerifyA2ALitellmAttributionRuntimeStep",
+    "VerifyA2AModalitiesStep",
+    "VerifyA2APeerAgentsStep",
+    "VerifyA2ARoleStep",
+    "VerifyA2ASkillConfigStep",
+    "VerifyA2ASnapshotStep",
+    "VerifyA2ASystemPromptStep",
+    "VerifyA2ATrajectoryStep",
+]

agent_env/task_step/task_steps/a2a_agent_validator/fixtures/README.md

@@ -0,0 +1,158 @@
+# Modality probe fixtures
+
+Binary fixtures used by the A2A agent validator's modality probes. Each
+file is loaded at import time via `_b64(name)` in `verify_a2a_modalities.py`
+and exposed as a `*_B64` constant. The same constants get assembled into
+`*_PROBE_PARTS` lists for the inline-bytes path, and the raw bytes are also
+read directly for the URI-based S3 upload path.
+
+| File | Probe modality | What it contains | Why |
+|---|---|---|---|
+| `red.png`      | `image/png`           | 8×8 solid red square                | smallest valid red png (75 B)   |
+| `red.jpg`      | `image/jpeg`          | 8×8 solid red square                | tests separate JPEG decode path |
+| `red.gif`      | `image/gif`           | 8×8 solid red square                | tests separate GIF decode path  |
+| `clip.wav`     | `audio/wav`           | spoken `"Say the word: banana"`     | tests PCM decode + transcription|
+| `clip.mp3`     | `audio/mpeg`          | spoken `"Say the word: telephone"`  | tests MP3 decode + transcription|
+| `clip.m4a`     | `audio/mp4`           | spoken `"Say the word: bicycle"`    | tests AAC decode + transcription|
+| `clip.ogg`     | `audio/ogg`           | spoken `"Say the word: rainbow"`    | tests Opus decode + transcription|
+| `document.pdf` | `application/pdf`     | one-page instructional doc, target `ELEPHANT` | tests PDF text extraction |
+| `clip.mp4`     | `video/mp4`           | 3 s clip showing `GIRAFFE` on white | tests video-frame OCR; URI-delivered |
+
+## Design choices that surface as gotchas
+
+### Distinct target words per audio format
+Each audio file says a *different* word — the validator uses
+`AUDIO_WAV_EXPECTED = "banana"`, `AUDIO_MP3_EXPECTED = "telephone"`, etc.
+If every probe expected the same word, a model could pass by outputting
+that word from any cue (filename, bias, the prompt). Distinct expected
+values per format means the model has to actually decode each clip.
+
+### Neutral filenames
+All fixtures are named `clip.<ext>` / `red.<ext>` / `document.pdf` rather
+than `banana.<ext>` / `red-square.png` etc. A leaky filename lets the model
+answer from the path the wrapper materializes (`@/app/inputs/<task>/X`)
+without ever decoding the bytes. We caught this when an early probe with
+`banana.mp3` was "passing" via `ls banana.mp3` + filename inference.
+
+### Audio encoding details
+- **16 kHz mono is the format Gemini accepts reliably.** An earlier 8 kHz
+  WAV failed even though `audio/wav` is in the gemini-cli MIME table.
+- **`Alex` voice transcribes more reliably than the default `say` voice.**
+  With the default voice the model occasionally heard "banana" as "apple".
+- **3× volume boost + 200 ms silence padding raise transcription
+  accuracy from ~70% to ~100%.** Without them the model sometimes guessed
+  unrelated words ("visual", "red") when it couldn't lock onto the
+  utterance.
+
+### PDF embeds the target word inside an instructional paragraph
+`document.pdf` doesn't just show `ELEPHANT` alone — it shows a short
+paragraph naming `ELEPHANT` as the target word. Bare word alone tripped
+letter-truncation edge cases (the model occasionally reading "ELEPHANT"
+as "ANT" or "PHANT", probably from letter-spacing artifacts in the PDF
+text extractor).
+
+### Video shows a static frame, not motion
+`clip.mp4` is a static frame on a white background (480×360 @ 15 fps, h.264
+CRF 28, no audio track). It tests video-frame OCR, not temporal
+understanding. The static design plus on-screen instructional context plus
+the larger 480×360 frame size were each needed: smaller / barer clips
+truncated to "FFE" probabilistically.
+
+### Why video is URI-only
+The video fixture is delivered via `FileWithUri` (`s3://`), not inline
+`FileWithBytes` like the others. At 8.9 KB it would fit inline, but the
+validator deliberately exercises the wrapper's URI-materialization code
+path with this probe — it's the only fixture that does so for video, and
+one of three (alongside the two URI-delivered PNG probes) that exercise
+URI delivery at all.
+
+## Regenerating fixtures
+
+These are *not* runtime dependencies. They're only needed if you want to
+re-create or modify a fixture. Install with `pip install Pillow fpdf2`.
+You'll also need `ffmpeg` and the `flac` CLI on PATH (`brew install
+ffmpeg flac` on macOS).
+
+### Audio (`clip.wav`, `clip.mp3`, `clip.m4a`, `clip.ogg`)
+
+```bash
+FF_FILTER="silenceremove=start_periods=1:start_duration=0:start_threshold=-50dB:detection=peak,areverse,silenceremove=start_periods=1:start_duration=0:start_threshold=-50dB:detection=peak,areverse,volume=3.0,adelay=200|200,apad=pad_dur=0.2"
+
+# Per-format: substitute the target word, re-encode in native format.
+say -v Alex -r 150 "Say the word: Banana" -o /tmp/x.aiff
+ffmpeg -y -i /tmp/x.aiff -ac 1 -ar 16000 -map_metadata -1 -fflags +bitexact \
+  -af "$FF_FILTER" -acodec pcm_s16le fixtures/clip.wav
+
+# MP3 / M4A / OGG: encode from the freshly-trimmed WAV
+ffmpeg -y -i fixtures/clip.wav -ac 1 -ar 16000 -b:a 64k -map_metadata -1 \
+  -fflags +bitexact -write_xing 1 fixtures/clip.mp3
+ffmpeg -y -i fixtures/clip.wav -c:a aac -b:a 64k -ac 1 -ar 16000 \
+  -map_metadata -1 -fflags +bitexact fixtures/clip.m4a
+ffmpeg -y -i fixtures/clip.wav -c:a libopus -b:a 32k -ac 1 -ar 16000 \
+  -map_metadata -1 -fflags +bitexact fixtures/clip.ogg
+```
+
+If updating the target word for a format, also update the corresponding
+`AUDIO_<FMT>_EXPECTED` constant in `verify_a2a_modalities.py`.
+
+### PDF (`document.pdf`)
+
+```python
+# requires: pip install fpdf2
+from fpdf import FPDF
+pdf = FPDF(orientation='P', unit='pt', format='A4')
+pdf.set_compression(True); pdf.set_creator(''); pdf.set_producer('')
+pdf.add_page()
+pdf.set_font('Helvetica', '', 36)
+pdf.set_xy(50, 100)
+pdf.multi_cell(500, 50,
+    'A2A Modality Probe Document\n\n'
+    'This page contains exactly one target word that the reader should report.\n\n'
+    'The target word is: ELEPHANT\n\n'
+    'Reply with only the word above.',
+    align='L')
+pdf.output('fixtures/document.pdf')
+```
+
+### Video (`clip.mp4`)
+
+```python
+# requires: pip install Pillow; brew install ffmpeg
+from PIL import Image, ImageDraw, ImageFont
+img = Image.new('RGB', (480, 360), 'white')
+draw = ImageDraw.Draw(img)
+big   = ImageFont.truetype("/System/Library/Fonts/Supplemental/Arial.ttf", 80)
+small = ImageFont.truetype("/System/Library/Fonts/Supplemental/Arial.ttf", 22)
+draw.text((30, 30), "A2A Video Probe", font=small, fill='black')
+draw.text((30, 60), "Target word:",    font=small, fill='black')
+bbox = draw.textbbox((0, 0), "GIRAFFE", font=big); w = bbox[2] - bbox[0]
+draw.text(((480 - w) / 2, 150), "GIRAFFE", font=big, fill='black')
+draw.text((30, 280), "Reply with only the target word.", font=small, fill='black')
+img.save('/tmp/frame.png')
+```
+```bash
+ffmpeg -y -loop 1 -i /tmp/frame.png -t 3 -r 15 \
+  -c:v libx264 -preset slow -crf 28 -pix_fmt yuv420p -movflags +faststart \
+  fixtures/clip.mp4
+```
+
+### Images (`red.png`, `red.jpg`, `red.gif`)
+
+These are static and committed once. To regenerate, encode an 8×8 solid
+red square via Pillow or any image tool — the existing files are about
+as small as their formats allow.
+
+## Listening / previewing fixtures
+
+```bash
+# Audio (afplay handles wav/mp3/m4a; ffplay for ogg)
+afplay fixtures/clip.wav
+ffplay -nodisp -autoexit fixtures/clip.ogg
+
+# PDF / video
+qlmanage -p fixtures/document.pdf
+open fixtures/clip.mp4
+
+# Or open the whole directory in Finder and hit space for QuickLook
+open fixtures/
+```

agent_env/task_step/task_steps/a2a_agent_validator/verify_a2a_agent_card.py

@@ -0,0 +1,103 @@
+"""Verify A2A agent card structure and persist to agent metadata."""
+
+from __future__ import annotations
+
+import logging
+from typing import ClassVar, Optional
+
+from agent_env.task_step.context import TaskStepContext
+from agent_env.entity_refs import EntityRef
+from agent_env.task_step.task_step import TaskStep, TaskStepDependency
+
+logger = logging.getLogger(__name__)
+
+REQUIRED_CARD_FIELDS = ["name", "description", "url", "version", "capabilities", "defaultInputModes", "defaultOutputModes", "skills"]
+OPTIONAL_CARD_FIELDS = ["authentication", "provider", "documentationUrl"]
+
+
+class VerifyA2AAgentCardStep(TaskStep):
+    type: ClassVar[str] = "verify_a2a_agent_card"
+    entity_refs = (EntityRef.agent("a2a_agent_id", version_field="a2a_agent_version"),)
+
+    def __init__(
+        self,
+        id: str,
+        version: Optional[int],
+        a2a_agent_id: str,
+        a2a_agent_version: Optional[int] = None,
+        depends_on: Optional[list[TaskStepDependency]] = None,
+        fail_task_on_error: bool = True,
+    ):
+        super().__init__(id, version, depends_on=depends_on, fail_task_on_error=fail_task_on_error)
+        self.a2a_agent_id = a2a_agent_id
+        self.a2a_agent_version = a2a_agent_version
+
+    def to_dict(self) -> dict:
+        base = super().to_dict()
+        base["a2a_agent_id"] = self.a2a_agent_id
+        base["a2a_agent_version"] = self.a2a_agent_version
+        return base
+
+    @classmethod
+    def from_dict(cls, data: dict) -> VerifyA2AAgentCardStep:
+        return cls(**cls._base_from_dict(data), a2a_agent_id=data["a2a_agent_id"], a2a_agent_version=data.get("a2a_agent_version"))
+
+    async def execute(self, context: TaskStepContext) -> TaskStepContext:
+        from agent_env.a2a_agent import A2AAgent
+
+        deployed = next((a for a in context.deployed_agents), None)
+        if deployed is None:
+            raise RuntimeError("No deployed agent found in context")
+
+        card = deployed.a2a_card
+        agent = A2AAgent.get(self.a2a_agent_id, self.a2a_agent_version)
+
+        # Validate card is accessible
+        if not card:
+            logger.error("Agent card is inaccessible or empty")
+            validated = {"accessible": False, "error": "Inaccessible Agent Card"}
+            agent.update_metadata({**agent.metadata, "validated_agent_card": validated})
+            raise RuntimeError("Inaccessible Agent Card: agent did not return a valid agent card at /.well-known/agent.json")
+
+        logger.info(f"Agent card for '{self.a2a_agent_id}': name={card.get('name')}")
+
+        # Check required fields
+        required_fields = {}
+        missing_required = []
+        for field in REQUIRED_CARD_FIELDS:
+            value = card.get(field)
+            present = field in card and (
+                bool(value) or (field == "skills" and value == [])
+            )
+            required_fields[field] = {"present": present}
+            if not present:
+                missing_required.append(field)
+
+        if missing_required:
+            logger.warning(f"Agent card missing required fields: {missing_required}")
+        else:
+            logger.info("Agent card has all required fields")
+
+        # Check optional fields
+        optional_fields = {}
+        missing_optional = []
+        for field in OPTIONAL_CARD_FIELDS:
+            present = field in card and bool(card[field])
+            optional_fields[field] = {"present": present}
+            if not present:
+                missing_optional.append(field)
+
+        if missing_optional:
+            logger.info(f"Agent card missing optional fields: {missing_optional}")
+
+        # Log which extensions the card advertises
+        for ext_uri in [A2AAgent.EXT_MCP_CONFIG, A2AAgent.EXT_SKILL_CONFIG, A2AAgent.EXT_TRAJECTORY, A2AAgent.EXT_AGENT_CONFIG, A2AAgent.EXT_TOOLS]:
+            ext = A2AAgent.find_extension(card, ext_uri)
+            logger.info(f"  {ext_uri}: {'advertised' if ext else 'not advertised'}")
+
+        # Persist agent_card (raw) and validated_agent_card (our validation)
+        validated = {"accessible": True, "required_fields": required_fields, "optional_fields": optional_fields}
+        agent.update_metadata({**agent.metadata, "agent_card": card, "validated_agent_card": validated})
+
+        context.metadata.setdefault("verifications", {})["a2a_agent_card"] = {"agent_card": card, "validated_agent_card": validated}
+        return context