jd five

When the SDK Runs the Loop

You already wrote the tool-call loop yourself: call the model, maybe run a tool / skill, append the result, call again, with a step limit.

Some SDKs offer a shortcut: you hand them the tools as real functions, and the SDK runs the loop inside one API helper call. Same job. Less code you write.

Two ways to get the same result

Approach Who writes the loop? You see each step?
Manual loop (previous chapter) You Yes — every tool call and result
SDK-run loop (this chapter) The SDK Often less — unless you log or read history the SDK keeps
Same stairs. Who climbs them?
  Manual                         SDK helper
  ──────                         ──────────
  you: call model                you: one generate call
  you: run tool                    │
  you: call model                  ├── SDK calls model
  you: …                           ├── SDK runs your function
  you: stop                        ├── SDK calls model again
                                   └── returns final text

Long declaration vs pass-a-function

Earlier labs declared the tool the long way: name, description, and input fields in a schema object.

The SDK-run shortcut often uses a short way: pass a real function (or method) from your language. The SDK builds the declaration and can run that function when the model asks.

Style What you hand the SDK Who writes the description?
Long Name + description + parameter schema You
Short The function / method itself Mostly the SDK, from what it can read off the function

Same tool. Different packaging.

How the short way gets a description

The model still needs a description to choose the tool wisely. On the short path, the SDK has to invent that from your code.

Python: a docstring is the short text under def, written in triple quotes:

def read_file(path: str) -> str:
    """Read a text file by path and return its contents."""
    ...

Many Python SDKs send that docstring as the tool description, and build parameter fields from the function’s arguments and types. A clear docstring matters.

Java: the lookalike is a Javadoc comment (/** … */ above the method). But when you pass a reflected Method, that runtime object has the name and parameter types — it does not carry the Javadoc text. Comments are stripped when the code is compiled.

So on Java’s short path, the description the model sees is often thinner (name + types), and easier to get wrong than an explicit FunctionDeclaration description you wrote yourself.

Language Short path description quality
Python (with a good docstring) Usually strong
TypeScript / JavaScript Often strong if you pass a clear description (or JSDoc, depending on helper)
Java (Method / functions(method)) Often weaker — prefer the long declaration when wording matters
Go Many setups still use an explicit declaration; check your SDK

Rule of thumb: short path for speed; long path when the model must not misread what the tool does.

What you still own

Even when the SDK runs the loop:

Still yours Why
The tool / skill functions The model cannot touch your files or APIs alone
A ceiling (max remote calls / steps) Stop runaway loops
Saying no to dangerous tools Guardrails stay in your code
Understanding the manual loop Debug when the helper misbehaves

If you only ever see the shortcut, a stuck agent is harder to fix. That is why the manual loop came first.

When the shortcut helps

  • Small demos and tutorials
  • One clear goal and a few safe tools
  • An SDK that documents max steps and history well

When to write the loop yourself

  • You need to approve a tool before it runs
  • You want custom logging, retries, or budgets per step
  • The SDK in your language does not offer a helper (or you do not trust it yet)

Names you will see

Companies and SDKs use different labels for the same idea:

You might read Meaning
Automatic function calling SDK runs tools and may loop for you
Tool runner / agent runner Helper that owns the loop
Max remote calls Step limit inside the helper

The idea does not change: someone must repeat until a final answer or a limit. Either that someone is your for loop, or the SDK.

One picture to keep

Word Meaning
Manual tool-call loop You write call → tool → call again
SDK-run loop The library repeats that for you inside one helper
Max remote calls The helper’s step limit
Docstring Short description inside a Python function (often used as the tool description on the short path)
Javadoc Documentation comment above a Java method — not available on a reflected Method at runtime

See it in Code

The Code panel uses the SDK-run path for the same “summarize notes.txt” job: your read_file function still runs on your machine, but you do not write the for loop. Python relies on the function + docstring; Java uses a method with automatic calling (description is thinner — compare with the long declaration in earlier labs). Go still shows an honest manual loop where the SDK has no full helper.

Next: when many tools / skills are available, and how the model picks among them.