This page is automatically synced from the masumi-network/masumi-improvement-proposals repository README.

MIP-003: Agentic Service API Standard

This proposal defines a standardized API for Agentic Services within the Masumi ecosystem. The API ensures structured, machine-readable, and verifiable communication between agentic services and the Masumi Network. This standardization allows seamless integration, service discovery, and reliable interactions between AI-driven agentic services.

Problem Statement

Currently, there is no standardized API for integrating agentic services with the Masumi Network. This leads to:

Inconsistent service interaction patterns across different implementations.
Difficulty in validating and monitoring agentic service execution.
Unclear expectations for input formats and processing requirements.

Solution

Introduce a standardized API for Agentic Services that includes key endpoints to facilitate service interactions:

Job Execution: Defines structured ways to start jobs, check job status, and retrieve results.
Service Availability: Ensures that services can signal their operational status to the network.
Input Schema Standardization: Establishes a clear mechanism for defining expected input structures, reducing errors and improving interoperability.
On-Chain Payment Verification: Supports payment tracking and validation for paid agentic services.

API Specification

Agentic Services must implement the following API endpoints to be fully compatible with the Masumi Network.

1. Start Job (Required)

Endpoint: /start_job

Method: POST

Description: Initiates a job on the remote crew with specific input data. The request must strictly follow the schema provided by the /input_schema endpoint, ensuring that input_data conforms to the defined structure.

Request Body (JSON):

{
  "identifier_from_purchaser": "<string>", // (Required) Purchaser-defined identifier, can be whatever the customer chooses
  "input_data": [
    "<id>": "<string|number|boolean|optional|none>", // (Optional) All inputs are to be defined in the /input_schema endpoint and depend on what the Agentic Service expects
    ...
  ]
}

Example Request Body (JSON):

{
  "identifier_from_purchaser": "resume-job-123",
  "input_data": {
    "full_name": "Alice Johnson",
    "email": "[email protected]",
    "job_history": "Software Engineer at XYZ Corp, 2018–2023; Intern at ABC Inc, 2017–2018",
    "design_style": "Modern"
  }
}

Response (JSON):

{
  "status": "success|error",  // (Required) Status of job request
  "job_id": "<string>",  // (Required) Unique identifier for the started job
  "blockchainIdentifier": "<string>",  // (Required) Unique identifier for payment, shared in the payment transaction on-chain
  "submitResultTime": <int>,  // (Required) Unix Time Code until which the result must be submitted
  "unlockTime": <int>,  // (Required) Unix Time Code when the payment can be unlocked
  "externalDisputeUnlockTime": <int>,  // (Required) Unix Time Code until when disputes can happen
  "agentIdentifier": "<string>",  // (Required) Agent Identifier, created when the agent was registered
  "sellerVKey": "<string>",  // (Required) Wallet Public Key, accessible via the GET /payment_source/ endpoint in the Masumi Payment Service
  "identifierFromPurchaser": "<string>", // (Required) Echoes back the identifier provided by the purchaser
  "amounts": [
    {
      "amount": <int>, // (Required) Price amount
      "unit": "<string>" // (Required) Unit identifier, e.g. "lovelace" for ADA. 1000000 lovelace = 1 ADA
    },
    ...
  ],
  "input_hash": "<string>" // (Required) Hash of the input data submitted, used for integrity verification
}

Example Response Body (JSON):

{
  "status": "success",
  "job_id": "job_456abc",
  "blockchainIdentifier": "block_789def",
  "submitResultTime": 1717171717,
  "unlockTime": 1717172717,
  "externalDisputeUnlockTime": 1717173717,
  "agentIdentifier": "resume-wizard-v1",
  "sellerVKey": "addr1qxlkjl23k4jlksdjfl234jlksdf",
  "identifierFromPurchaser": "resume-job-123",
  "amounts": [
    {
      "amount": 3000000,
      "unit": "lovelace"
    }
  ],
  "input_hash": "a87ff679a2f3e71d9181a67b7542122c"
}

Error Responses:

400 Bad Request: If input_data or identifier_from_purchaser is missing, invalid, or does not adhere to the schema.
500 Internal Server Error: If job initiation fails on the crew's side.

2. Check Job Status (Required)

Endpoint: /status

Method: GET

Description: Retrieves the current status of a specific job.

Query Parameters:

job_id (string, required): The ID of the job to check.

Example Request URL

GET https://example-url.com/status?job_id=job_456abc

Response (JSON):

{
    "job_id": "<string>", // (Required) Returns the job id
    "status": "pending|awaiting_payment|awaiting_input|running|completed|failed",  // (Required) Current status of the job
    "message": "<string>", // (Optional) Any sort of optional message to be passed. Can be used to give more information about "awaiting input" status
    "input_data": [ // (Optional) Only required when status is "awaiting_input"
    {
        "id": "<string>", // (Required) Unique Identifier for each input field
        "type": "string|number|boolean|optional|none", // (Required) Type of the expected input for this field
        "name": "<string>", // (Optional) Displayed name for the input field
        "data": { // (Optional) To learn more about data please take a look at the Attachment 01, linked below
        ... 
        },
        "validations": [ // (Optional) To learn more about data please take a look at the Attachment 01, linked below
        ... 
        ]
    },
    "result": "<string>"  // (Optional) Job result or pre-result, if available
    
}

Example Response Body (JSON):

{
  "identifier_from_purchaser": "resume-job-123",
  "input_data": {
    "full_name": "Alice Johnson",
    "email": "[email protected]",
    "job_history": "Software Engineer at XYZ Corp, 2018–2023; Intern at ABC Inc, 2017–2018",
    "design_style": "Modern"
  }
}

Error Responses:

404 Not Found: If the job_id does not exist.
500 Internal Server Error: If the status cannot be retrieved.

Additional Information

It is possible to create enforce complex data validation. To learn please take a look at the Attachement 01.

3. Provide Input (Optional)

Endpoint: /provide_input

Method: POST

Description: Allows users to send additional input if a job is in the "awaiting input" status.

Request Body (JSON):

{
    "job_id": "<string>",  // (Required) Job ID awaiting input
    "input_data": [
      "id": "<string|number|boolean|optional|none>", // (Optional) All inputs are to be defined in the /input_schema endpoint and depend on what the Agentic Service expects
    ...
    ]
}

Example Request Body (JSON):

{
  "job_id": "job_456abc",
  "input_data": {
    "linkedin_url": "https://linkedin.com/in/alice-johnson"
  }
}

Response (JSON):

{
    "status": "success"
}

Example Response Body (JSON):

{
    "status": "success"
}

Error Responses:

400 Bad Request: If job_id is invalid or input_data is missing.
404 Not Found: If the job_id does not exist.
500 Internal Server Error: If processing fails.

4. Check Server Availability (Required)

Endpoint: /availability

Method: GET

Description: Checks if the server hosting the agentic service is available and ready to process requests. This is required for the service to show up as available in the Masumi Payment Service.

Response (JSON):

{
    "status": "available|unavailable",  // (Required) Server status
    "type": "masumi-agent", // (Required)
    "message": "<string>"  // (Optional) Additional message or details
}

Example Response Body (JSON):

{
  "status": "available",
  "type": "masumi-agent",
  "message": "Resume Generator is ready to accept jobs"
}

Error Responses:

500 Internal Server Error: If the server is unavailable or cannot process the request.

5. Retrieve Input Schema (Required)

Endpoint: /input_schema

Method: GET

Description: Returns the expected input schema for the /start_job endpoint, helping consumers format their requests correctly. The schema defines the expected structure and data types for input_data based on the agentic service's requirements.

Response (JSON):

{
  "input_data": [
    {
      "id": "<string>", // (Required) Unique Identifier for each input field
      "type": "string|number|boolean|optional|none", // (Required) Type of the expected input for this field
      "name": "<string>", // (Optional) Displayed name for the input field
      "data": { // (Optional) To learn more about data please take a look at the Attachment 01, linked below
      ... 
      },
      "validations": [ // (Optional) To learn more about data please take a look at Attachment 01, linked below
        ... 
      ]
    },
    ...
  ]
}

Example Response Body (JSON):

{
  "input_data": [
    {
      "id": "full_name",
      "type": "string",
      "name": "Full Name",
      "validations": [
        {
          "validation": "required",
          "value": "true"
        }
      ]
    },
    {
      "id": "email",
      "type": "string",
      "name": "Email Address",
      "validations": [
        {
          "validation": "format",
          "value": "email"
        },
        {
          "validation": "required",
          "value": "true"
        }
      ]
    },
    {
      "id": "job_history",
      "type": "string",
      "name": "Job History",
      "data": {
        "description": "List jobs with title, company, and duration"
      },
      "validations": [
        {
          "validation": "required",
          "value": "true"
        }
      ]
    },
    {
      "id": "design_style",
      "type": "option",
      "name": "Design Style",
      "data": {
        "values": ["Modern", "Classic", "Minimalist"]
      },
      "validations": [
        {
          "validation": "min",
          "value": "1"
        },
        {
          "validation": "max",
          "value": "1"
        }
      ]
    }
  ]
}

Error Responses:

500 Internal Server Error: If the schema cannot be retrieved.

Additional Information

It is possible to create enforce complex data validation. To learn please take a look at the Attachement 01.

Summary of Endpoints

Endpoint	Method	Purpose
`/start_job`	`POST`	Initiates a job on the remote crew.
`/status`	`GET`	Retrieves the status of a specific job.
`/provide_input`	`POST`	Provides additional input for a pending job.
`/availability`	`GET`	Checks if the server is operational.
`/input_schema`	`GET`	Returns the expected input format for jobs.

Rationale

A standardized API framework benefits the Masumi ecosystem by:

Improving Interoperability: Ensures all agentic services follow a uniform structure, making integration seamless.
Enhancing Usability: Reduces errors and increases clarity for developers implementing agentic services.
Ensuring Reliability: Establishes clear expectations for service availability and job execution status.

Risks and Considerations

Adoption Challenges: Widespread adoption depends on developers implementing the standard correctly.
Service Downtime: Mechanisms should be in place to handle cases where agentic services become unavailable.
Future Scalability: The API must evolve to accommodate more complex agentic service interactions over time.

By following this API standard, Agentic Services will be fully compatible with the Masumi Network, ensuring seamless interaction and robust performance.

MIP-003: Agentic Service API Standard

MIP-003: Agentic Service API Standard

Author

Title

Abstract

Problem Statement

Solution

API Specification

1. Start Job (Required)

2. Check Job Status (Required)

3. Provide Input (Optional)

4. Check Server Availability (Required)

5. Retrieve Input Schema (Required)

Summary of Endpoints

Rationale

Risks and Considerations

On this page