examples

Realistic agent workflows

Five short patterns that show up over and over in agent code. Pick a tab to switch language.

1. Search and iterate hits

Walk results, stop early on a score threshold.

from argand import ArgandClient

with ArgandClient() as client:
    response = client.search("retrieval-augmented generation", limit=20)
    for hit in response.results:
        if hit.score < 0.4:
            break  # tail of the result list — stop early
        print(f"[{hit.score:.2f}] {hit.title}\n  {hit.url}")

2. Programming-vertical search

Ask for code-flavored results; print snippets where present.

from argand import ArgandClient

with ArgandClient() as client:
    response = client.search(
        "how to spawn a tokio task with shutdown handling in rust",
        limit=10,
    )
    for hit in response.results:
        # programming-vertical results often expose snippet text
        # already extracted from the source code/doc.
        print(hit.title, "->", hit.url)
        if hit.snippet:
            print("  ", hit.snippet[:160])

3. Lucky redirect

One-shot URL retrieval — useful for "take me to the docs" intents. The returned URL is the /yw/ referral wrapper; Argand sends traffic to source sites instead of capturing it.

from argand import ArgandClient

with ArgandClient() as client:
    location = client.lucky("tokio docs")
    print("redirect target:", location)
    # location is a /yw/ wrapper URL — Argand sends traffic TO source sites.

4. Self-hosted base URL

Point any SDK at your own deployment by setting base_url / baseUrl. Same surface, different origin.

from argand import ArgandClient

# Point at your own argand gateway — same SDK, no other change.
with ArgandClient(base_url="https://argand.example.org") as client:
    response = client.search("self-hosted", limit=5)
    print(response.total_results)

5. Error handling with retries

The SDK already retries 5xx and 429 with exponential backoff and Retry-After honoring. Once you see RateLimitError / ServerError escape, the SDK has given up — treat it as terminal.

from argand import (
    ArgandClient,
    RetryPolicy,
    RateLimitError,
    ServerError,
)

retry = RetryPolicy(max_attempts=5, base_delay_s=0.25, max_delay_s=8.0)
with ArgandClient(retry=retry) as client:
    try:
        response = client.search("flaky network test")
    except RateLimitError as e:
        # SDK already retried up to max_attempts. Treat as terminal.
        print(f"hard rate-limited; backoff exhausted: retry_after={e.retry_after}s")
    except ServerError as e:
        print(f"server unhappy after retries: {e}")