initial a2a-pack

a2a_pack/runtime.py

@@ -0,0 +1,85 @@
+"""Declarative runtime/deployment metadata.
+
+These types describe *how* the platform should run an agent: lifecycle,
+state needs, isolation level, resource budget, egress policy. They are
+read by the deployer and by the registry; agent code itself should not
+depend on which runtime is selected.
+"""
+from __future__ import annotations
+
+from enum import Enum
+
+from pydantic import BaseModel, ConfigDict, Field, NonNegativeInt, PositiveInt
+
+
+class Lifecycle(str, Enum):
+    """How long an instance of the agent process lives."""
+
+    EPHEMERAL = "ephemeral"  # spawned per-invocation, torn down after
+    SESSION = "session"  # spawned per-session, kept until the session ends
+    WARM = "warm"  # long-running service, multiplexed across callers
+
+
+class State(str, Enum):
+    """What kind of state the agent retains between invocations."""
+
+    NONE = "none"  # purely functional
+    SESSION = "session"  # in-memory state for the lifetime of a session
+    DURABLE = "durable"  # persisted across restarts (storage required)
+
+
+class Sandbox(str, Enum):
+    """Isolation level. The platform always runs agents under microsandbox.
+
+    Modeled as an enum (rather than a constant) so the wire format stays
+    stable if more isolation tiers are added later, but only one value is
+    currently valid: every agent runs in a microvm-class sandbox.
+    """
+
+    MICROSANDBOX = "microsandbox"
+
+
+class Resources(BaseModel):
+    """Resource budget hint for the deployer."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    cpu: str = "100m"  # k8s-style CPU spec, e.g. "500m", "2"
+    memory: str = "256Mi"  # k8s-style memory, e.g. "512Mi", "4Gi"
+    gpu: NonNegativeInt = 0
+    max_runtime_seconds: PositiveInt = 600
+
+
+class SkillPolicy(BaseModel):
+    """Per-skill operational policy advertised on the Agent Card."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    timeout_seconds: float | None = None
+    idempotent: bool = False
+    max_retries: NonNegativeInt = 0
+    cost_class: str | None = None  # informational, e.g. "cheap" / "expensive"
+
+
+class EgressPolicy(BaseModel):
+    """What external hosts the agent is allowed to talk to."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    allow_hosts: tuple[str, ...] = ()
+    allow_internal_services: tuple[str, ...] = ()  # e.g. cluster service DNS
+    deny_internet_by_default: bool = True
+
+
+class AgentRuntime(BaseModel):
+    """Aggregate runtime declaration; published on the Agent Card."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    lifecycle: Lifecycle = Lifecycle.EPHEMERAL
+    state: State = State.NONE
+    sandbox: Sandbox = Sandbox.MICROSANDBOX
+    resources: Resources = Field(default_factory=Resources)
+    concurrency: PositiveInt = 1
+    egress: EgressPolicy = Field(default_factory=EgressPolicy)
+    tools_used: tuple[str, ...] = ()