openapi: 3.1.0
info:
  title: Agoragentic Rust Framework Runtime
  version: 0.1.0
  description: |
    Focused OpenAPI profile for local or self-hosted Agoragentic Rust
    framework runtimes. The runtime is Harness-compatible over HTTP/JSON and
    exposes health, Agent Card discovery, tool discovery, typed invocation,
    local A2A JSON-RPC, and the generated JSON Schema/OpenAPI artifacts. This
    profile is not the hosted Agoragentic Router / Marketplace contract.
  x-agoragentic-framework:
    framework: agoragentic-rust
    version: 0.1.0
    transport: http-json
    harness_compatible: true
    schema_id: https://agoragentic.com/schema/agoragentic-rust-framework.v1.json
    hosted_provisioning_enabled: false
    wallet_spend_enabled: false
    x402_settlement_enabled: false
    marketplace_publication_enabled: false
    trust_state_mutation_enabled: false
    global_execute_mutation_enabled: false
    global_invoke_mutation_enabled: false
    provider_calls_required: false
    native_bindings_required: false
servers:
  - url: http://127.0.0.1:8080
    description: Local Rust framework runtime
tags:
  - name: runtime
    description: Local Rust runtime health and discovery
  - name: invoke
    description: Local HTTP/JSON invocation boundary
  - name: a2a
    description: Local A2A JSON-RPC bridge
  - name: schema
    description: Static compatibility artifacts
paths:
  /health:
    get:
      tags:
        - runtime
      operationId: getRustFrameworkHealth
      summary: Get local Rust framework runtime health
      responses:
        "200":
          description: Runtime health and compatibility metadata
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HealthResponse"
  /.well-known/agent-card.json:
    get:
      tags:
        - runtime
      operationId: getRustFrameworkAgentCard
      summary: Get local Rust framework Agent Card
      responses:
        "200":
          description: Local Rust framework Agent Card
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentCardResponse"
  /tools:
    get:
      tags:
        - runtime
      operationId: listRustFrameworkTools
      summary: List registered local Rust framework tools
      responses:
        "200":
          description: Registered tool specifications
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ToolSpec"
  /invoke:
    post:
      tags:
        - invoke
      operationId: invokeRustFrameworkAgent
      summary: Invoke a local Rust framework agent
      description: |
        Accepts the stable invocation request envelope used by local
        Harness-compatible Rust agents. The request is local/self-hosted and
        does not imply hosted Router execution, wallet spend, x402 settlement,
        marketplace publication, trust mutation, or provider dispatch.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/InvocationRequest"
      responses:
        "200":
          description: Invocation completed, failed, or was blocked by local policy
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InvocationResponse"
        "400":
          description: Invalid invocation request represented as a failed invocation response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InvocationResponse"
        "500":
          description: Local runtime error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RustFrameworkError"
  /a2a/invoke:
    post:
      tags:
        - a2a
      operationId: invokeRustFrameworkA2a
      summary: Send a local A2A JSON-RPC message
      description: |
        Local JSON-RPC bridge for Rust framework agent-to-agent calls. This is
        separate from the hosted Agent OS gateway and does not publish agents
        into the marketplace or mutate trust state.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/A2aJsonRpcRequest"
      responses:
        "200":
          description: JSON-RPC response from the local A2A bridge
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/A2aJsonRpcResponse"
        "400":
          description: Invalid JSON-RPC request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/A2aJsonRpcResponse"
  /schema/agoragentic-rust-framework.json:
    get:
      tags:
        - schema
      operationId: getRustFrameworkSchema
      summary: Get the Rust framework JSON Schema artifact
      responses:
        "200":
          description: Rust framework JSON Schema
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
  /openapi.json:
    get:
      tags:
        - schema
      operationId: getRustFrameworkOpenApiJson
      summary: Get the local Rust framework OpenAPI profile
      responses:
        "200":
          description: Rust framework OpenAPI 3.1 profile
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
components:
  schemas:
    JsonValue:
      description: Any JSON value accepted at the HTTP/JSON boundary.
    RuntimeInfo:
      type: object
      required:
        - language
        - transport
        - harness_compatible
      properties:
        language:
          type: string
          example: rust
        transport:
          type: string
          example: http-json
        harness_compatible:
          type: boolean
          example: true
    HealthResponse:
      type: object
      required:
        - agent_id
        - framework
        - framework_version
        - runtime
        - status
      properties:
        agent_id:
          type: string
        framework:
          type: string
          example: agoragentic-rust
        framework_version:
          type: string
          example: 0.1.0
        runtime:
          $ref: "#/components/schemas/RuntimeInfo"
        status:
          type: string
          example: ok
    AgentCardInterface:
      type: object
      required:
        - url
        - protocolBinding
        - protocolVersion
      properties:
        url:
          type: string
          example: http://127.0.0.1:8080/a2a/invoke
        protocolBinding:
          type: string
          example: HTTP+JSON
        protocolVersion:
          type: string
          example: "1.0"
    AgentCardProvider:
      type: object
      required:
        - organization
        - url
      properties:
        organization:
          type: string
          example: Agoragentic Rust Framework
        url:
          type: string
          example: https://agoragentic.com
    AgentCardCapabilities:
      type: object
      required:
        - streaming
        - pushNotifications
        - stateTransitionHistory
        - extendedAgentCard
      properties:
        streaming:
          type: boolean
          example: false
        pushNotifications:
          type: boolean
          example: false
        stateTransitionHistory:
          type: boolean
          example: false
        extendedAgentCard:
          type: boolean
          example: true
    AgentCardSkill:
      type: object
      required:
        - id
        - name
        - description
        - tags
        - inputModes
        - outputModes
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        tags:
          type: array
          items:
            type: string
        inputModes:
          type: array
          items:
            type: string
        outputModes:
          type: array
          items:
            type: string
    AgentCardResponse:
      type: object
      required:
        - name
        - description
        - supportedInterfaces
        - provider
        - version
        - documentationUrl
        - capabilities
        - defaultInputModes
        - defaultOutputModes
        - skills
        - extensions
      properties:
        name:
          type: string
        description:
          type: string
        supportedInterfaces:
          type: array
          items:
            $ref: "#/components/schemas/AgentCardInterface"
        provider:
          $ref: "#/components/schemas/AgentCardProvider"
        version:
          type: string
        documentationUrl:
          type: string
        capabilities:
          $ref: "#/components/schemas/AgentCardCapabilities"
        defaultInputModes:
          type: array
          items:
            type: string
        defaultOutputModes:
          type: array
          items:
            type: string
        skills:
          type: array
          items:
            $ref: "#/components/schemas/AgentCardSkill"
        extensions:
          type: object
          additionalProperties: true
    ToolSideEffects:
      type: object
      required:
        - network
        - filesystem
        - wallet
        - external_write
      properties:
        network:
          type: boolean
        filesystem:
          type: boolean
        wallet:
          type: boolean
        external_write:
          type: boolean
    ToolSpec:
      type: object
      required:
        - name
        - description
        - side_effects
      properties:
        name:
          type: string
        description:
          type: string
        input_schema:
          $ref: "#/components/schemas/JsonValue"
        output_schema:
          $ref: "#/components/schemas/JsonValue"
        side_effects:
          $ref: "#/components/schemas/ToolSideEffects"
    ReceiptRef:
      type: object
      required:
        - receipt_id
        - vendor_id
        - amount_usdc
      properties:
        receipt_id:
          type: string
        vendor_id:
          type: string
        amount_usdc:
          type: string
          example: "0"
    InvocationContext:
      type: object
      required:
        - memory_refs
        - messages
        - receipt_refs
      properties:
        memory_refs:
          type: array
          items:
            type: string
        messages:
          type: array
          items:
            $ref: "#/components/schemas/JsonValue"
        receipt_refs:
          type: array
          items:
            $ref: "#/components/schemas/ReceiptRef"
    InvocationLimits:
      type: object
      properties:
        timeout_ms:
          type: integer
          minimum: 0
          default: 30000
        max_tokens:
          type: integer
          minimum: 0
          default: 8000
        max_cost_usdc:
          type: string
          default: "0"
    TraceContext:
      type: object
      required:
        - trace_id
      properties:
        trace_id:
          type: string
        parent_span_id:
          type:
            - string
            - "null"
        marketplace_invocation_id:
          type:
            - string
            - "null"
    InvocationRequest:
      type: object
      required:
        - request_id
        - agent_id
        - task
        - input
      properties:
        request_id:
          type: string
        agent_id:
          type: string
        task:
          type: string
          default: default
        input:
          $ref: "#/components/schemas/JsonValue"
        context:
          $ref: "#/components/schemas/InvocationContext"
        limits:
          $ref: "#/components/schemas/InvocationLimits"
        trace:
          $ref: "#/components/schemas/TraceContext"
    InvocationStatus:
      type: string
      enum:
        - accepted
        - running
        - completed
        - failed
        - blocked
        - cancelled
    RustFrameworkError:
      type: object
      required:
        - type
        - message
      properties:
        type:
          type: string
          enum:
            - Serialization
            - Tool
            - DuplicateTool
            - Provider
            - InvalidRequest
            - NotFound
            - PolicyBlocked
            - Runtime
        message:
          type: string
    InvocationResponse:
      type: object
      required:
        - request_id
        - agent_id
        - status
        - tool_calls
        - memory_refs
        - events
        - trace
      properties:
        request_id:
          type: string
        agent_id:
          type: string
        status:
          $ref: "#/components/schemas/InvocationStatus"
        output:
          $ref: "#/components/schemas/JsonValue"
        tool_calls:
          type: array
          items:
            $ref: "#/components/schemas/JsonValue"
        memory_refs:
          type: array
          items:
            type: string
        events:
          type: array
          items:
            $ref: "#/components/schemas/JsonValue"
        error:
          oneOf:
            - $ref: "#/components/schemas/RustFrameworkError"
            - type: "null"
        trace:
          $ref: "#/components/schemas/TraceContext"
    A2aJsonRpcRequest:
      type: object
      required:
        - jsonrpc
        - method
      properties:
        jsonrpc:
          type: string
          example: "2.0"
        method:
          type: string
          example: message/send
        params:
          $ref: "#/components/schemas/JsonValue"
        id:
          $ref: "#/components/schemas/JsonValue"
    A2aJsonRpcError:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: integer
        message:
          type: string
        data:
          $ref: "#/components/schemas/JsonValue"
    A2aJsonRpcResponse:
      type: object
      required:
        - jsonrpc
      properties:
        jsonrpc:
          type: string
          example: "2.0"
        result:
          $ref: "#/components/schemas/JsonValue"
        error:
          oneOf:
            - $ref: "#/components/schemas/A2aJsonRpcError"
            - type: "null"
        id:
          $ref: "#/components/schemas/JsonValue"