agents.json Python Implementation

The agents.json Specification (current version 0.1.0) is an open specification designed to formally describe contracts for API and agent interactions. It is built on top of the OpenAPI standard but optimized for LLM consumption.

While OpenAPI describes how endpoints work, agents.json adds structured contracts that help AI agents understand how to execute multi-step workflows. Key additions include:

• Optimized Schema: Updated descriptions and added examples specifically for LLM argument generation and endpoint discovery.
• Flows: Contracts consisting of one or more API calls that describe a specific outcome (e.g., instead of searching for an email and then replying, a single 'flow' can handle the entire task).
• Links: Definitions of how different actions are stitched together, allowing agents to understand the sequence of operations required to achieve a goal.

It is proposed that agents.json files be placed in /.well-known/agents.json for easy discovery by agents.

The GoogleSheetsAgent class encapsulates the logic for interacting with Google Sheets using agents.json. It manages three main lifecycle steps:

1. setup_google_auth(): Sets up the Google Sheets API credentials using a provided JSON auth file.
2. load_agents_json(agents_json_path): Loads the agents.json file and its corresponding openapi.yaml spec to build a Bundle object.
3. execute_query(query, flow_hint): Takes a natural language query, uses an LLM (OpenAI) to select the appropriate API flows, and executes them against the Google Sheets API.

To use the agent, initialize it with your auth_json_path and openai_api_key, then call the setup and load methods before executing queries.

from openai import OpenAI
from agentsjson.core.models.bundle import Bundle
from agentsjson.core.executor import execute_flows
import agentsjson.core as core
from agentsjson.core import ToolFormat

class GoogleSheetsAgent:
    def __init__(self, auth_json_path: str, openai_api_key: str):
        self.auth_json_path = auth_json_path
        self.openai_api_key = openai_api_key
        self.google_creds = None
        self.bundle = None
        self.flows = None
        self.openai_client = OpenAI(api_key=openai_api_key)

    def setup_google_auth(self) -> None:
        # ... implementation ...
        pass

    def load_agents_json(self, agents_json_path: str) -> None:
        # ... implementation ...
        pass

    def execute_query(self, query: str, flow_hint: Optional[List[str]] = None) -> Dict[str, Any]:
        # ... implementation ...
        pass

For complex user requests that require multiple specialized agents, you can implement an orchestrator pattern. This involves:

1. Defining a list of sub-agents with names and descriptions.
2. Creating a system prompt that instructs the LLM to break down tasks and select the appropriate agent.
3. Defining a tool (e.g., execute_agent) that the orchestrator can call to delegate tasks to sub-agents.
4. Recursively calling the orchestrator until the task is complete or the LLM returns a 'STOP' signal.

# Example structure for an orchestrator agent list
agents_list = [
    {
        "name": "twitter_agent",
        "agent": twitter_agent,
        "description": "This agent makes requests to the Twitter API."
    },
    {
        "name": "giphy_agent",
        "agent": giphy_agent,
        "description": "This agent makes requests to the Giphy API."
    }
]

# The orchestrator uses the agent descriptions to decide which tool to call
# and passes natural language tasks to the sub-agents.

You can implement a 'Wildcard Agent' that uses a specialized tool to search for the correct API flow based on a natural language task.

1. Define a wildcard_tool for the LLM to call.
2. The LLM calls wildcard_tool with a task description.
3. Use the Wildcard Search API (https://queryfd.onrender.com/search) to find the matching flow_id and api_name using the task description.

import requests
import json

# 1. Define the tool for the LLM
wildcard_tool = {
    "type": "function",
    "function": {
        "name": "wildcard_tool",
        "description": "This function is responsible for calling the wildcard tool search API to find the right tool to use.",
        "parameters": {
            "type": "object",
            "properties": {
                "task": {
                    "type": "string",
                    "description": "A brief description of the task to accomplish described precisely in natural language."
                }
            },
            "required": ["task"],
        }
    }
}

# 2. After the LLM calls the tool, query the Wildcard API
# (Assuming 'response' is the LLM output containing the tool call)
args = json.loads(response.choices[0].message.tool_calls[0].function.arguments)
task = args["task"]

search_url = "https://queryfd.onrender.com/search"
search_params = {
    "query": task,
    "collection_name": "YOUR_COLLECTION_NAME"
}

search_response = requests.get(search_url, params=search_params, headers={"x-api-key": "YOUR_WILDCARD_API_KEY"})
search_results = search_response.json()

# 3. Extract flow details
flow_id = search_results["points"][0]["payload"]["flow"]["id"]
api_name = search_results["points"][0]["payload"]["info"]["title"]