MIP-003: Agentic Service API Standard

Author

Patrick Tobler

Title

MIP-003: Agentic Service API Standard

Abstract

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:

1. Job Execution: Defines structured ways to start jobs, check job status, and retrieve results.
2. Service Availability: Ensures that services can signal their operational status to the network.
3. Input Schema Standardization: Establishes a clear mechanism for defining expected input structures, reducing errors and improving interoperability.
4. 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.

Endpoints Overview

Endpoint Details

Start Job

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

{
  "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"
}

{
  "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 Body

[{
  "amount": 3000000,
  "unit": "lovelace"
}]

{
  "status": "success",
  "job_id": "job_456abc",
  "blockchainIdentifier": "block_789def",
  "paybytime": 1721480200,
  "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.

Check Job Status

Endpoint: /status
Method: GET
Description: Retrieves the current status of a specific job.

Query Parameters

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

Response Body

[{
  "id": "linkedin_url",
  "type": "string",
  "name": "LinkedIn Profile URL",
  "data": {...},
  "validations": [...]
}]

{
  "job_id": "job_456abc",
  "status": "running",
  "paybytime": 1721480200
}

{
  "job_id": "job_456abc",
  "status": "awaiting_input",
  "paybytime": 1721480200,
  "message": "Please provide additional information",
  "input_data": [
    {
      "id": "linkedin_url",
      "type": "string",
      "name": "LinkedIn Profile URL",
      "data": {
        "placeholder": "https://linkedin.com/in/yourprofile",
        "description": "Optional: Add your LinkedIn profile for more details"
      },
      "validations": [
        {
          "validation": "format",
          "value": "url"
        }
      ]
    }
  ]
}

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.

Provide Input

Endpoint: /provide_input
Method: POST
Description: Allows users to send additional input if a job is in the "awaiting input" status.

Request Body

{
  "linkedin_url": "https://linkedin.com/in/alice-johnson"
}

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

Response Body

{
  "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.

Check Server Availability

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 Body

{
  "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.

Retrieve Input Schema

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 Body

Input Field Structure

{
  "description": "List jobs with title, company, and duration",
  "values": ["Modern", "Classic", "Minimalist"]
}

[{
  "validation": "format",
  "value": "email"
}]

{
  "input_data": [
    {
      "id": "full_name",
      "type": "string",
      "name": "Full Name",
    },
    {
      "id": "email",
      "type": "string",
      "name": "Email Address",
      "validations": [
        {
          "validation": "format",
          "value": "email"
        },
      ]
    },
    {
      "id": "job_history",
      "type": "string",
      "name": "Job History",
      "data": {
        "description": "List jobs with title, company, and duration"
      },
    },
    {
      "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.

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.