Waxell Agent Governance Workflow

naftiko: 1.0.0-alpha2
info:
  label: Waxell Agent Governance Workflow
  description: >-
    Customer-facing workflow that combines Waxell Observe telemetry capture
    with runtime policy enforcement. Used by platform engineering teams to
    record every LLM call, evaluate governance policies before risky actions,
    and audit governance events for AI agents in production.
  tags:
    - Waxell
    - AI Agent Governance
    - Observability
    - Policy Enforcement
    - Cost Management
  created: '2026-05-06'
  modified: '2026-05-06'
binds:
  - namespace: env
    keys:
      WAXELL_API_KEY: WAXELL_API_KEY
      WAXELL_API_URL: WAXELL_API_URL
capability:
  imports:
    - location: shared/observe.yaml
  exposes:
    - type: http
      namespace: waxell-agent-governance
      description: Unified REST adapter for the agent governance workflow.
      paths:
        /agent-runs:
          post:
            summary: Start Agent Run
            operation: waxell-observe.runs.startrun
        /agent-runs/{run_id}/llm-calls:
          post:
            summary: Record LLM Call
            operation: waxell-observe.runs.recordllmcall
        /agent-runs/{run_id}/spans:
          post:
            summary: Record Span
            operation: waxell-observe.runs.recordspan
        /agent-runs/{run_id}/complete:
          post:
            summary: Complete Agent Run
            operation: waxell-observe.runs.completerun
        /policy-checks:
          post:
            summary: Check Policy
            operation: waxell-observe.governance.checkpolicy
        /audit-events:
          post:
            summary: Record Audit Event
            operation: waxell-observe.governance.recordevent
        /model-costs:
          get:
            summary: List Model Costs
            operation: waxell-observe.model-costs.listmodelcosts
        /prompts/{name}:
          get:
            summary: Get Managed Prompt
            operation: waxell-observe.prompts.getprompt
    - type: mcp
      namespace: waxell-agent-governance
      description: MCP adapter exposing the governance workflow as agent-callable tools.
      tools:
        - name: start_agent_run
          description: Begin a new Waxell Observe run for an agent.
          operation: waxell-observe.runs.startrun
        - name: record_llm_call
          description: Log an LLM API call (model, tokens, cost) against a run.
          operation: waxell-observe.runs.recordllmcall
        - name: record_span
          description: Log an OpenTelemetry-style span against a run.
          operation: waxell-observe.runs.recordspan
        - name: complete_agent_run
          description: Mark an agent run as completed or failed.
          operation: waxell-observe.runs.completerun
        - name: check_policy
          description: Evaluate Waxell governance policies before an agent action runs.
          operation: waxell-observe.governance.checkpolicy
        - name: record_audit_event
          description: Append a governance or audit event to the audit trail.
          operation: waxell-observe.governance.recordevent
        - name: list_model_costs
          description: Return the merged model cost table (defaults plus tenant overrides).
          operation: waxell-observe.model-costs.listmodelcosts
        - name: get_managed_prompt
          description: Fetch a versioned managed prompt by name and label.
          operation: waxell-observe.prompts.getprompt