How to Make an AI Agent API Call: A Developer Guide

An AI agent API call is a single request from your application to a language model provider that carries enough context — system instructions, conversation history, available tools, and parameters like temperature or max tokens — for the model to either respond directly or invoke a tool on your behalf. It's the basic unit of work behind every autonomous or semi-autonomous agent: research assistants, coding copilots, customer support bots, workflow automators.

If you're building an agent, the "API call" part is usually the easy 80%. The hard 20% is structuring requests so the model has what it needs to act reliably, handling tool execution loops, streaming partial output to users, and doing all of this without your API bill or latency spiraling out of control. This article walks through the anatomy of a well-formed agent API call, the loop that makes agents "agentic," and the tradeoffs you'll hit in practice.

The anatomy of an agent API call

Every agent API call to a modern LLM provider follows roughly the same shape, regardless of vendor:

• System prompt — role, constraints, and behavior the model should follow across the whole session
• Message history — the running conversation, including prior tool calls and their results
• Tool definitions — JSON schemas describing functions the model can request to invoke
• Model parameters — model name, max tokens, temperature, stop sequences
• Stream flag — whether to receive tokens incrementally or wait for the full response

A minimal call looks like this:

curl https://api.subtoapi.app/v1/messages \
  -H "Authorization: Bearer $SUBTOAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Summarize the attached ticket and suggest a fix."}
    ]
  }'

That's the whole request for a single-turn call. Agents get more interesting once tools enter the picture.

Adding tools to the call

Agents differentiate themselves from chatbots by taking action: querying a database, calling an internal API, running code, searching the web. You expose these actions to the model as tool definitions in the request body. The model then decides, based on the conversation, whether to respond in plain text or ask you to run a specific tool with specific arguments.

{
  "model": "claude-sonnet-4",
  "max_tokens": 1024,
  "tools": [
    {
      "name": "get_order_status",
      "description": "Look up the current status of a customer order by ID",
      "input_schema": {
        "type": "object",
        "properties": {
          "order_id": { "type": "string" }
        },
        "required": ["order_id"]
      }
    }
  ],
  "messages": [
    { "role": "user", "content": "Where's my order #48213?" }
  ]
}

The model doesn't execute get_order_status itself — it returns a tool-use block asking your application to run it. Your code executes the function, then sends the result back in a follow-up message so the model can produce a final answer. This request-execute-respond cycle is the core loop behind every agent, and it's why a single "agent action" from a user's perspective often maps to two or three raw API calls under the hood.

The agent loop in practice

A typical agent turn looks like this:

1. Send the conversation plus tool definitions to the model.
2. If the model returns a tool-use block, execute that function in your own code.
3. Append the tool result to the message history as a tool_result.
4. Send the updated history back to the model.
5. Repeat until the model returns a plain-text final answer.

async function runAgentTurn(messages, tools) {
  let response = await callModel(messages, tools);

  while (response.stop_reason === "tool_use") {
    const toolCall = response.content.find(c => c.type === "tool_use");
    const result = await executeTool(toolCall.name, toolCall.input);

    messages.push({ role: "assistant", content: response.content });
    messages.push({
      role: "user",
      content: [{ type: "tool_result", tool_use_id: toolCall.id, content: result }]
    });

    response = await callModel(messages, tools);
  }

  return response;
}

This loop is where most agent bugs live: forgetting to append the assistant's tool-use turn before the tool result, mismatched tool_use_ids, or letting the loop run unbounded if the model keeps requesting tools. Always cap iterations and log every call for debugging — full docs on this pattern are at /docs/tools.

Streaming for responsive agents

For anything user-facing, streaming matters more in agent contexts than in simple chat, because a single user action might trigger several model calls chained together. Streaming each call's tokens as they arrive keeps the UI from looking frozen during multi-step tool loops.

const res = await fetch("https://api.subtoapi.app/v1/messages", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.SUBTOAPI_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "claude-sonnet-4",
    max_tokens: 1024,
    stream: true,
    messages
  })
});

Details on parsing server-sent events, handling partial tool-use blocks mid-stream, and reconnecting on drops are covered in /docs/streaming.

Where SubToAPI fits

If your Claude access is currently tied to a personal or team chat subscription, there's no native way to call it programmatically — you need a proper HTTPS API. SubToAPI turns that access into sub_live_... API keys you can drop straight into agent code: standard /v1/messages requests, streaming, tool use, and per-key usage metadata so you can see exactly what each agent or environment is costing you. Plans start at Solo €9 for individual projects, with Team (€19/seat) and Scale (€49/seat) tiers adding shared keys and higher limits for teams running multiple agents. A free trial is available at /signup, and the fastest way to see a working call end-to-end is /docs/quickstart.

Questions

What's the difference between a regular API call and an AI agent API call? A regular API call is one request-response exchange. An agent API call is usually one step in a loop where the model can request tool execution, receive results, and continue reasoning across multiple calls before returning a final answer to the user.

How many API calls does one agent action actually use? It varies, but a task involving two tool lookups typically costs three model calls: one to decide the first tool, one after seeing the result to decide the next step, and one to produce the final response. Budget accordingly, especially with rate limits.

Do I need a special API for AI agents, or does a standard chat API work? A standard messages API with tool-use and streaming support is sufficient — you don't need a separate "agent API." What matters is that your provider supports tool definitions, tool results, and streaming in the same request format, which is standard on Claude-compatible endpoints like /docs/messages.