Skip to main content

Overview

ACN works with any agent framework that supports function/tool calling. The pattern is always the same:
  1. Define a “discover” tool that calls POST /v1/discover
  2. Define an “execute” tool that calls POST /v1/execute/:providerId/:endpointSlug
  3. Give both tools to your agent

Generic Pattern

The Two Functions

import os
import requests

ACN_BASE_URL = "https://api.acn.exchange"
ACN_API_KEY = os.environ["ACN_API_KEY"]

def acn_discover(query: str, category: str = None, max_price: float = None) -> dict:
    """Search ACN for services matching a query."""
    body = {"query": query}
    if category or max_price:
        body["filters"] = {}
        if category:
            body["filters"]["category"] = category
        if max_price:
            body["filters"]["max_price_per_call"] = max_price

    response = requests.post(f"{ACN_BASE_URL}/v1/discover", json=body)
    return response.json()

def acn_execute(provider_id: str, endpoint_slug: str, **payload) -> dict:
    """Execute a service on ACN."""
    response = requests.post(
        f"{ACN_BASE_URL}/v1/execute/{provider_id}/{endpoint_slug}",
        headers={"Authorization": f"Bearer {ACN_API_KEY}"},
        json=payload
    )
    return response.json()

Tool Schema (OpenAI Function Calling Format)

Most frameworks accept tool definitions in OpenAI’s function calling format:
[
  {
    "type": "function",
    "function": {
      "name": "acn_discover",
      "description": "Search ACN marketplace for services. Returns ranked results with pricing and quality scores.",
      "parameters": {
        "type": "object",
        "properties": {
          "query": {
            "type": "string",
            "description": "Natural language description of what you need"
          },
          "category": {
            "type": "string",
            "enum": ["data_intelligence", "ai_ml", "communication", "blockchain", "utility"],
            "description": "Optional category filter"
          },
          "max_price_per_call": {
            "type": "number",
            "description": "Maximum price per call in USDC"
          }
        },
        "required": ["query"]
      }
    }
  },
  {
    "type": "function",
    "function": {
      "name": "acn_execute",
      "description": "Execute a service discovered on ACN. Costs are deducted from your balance automatically.",
      "parameters": {
        "type": "object",
        "properties": {
          "provider_id": {
            "type": "string",
            "description": "Provider ID from discovery results"
          },
          "endpoint_slug": {
            "type": "string",
            "description": "Endpoint slug from discovery results"
          },
          "payload": {
            "type": "object",
            "description": "Request payload matching the endpoint's parameter schema"
          }
        },
        "required": ["provider_id", "endpoint_slug", "payload"]
      }
    }
  }
]

Framework Examples

Google ADK (Agent Development Kit)

from google.adk.agents import Agent

agent = Agent(
    model="gemini-2.0-flash",
    name="acn_agent",
    instruction="Use ACN to discover and execute external services.",
    tools=[acn_discover, acn_execute]
)

OpenAI Agents SDK

from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-4o",
    tools=[discover_schema, execute_schema],
    input="Find the current ETH price using ACN"
)

Bare HTTP (No Framework)

If your agent doesn’t use a framework, just call the REST API directly:
# Step 1: Discover
curl -X POST https://api.acn.exchange/v1/discover \
  -H "Content-Type: application/json" \
  -d '{"query": "cryptocurrency prices"}'

# Step 2: Execute (using provider_id and endpoint_slug from step 1)
curl -X POST https://api.acn.exchange/v1/execute/coingecko/get-price \
  -H "Authorization: Bearer acn_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"ids": "bitcoin", "vs_currencies": "usd"}'

Tips

  • Good tool descriptions matter. The LLM uses the description to decide when to call ACN. Be specific about what the tool does.
  • Include cost info in the system prompt. Tell your agent to check pricing.price_per_call_usdc from discovery results before executing.
  • Handle errors gracefully. If a call returns an error, let the agent try a different provider rather than retrying the same one.