agents.json: an open source specification for intelligences to interact with APIs via natural language

General Introduction

agents.json is an open source specification developed by Wildcard AI team, based on the OpenAPI standard, which aims to enable intelligent bodies to communicate with APIs efficiently through natural language. It defines the interaction contract between intelligences and APIs through structured JSON files, optimizes endpoint discovery and parameter generation, and solves the problem of chaotic order and low accuracy when intelligences call APIs. The project is version 0.1.0, hosted on GitHub (https://github.com/wild-card-ai/agents-json) under the Apache 2.0 license, and community participation is encouraged. With the Wildcard Bridge Python package, developers can load, parse, and run agents.json files to easily automate multi-step API calls.

Agents.json is an open source JSON specification that formally describes a contract for interaction between APIs and AI intelligences, building on the OpenAPI standard.

Function List

• Natural Language Driven API Calls: Intelligentsia trigger API operations in everyday language.
• Extensions based on OpenAPI: New interaction rules on OpenAPI to optimize the use of intelligences.
• Task flows and links: Define multi-step task flows (flows) and action links (links) to ensure call order.
• stateless design: Client management status to support existing infrastructure deployments.
• SDK Support: Wildcard Bridge loads and runs specification files to simplify development.

Using Help

Access and Preparation

agents.json is a canonical file that should be used in conjunction with the SDK or written manually. Here's how it works:

1. Get the agents.json file

• official example::
  Get the Quick Start Notebook from Wildcard AI, such as:
  • Resend:resend.ipynb
  • Stripe:single.ipynb
  • Google Sheets, etc:multiple-dynamic.ipynb
• Custom writing::
  ground Full schemathat creates the file. For example:

  {
  "apiVersion": "0.1.0",
  "baseUrl": "https://api.example.com",
  "chains": {
  "get_data": {
  "description": "Get the specified data",
  "agent_instructions": "Extracts data based on user input",
  "steps": [{ "endpoint": "/data", "method": "GET"}]
  }
  }
  }

It is recommended to place /.well-known/agents.json paths for easy discovery by intelligentsia.

2. Installation of Wildcard Bridge

• request: Python 3.10+.
• move::
  1. Run command:

     pip install wildcard-bridge
     

  2. Validation:

     python -c "import wildcard_bridge; print(wildcard_bridge.__version__)"
     

3. Configuration environment

• Certification Support: Supports Basic, ApiKey, and Bearer authentication. Example:

  from wildcard_bridge import Bridge
  bridge = Bridge(auth={"type": "ApiKey", "key": "your-api-key"})
  

• Connecting Intelligent Bodies: Access supported LLMs (e.g., OpenAI) and prepare base prompts.

Operation of the main functions

Function 1: Load and parse a specification file

• move::
  1. Load file:

     bridge.load_agents_json("path/to/agents.json")
     

  2. View the task chain:

     chains = bridge.get_available_chains()
     print(chains) # Output the available tasks, e.g. ["get_data"]
     

• use: Understanding supported operations, ready to run.

Function 2: Execution of task flows

• move::
  1. Run the task:

     result = bridge.run_chain("get_data", {"query": "sales report"})
     print(result) # Output API Return Results
     

  2. Check the return data.
• take: The user says "Give me the sales report" and the smartbody automatically calls the API.

Function 3: Debugging and Optimization

• adjust components during testing::

  bridge.enable_debug()
  result = bridge.run_chain("get_data", {"query": "test"})
  

  Check the logs to make sure each step is correct.

• make superior: Adjustments agent_instructions or examples to improve the accuracy of the intelligentsia.

Featured Function Operation

Task flow and link design

• workflow::
  1. Define multi-step task flows, such as Gmail replies:

     {
     "chains": {
     "reply_email": {
     "description": "Replies to emails",
     "agent_instructions": "Replies to emails based on user input",
     "steps": [
     { "endpoint": "/threads/{threadId}", "method": "GET"}, }
     {"endpoint": "/messages/send", "method": "POST"}
     ]
     }
     }
     }
     

  2. Running:

     bridge.run_chain("reply_email", {"threadId": "123", "reply": "received"})
     

• bright spot: The flows and links ensure that the calls are in the right order and that the intelligence does not have to reason about them.

Stateless compatibility with existing systems

• realization::
  The SDK runs on the client side and is adapted for serverless environments:

  def lambda_handler(event, context).
  bridge = Bridge(auth={"type": "Bearer", "token": event["token"]})
  bridge.load_agents_json("s3://bucket/agents.json")
  return bridge.run_chain("task", event["args"])
  

• dominance: No need to change the API server, just use it.

Example: Stripe Payment Inquiry

• agents.json::

  {
  "baseUrl": "https://api.stripe.com/v1",
  "chains": {
  "check_payment": {
  "description": "Checks the status of a payment",
  "agent_instructions": "Returns status based on payment ID",
  "steps": [{ "endpoint": "/charges/{chargeId}", "method": "GET"}]
  }
  }
  }
  

• (of a computer) run::

  result = bridge.run_chain("check_payment", {"chargeId": "ch_123"})
  print(result)
  

• effect: The smart body returns the payment status directly, which is simple and efficient.

caveat

• surety: The key is stored in an environment variable to avoid leakage.
• communal: Join Discord Get support.
• (computer) file: Reference official documentThe