agentops-rpc 0.1.0__py3-none-any.whl

agentops_rpc/__init__.py

@@ -0,0 +1,393 @@
+from __future__ import annotations
+
+from .a2a import A2AMessage, A2AMessagePart, A2AMessageRequest, A2ATask, A2ATaskResponse
+from .agent_create import (
+    CreateAgentMcpServer,
+    CreateAgentRequest,
+    CreateAgentResponse,
+    CreateAgentSkill,
+    CreateWorkerTokenRequest,
+    CreateWorkerTokenResponse,
+    WorkerTokenStatusResponse,
+    WorkerTokenSummaryResponse,
+)
+from .agents import (
+    BUILTIN_USE_CASE_SLUGS,
+    BUILTIN_USE_CASES,
+    CONNECTIVITY_CHECK_USE_CASE,
+    LABEL_MAX_LENGTH,
+    LABEL_RULE_HINT,
+    PUSH_CAPABILITY,
+    REVIEW_CAPABILITY,
+    SAMPLE_RUN_PROMPT,
+    SAMPLE_RUN_USE_CASE,
+    USE_CASE_INPUT_KEY,
+    USE_CASE_SLUG_HINT,
+    USE_CASE_SLUG_MAX_LENGTH,
+    AgentGenerationInfo,
+    AgentInstanceResponse,
+    AgentManifest,
+    BuiltinUseCaseSlug,
+    CreateAgentDraftRequest,
+    HeartbeatRequest,
+    HeartbeatResponse,
+    ScheduleTriggerManifest,
+    SkillDetail,
+    SkillReference,
+    SkillSourceAgent,
+    SkillSummary,
+    SlackKeywordTriggerManifest,
+    UpdateAgentDraftRequest,
+    UpdateAgentLabelsRequest,
+    UseCase,
+    WorkerInstanceInfo,
+    label_violations,
+)
+from .artifacts import ArtifactDetail, ArtifactSummary
+from .credentials import (
+    SECRETS_METADATA_KEY,
+    BindCredentialRequest,
+    CreateCredentialRequest,
+    CredentialBinding,
+    CredentialMetadata,
+    CredentialStatus,
+    ReplaceCredentialValueRequest,
+    UpdateCredentialMetadataRequest,
+    WorkerSecretsResponse,
+)
+from .events import (
+    HANDLER_FAILED_LOG_PREFIX,
+    BatchEventsRequest,
+    IngestRunEventsRequest,
+    IngestRunEventsResponse,
+    LogEventIn,
+    LogEventResponse,
+    RunEventIn,
+    RunMessageResponse,
+    TraceEventIn,
+    TraceEventResponse,
+)
+from .grader import (
+    GRADER_CAPABILITY,
+    GradeContext,
+    GradeResult,
+)
+from .hosted_agents import (
+    HostedAgentCreateRequest,
+    HostedAgentImage,
+    HostedAgentMcpServer,
+    HostedAgentResponse,
+    HostedAgentSkill,
+    HostedAgentUpdateRequest,
+)
+from .insights import (
+    FailureCategoryCount,
+    IssueRecommendation,
+    RunIssue,
+    SaveIssueRecommendationRequest,
+    WorkspaceIssuesResponse,
+)
+from .integrations import (
+    CreateIntegrationConnectionRequest,
+    CreateIntegrationConnectionResponse,
+    IntegrationAuthMode,
+    IntegrationCatalogEntry,
+    IntegrationConnection,
+    IntegrationConnectionDetail,
+    IntegrationCredentialField,
+    IntegrationFieldType,
+    IntegrationOAuthMetadata,
+    IntegrationProviderCredentials,
+    IntegrationStatus,
+    StartIntegrationAppRequest,
+    StartIntegrationAppResponse,
+    StartIntegrationOAuthRequest,
+    StartIntegrationOAuthResponse,
+    TestIntegrationConnectionResponse,
+)
+from .issues import (
+    IssueDetail,
+    IssueGrouping,
+    IssueListResponse,
+    IssueLog,
+    IssueRca,
+    IssueSignal,
+    IssueSource,
+    IssueTimelineEvent,
+    IssueWorker,
+    UpdateIssueRequest,
+)
+from .knowledge_base import (
+    AttachAgentToKBRequest,
+    CreateKnowledgeBaseRequest,
+    KBAgentGrant,
+    KBChunkSummary,
+    KBDocumentDetail,
+    KBDocumentMetadata,
+    KBDocumentOrigin,
+    KBDocumentStatus,
+    KBDocumentSummary,
+    KBSearchFilters,
+    KBSearchHit,
+    KBSearchRequest,
+    KBSearchResponse,
+    KnowledgeBaseDetail,
+    KnowledgeBaseSummary,
+)
+from .quality import (
+    AgentQualityRollup,
+    AutoScoreSeries,
+    RunQualityRow,
+    SkillQualityRollup,
+    UngradedQueueResponse,
+)
+from .runs import (
+    ActivityBucket,
+    AddRunMessageRequest,
+    AgentActivitySummary,
+    ClaimRunResponse,
+    CompleteRunRequest,
+    CreateRunRequest,
+    FailRunRequest,
+    InvokeAgentRequest,
+    InvokeAgentResponse,
+    ModelActivity,
+    PollNextRunRequest,
+    RunDetail,
+    RunJob,
+    RunSummary,
+    RunUsage,
+    StartRunDirectRequest,
+    StartRunRequest,
+    TopCostRunSummary,
+    UpdateRunOutputRequest,
+    WorkerInvokeAgent,
+    WorkerInvokeRequest,
+    WorkerInvokeResponse,
+    WorkspaceActivityResponse,
+)
+from .schedules import CreateScheduleRequest, ScheduleResponse, UpdateScheduleRequest
+from .scores import (
+    CreateScoreRequest,
+    ScoreListResponse,
+    ScoreResponse,
+    ScoreTargetType,
+    ScoreValue,
+    UpdateScoreRequest,
+)
+from .session import SESSION_SNAPSHOT_METADATA_KEY, SessionSnapshot, SnapshotComponent, SnapshotComponentKind
+from .types import (
+    ACTIVE_RUN_STATUSES,
+    OBSERVABILITY_EVENT_TYPES,
+    OWNED_RUN_STATUSES,
+    TERMINAL_RUN_STATUSES,
+    AgentStatus,
+    DeployStatus,
+    EventType,
+    HookEventName,
+    HookEventType,
+    LogLevel,
+    MessageRole,
+    MessageType,
+    RunChannel,
+    RunEventType,
+    RunStatus,
+    RunTransport,
+    SpanKind,
+    TraceEventType,
+)
+from .worker_catalog import (
+    WorkerCatalogCredential,
+    WorkerCatalogDeployRequest,
+    WorkerCatalogEntryResponse,
+    WorkerCatalogIntegration,
+    WorkerCatalogSelfHostedDeployRequest,
+    WorkerCatalogSelfHostedDeployResponse,
+)
+
+__all__ = [
+    "ACTIVE_RUN_STATUSES",
+    "HANDLER_FAILED_LOG_PREFIX",
+    "OWNED_RUN_STATUSES",
+    "TERMINAL_RUN_STATUSES",
+    "ArtifactDetail",
+    "ArtifactSummary",
+    "A2AMessage",
+    "A2AMessagePart",
+    "A2AMessageRequest",
+    "A2ATask",
+    "A2ATaskResponse",
+    "AddRunMessageRequest",
+    "AgentActivitySummary",
+    "AgentInstanceResponse",
+    "AgentGenerationInfo",
+    "AgentManifest",
+    "AgentStatus",
+    "DeployStatus",
+    "PUSH_CAPABILITY",
+    "REVIEW_CAPABILITY",
+    "UseCase",
+    "BuiltinUseCaseSlug",
+    "BUILTIN_USE_CASES",
+    "BUILTIN_USE_CASE_SLUGS",
+    "CONNECTIVITY_CHECK_USE_CASE",
+    "SAMPLE_RUN_USE_CASE",
+    "SAMPLE_RUN_PROMPT",
+    "USE_CASE_INPUT_KEY",
+    "USE_CASE_SLUG_HINT",
+    "USE_CASE_SLUG_MAX_LENGTH",
+    "ActivityBucket",
+    "BatchEventsRequest",
+    "ClaimRunResponse",
+    "CompleteRunRequest",
+    "BindCredentialRequest",
+    "CreateAgentDraftRequest",
+    "CreateAgentMcpServer",
+    "CreateAgentRequest",
+    "CreateAgentResponse",
+    "CreateAgentSkill",
+    "CreateWorkerTokenRequest",
+    "CreateWorkerTokenResponse",
+    "WorkerTokenStatusResponse",
+    "WorkerTokenSummaryResponse",
+    "CreateCredentialRequest",
+    "CreateRunRequest",
+    "CredentialBinding",
+    "CredentialMetadata",
+    "CredentialStatus",
+    "ReplaceCredentialValueRequest",
+    "WorkerSecretsResponse",
+    "WorkerInstanceInfo",
+    "SECRETS_METADATA_KEY",
+    "SESSION_SNAPSHOT_METADATA_KEY",
+    "SessionSnapshot",
+    "SnapshotComponent",
+    "SnapshotComponentKind",
+    "UpdateCredentialMetadataRequest",
+    "EventType",
+    "FailRunRequest",
+    "GRADER_CAPABILITY",
+    "GradeContext",
+    "GradeResult",
+    "HeartbeatRequest",
+    "HeartbeatResponse",
+    "HookEventName",
+    "HookEventType",
+    "HostedAgentCreateRequest",
+    "HostedAgentImage",
+    "HostedAgentMcpServer",
+    "HostedAgentResponse",
+    "HostedAgentSkill",
+    "HostedAgentUpdateRequest",
+    "WorkerCatalogCredential",
+    "WorkerCatalogDeployRequest",
+    "WorkerCatalogEntryResponse",
+    "WorkerCatalogIntegration",
+    "WorkerCatalogSelfHostedDeployRequest",
+    "WorkerCatalogSelfHostedDeployResponse",
+    "IngestRunEventsRequest",
+    "IngestRunEventsResponse",
+    "InvokeAgentRequest",
+    "InvokeAgentResponse",
+    "LogEventIn",
+    "LogEventResponse",
+    "LogLevel",
+    "MessageRole",
+    "MessageType",
+    "ModelActivity",
+    "OBSERVABILITY_EVENT_TYPES",
+    "PollNextRunRequest",
+    "RunDetail",
+    "RunEventIn",
+    "RunChannel",
+    "RunEventType",
+    "RunJob",
+    "RunMessageResponse",
+    "RunStatus",
+    "RunSummary",
+    "RunTransport",
+    "RunUsage",
+    "ScheduleResponse",
+    "ScheduleTriggerManifest",
+    "SlackKeywordTriggerManifest",
+    "CreateIntegrationConnectionRequest",
+    "CreateIntegrationConnectionResponse",
+    "CreateScheduleRequest",
+    "IntegrationAuthMode",
+    "IntegrationCatalogEntry",
+    "IntegrationConnection",
+    "IntegrationConnectionDetail",
+    "IntegrationCredentialField",
+    "IntegrationFieldType",
+    "IntegrationOAuthMetadata",
+    "IntegrationProviderCredentials",
+    "IntegrationStatus",
+    "StartIntegrationAppRequest",
+    "StartIntegrationAppResponse",
+    "StartIntegrationOAuthRequest",
+    "StartIntegrationOAuthResponse",
+    "TestIntegrationConnectionResponse",
+    "UpdateScheduleRequest",
+    "SkillDetail",
+    "SkillReference",
+    "SkillSourceAgent",
+    "SkillSummary",
+    "SpanKind",
+    "StartRunDirectRequest",
+    "StartRunRequest",
+    "TraceEventIn",
+    "TraceEventResponse",
+    "TraceEventType",
+    "TopCostRunSummary",
+    "AttachAgentToKBRequest",
+    "CreateKnowledgeBaseRequest",
+    "KBAgentGrant",
+    "KBChunkSummary",
+    "KBDocumentDetail",
+    "KBDocumentMetadata",
+    "KBDocumentOrigin",
+    "KBDocumentStatus",
+    "KBDocumentSummary",
+    "KBSearchFilters",
+    "KBSearchHit",
+    "KBSearchRequest",
+    "KBSearchResponse",
+    "KnowledgeBaseDetail",
+    "KnowledgeBaseSummary",
+    "UpdateAgentDraftRequest",
+    "UpdateAgentLabelsRequest",
+    "LABEL_MAX_LENGTH",
+    "LABEL_RULE_HINT",
+    "label_violations",
+    "UpdateRunOutputRequest",
+    "WorkerInvokeAgent",
+    "WorkerInvokeRequest",
+    "WorkerInvokeResponse",
+    "WorkspaceActivityResponse",
+    "FailureCategoryCount",
+    "IssueRecommendation",
+    "RunIssue",
+    "SaveIssueRecommendationRequest",
+    "WorkspaceIssuesResponse",
+    "IssueDetail",
+    "IssueGrouping",
+    "IssueListResponse",
+    "IssueLog",
+    "IssueRca",
+    "IssueSignal",
+    "IssueSource",
+    "IssueTimelineEvent",
+    "IssueWorker",
+    "UpdateIssueRequest",
+    "CreateScoreRequest",
+    "ScoreListResponse",
+    "ScoreResponse",
+    "ScoreTargetType",
+    "ScoreValue",
+    "UpdateScoreRequest",
+    "AgentQualityRollup",
+    "AutoScoreSeries",
+    "RunQualityRow",
+    "SkillQualityRollup",
+    "UngradedQueueResponse",
+]

agentops_rpc/a2a.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class A2AMessagePart(BaseModel):
+    model_config = ConfigDict(populate_by_name=True)
+
+    kind: str = "text"
+    text: str | None = None
+    data: dict[str, Any] | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return self.model_dump(exclude_none=True)
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> A2AMessagePart:
+        return cls.model_validate(d)
+
+
+class A2AMessage(BaseModel):
+    model_config = ConfigDict(populate_by_name=True)
+
+    role: str = "user"
+    message_id: str | None = Field(default=None, alias="messageId")
+    task_id: str | None = Field(default=None, alias="taskId")
+    context_id: str | None = Field(default=None, alias="contextId")
+    parts: list[A2AMessagePart] = Field(default_factory=list)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        d: dict[str, Any] = {"kind": "message", "role": self.role}
+        if self.message_id is not None:
+            d["messageId"] = self.message_id
+        if self.task_id is not None:
+            d["taskId"] = self.task_id
+        if self.context_id is not None:
+            d["contextId"] = self.context_id
+        d["parts"] = [p.to_dict() for p in self.parts]
+        d["metadata"] = self.metadata
+        return d
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> A2AMessage:
+        return cls.model_validate(d)
+
+
+class A2AMessageRequest(BaseModel):
+    message: A2AMessage
+    metadata: dict[str, Any] = Field(default_factory=dict, title="A2AMessageMetadata")
+
+
+class A2ATask(BaseModel):
+    model_config = ConfigDict(populate_by_name=True)
+
+    id: str
+    context_id: str | None = Field(default=None, alias="contextId")
+    status: dict[str, Any] = Field(default_factory=dict)
+    artifacts: list[dict[str, Any]] = Field(default_factory=list)
+    metadata: dict[str, Any] = Field(default_factory=dict, title="A2ATaskMetadata")
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "kind": "task",
+            "id": self.id,
+            "contextId": self.context_id,
+            "status": self.status,
+            "artifacts": self.artifacts,
+            "metadata": self.metadata,
+        }
+
+
+A2ATaskResponse = A2ATask

agentops_rpc/agent_create.py

@@ -0,0 +1,176 @@
+from __future__ import annotations
+
+import re
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+
+# agentId is used as a Helm release name, a Kubernetes resource name, and the
+# worker-token credential suffix, so it must be a valid RFC 1123 DNS label and fit
+# Helm's 53-char release-name limit.
+_AGENT_ID_RE = re.compile(r"^[a-z0-9]([-a-z0-9]*[a-z0-9])?$")
+_AGENT_ID_MAX_LEN = 53
+
+
+def validate_agent_id(v: str) -> str:
+    """Validate & normalize an operator-chosen ``agentId`` (the friendly per-account ``id_slug``).
+
+    Shared by every agent-creation entry point — full self-deploy create, worker-token mint, and the
+    Add-Agent wizard draft — so the same shape rule guards them all (the draft is the *first* step the
+    operator hits, so skipping it there let invalid slugs like ``"Bad Slug"`` reach the DB). Strips
+    surrounding whitespace, then enforces the RFC 1123 DNS-label shape + 53-char Helm limit.
+    """
+    v = v.strip()
+    if not v:
+        raise ValueError("must not be blank")
+    if len(v) > _AGENT_ID_MAX_LEN or not _AGENT_ID_RE.match(v):
+        raise ValueError(
+            f"must be a valid RFC 1123 DNS label (lowercase alphanumeric and '-', start/end alphanumeric, <= {_AGENT_ID_MAX_LEN} chars)"
+        )
+    return v
+
+
+def _camel(s: str) -> str:
+    head, *rest = s.split("_")
+    return head + "".join(w.capitalize() for w in rest)
+
+
+class _Camel(BaseModel):
+    model_config = ConfigDict(alias_generator=_camel, populate_by_name=True, extra="forbid")
+
+
+class CreateAgentSkill(_Camel):
+    id: str
+    content: str
+
+
+class CreateAgentMcpServer(_Camel):
+    # Transport-specific keys (type/command/args/env/url) vary; allow extras.
+    model_config = ConfigDict(alias_generator=_camel, populate_by_name=True, extra="allow")
+
+    name: str
+
+
+class CreateAgentRequest(_Camel):
+    agent_id: str
+    instructions: str
+    display_name: str = ""
+    model: str = "claude-sonnet-4-6"
+    skills: list[CreateAgentSkill] = Field(default_factory=list)
+    mcp_servers: list[CreateAgentMcpServer] = Field(default_factory=list)
+    replica_count: int = Field(default=1, ge=1)
+    # LLM key — provide EXACTLY ONE mode:
+    #   BYO: anthropic_api_key rendered into the chart Secret (lives in the user's cluster).
+    #   CP-managed: credential_ref the agent fetches from the control plane at boot.
+    anthropic_api_key: str | None = None
+    credential_ref: str | None = None
+    # Optional TTL for the minted worker token, so local/dev deploys don't need a permanent
+    # credential. None keeps today's non-expiring behavior.
+    ttl_seconds: int | None = Field(default=None, ge=1, le=86400)
+
+    @field_validator("instructions")
+    @classmethod
+    def _not_blank(cls, v: str) -> str:
+        if not v.strip():
+            raise ValueError("must not be blank")
+        return v
+
+    @field_validator("agent_id")
+    @classmethod
+    def _valid_agent_id(cls, v: str) -> str:
+        return validate_agent_id(v)
+
+    @field_validator("anthropic_api_key", "credential_ref")
+    @classmethod
+    def _blank_to_none(cls, v: str | None) -> str | None:
+        # Normalize blank/whitespace to None so downstream code can rely on truthiness.
+        return v.strip() if v and v.strip() else None
+
+    @model_validator(mode="after")
+    def _exactly_one_llm_mode(self) -> CreateAgentRequest:
+        byo = self.anthropic_api_key is not None
+        cp = self.credential_ref is not None
+        if byo and cp:
+            raise ValueError("provide exactly one of anthropicApiKey (BYO) or credentialRef (CP-managed), not both")
+        if not byo and not cp:
+            raise ValueError("provide an LLM key via anthropicApiKey (BYO) or credentialRef (CP-managed)")
+        return self
+
+
+class CreateAgentResponse(BaseModel):
+    model_config = ConfigDict(populate_by_name=True)
+
+    command: str
+    values: str
+    agent_id: str = Field(serialization_alias="agentId", validation_alias="agentId")
+    worker_token_hint: str = Field(serialization_alias="workerTokenHint", validation_alias="workerTokenHint")
+    expires_at: str | None = Field(default=None, serialization_alias="expiresAt", validation_alias="expiresAt")
+
+
+class CreateWorkerTokenRequest(_Camel):
+    agent_id: str
+    credential_ref: str | None = None
+    ttl_seconds: int | None = Field(default=None, ge=1, le=86400)
+
+    @field_validator("agent_id")
+    @classmethod
+    def _valid_agent_id(cls, v: str) -> str:
+        return validate_agent_id(v)
+
+
+class CreateWorkerTokenResponse(BaseModel):
+    model_config = ConfigDict(populate_by_name=True)
+
+    token: str
+    agent_id: str = Field(serialization_alias="agentId", validation_alias="agentId")
+    worker_token_hint: str = Field(serialization_alias="workerTokenHint", validation_alias="workerTokenHint")
+    expires_at: str | None = Field(default=None, serialization_alias="expiresAt", validation_alias="expiresAt")
+
+
+class WorkerTokenStatusResponse(BaseModel):
+    """Read-only lifecycle status of an agent's worker token. Carries NO secret material — the token
+    plaintext is shown only once, on create/rotate. Powers the "view + revoke" UI surface."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    # The friendly agent handle the caller asked about, echoed back for correlation in list views.
+    agent_id: str = Field(serialization_alias="agentId", validation_alias="agentId")
+    exists: bool
+    created_at: str | None = Field(default=None, serialization_alias="createdAt", validation_alias="createdAt")
+    last_rotated_at: str | None = Field(default=None, serialization_alias="lastRotatedAt", validation_alias="lastRotatedAt")
+    expires_at: str | None = Field(default=None, serialization_alias="expiresAt", validation_alias="expiresAt")
+    # True when the token carried a TTL that has already elapsed (it no longer authenticates).
+    expired: bool = False
+
+
+# The lifecycle of the *agent* a worker token belongs to, as far as the control plane can see it.
+# "unregistered" is the not-yet-installed case: the token was minted (e.g. by the self-deploy render)
+# but no agent_instances row exists yet — the worker has never heart-beaten. draft/online/offline
+# mirror the agent's computed status once a row exists.
+WorkerTokenAgentStatus = Literal["online", "offline", "draft", "unregistered"]
+
+
+class WorkerTokenSummaryResponse(BaseModel):
+    """One worker token in an account, for the Settings token table. Carries NO secret material.
+
+    Sourced from the ``worker-token-<agent_id>`` credentials directly (not from agent_instances), so
+    tokens of not-yet-installed agents — minted but never heart-beaten, hence with no agent row —
+    still appear. Agent metadata (``id_slug``/``name``/``is_archived``/``agent_status``) is null-ish
+    for those orphan tokens: only the opaque ``agent_id`` is known until the worker registers.
+    """
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    # Opaque internal agent id (``agt_…``) the token is bound to — the stable handle for revoke.
+    agent_id: str = Field(serialization_alias="agentId", validation_alias="agentId")
+    # Friendly per-account handle; null when the agent has never registered (rotate needs it, so a
+    # null slug means the UI offers revoke-only — you cannot safely rotate a token with no slug).
+    id_slug: str | None = Field(default=None, serialization_alias="idSlug", validation_alias="idSlug")
+    name: str | None = None
+    is_archived: bool = Field(default=False, serialization_alias="isArchived", validation_alias="isArchived")
+    agent_status: WorkerTokenAgentStatus = Field(default="unregistered", serialization_alias="agentStatus", validation_alias="agentStatus")
+    exists: bool = True
+    created_at: str | None = Field(default=None, serialization_alias="createdAt", validation_alias="createdAt")
+    last_rotated_at: str | None = Field(default=None, serialization_alias="lastRotatedAt", validation_alias="lastRotatedAt")
+    expires_at: str | None = Field(default=None, serialization_alias="expiresAt", validation_alias="expiresAt")
+    expired: bool = False