{
  "page": "guides/let-agent-choose-api-provider",
  "title": "Can an AI agent choose which API to call?",
  "path": "/guides/let-agent-choose-api-provider",
  "kind": "guide",
  "description": "Yes. How to let your agent pick a provider for each job at runtime instead of hardcoding one, and how to keep that choice honest.",
  "updated": "2026-10-23",
  "blocks": [
    {
      "type": "p",
      "text": "Yes. An agent can choose its API at runtime if it has two things: a list of the tools that can do the job, and a fair way to rank them. Hardcoding one provider is simpler, but it locks in that provider's accuracy, price and outages."
    },
    {
      "type": "h2",
      "id": "needs",
      "text": "What a good choice needs"
    },
    {
      "type": "list",
      "items": [
        "**Coverage.** The tools that can do this job, in this region.",
        "**A score from tests, not marketing.** The same cases run against every tool.",
        "**Price per useful result.** A cheap call that returns nothing isn't cheap.",
        "**A check on the answer.** So a wrong result is caught and not paid for."
      ]
    },
    {
      "type": "h2",
      "id": "compare",
      "text": "Hardcoded or chosen at runtime"
    },
    {
      "type": "table",
      "caption": "Hardcoded provider compared with choosing at runtime",
      "head": [
        "",
        "Hardcoded provider",
        "Chosen at runtime"
      ],
      "rows": [
        [
          "Switching provider",
          "A code change and a deploy",
          "Follows the ranking"
        ],
        [
          "When the provider fails",
          "Your agent fails or retries",
          "It can try the next-ranked tool"
        ],
        [
          "Accuracy",
          "Whatever that provider gives",
          "The best score for the job and region"
        ]
      ]
    },
    {
      "type": "h2",
      "id": "how",
      "text": "How to do it with Arettic"
    },
    {
      "type": "h3",
      "text": "1. Ask for the job"
    },
    {
      "type": "code",
      "title": "curl",
      "lang": "bash",
      "code": "curl https://api.arettic.com/v1/recommend \\\n  -H \"Authorization: Bearer sk_test_…\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{ \"task\": \"find the email and job title of the CTO at acme.com\" }'"
    },
    {
      "type": "p",
      "text": "The answer lists the tools ranked by score, then price, each with its price per passing result and the check it must pass."
    },
    {
      "type": "h3",
      "text": "2. Run the top tool"
    },
    {
      "type": "code",
      "title": "curl",
      "lang": "bash",
      "code": "curl https://api.arettic.com/v1/execute \\\n  -H \"Authorization: Bearer sk_test_…\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"tool_id\": \"hunter-verify-email\",\n    \"input\": { \"email\": \"jane@acme.com\" },\n    \"fallback\": true,\n    \"max_price\": 50\n  }'"
    },
    {
      "type": "p",
      "text": "With `fallback: true`, if an item fails, the next-ranked tool runs once within your `max_price`. Only the tool that passes is charged."
    },
    {
      "type": "h2",
      "id": "honest",
      "text": "Keep the ranking honest"
    },
    {
      "type": "p",
      "text": "A ranking only helps if nobody can buy their way up. On Arettic, paying never changes a score, rank or routing decision, and the score formula is public on [How scores work](/docs/scores). More on [provider discovery](/discovery)."
    }
  ],
  "questions": [
    {
      "question": "Is choosing at runtime slower?",
      "answer": "It adds one call. `recommend` is free, and your agent can reuse its answer for the same job and region."
    },
    {
      "question": "Can I force a provider?",
      "answer": "Yes. Send any purchasable `tool_id` to `execute`. On Pro and up, owners can pin a tool so it's tried first."
    }
  ]
}