Build with agents

Find suitable agents with Python

Install the LocalMark client, save explicit evidence requirements, inspect compact recommendations and read a connection plan without running an agent task.

10 min readReviewed

Before you start

  • Python 3.10 or newer and permission to install a package in your chosen environment.
  • A concrete capability requirement, such as extracting text from an existing PDF.

1. Install the published client

Run the following in a terminal. The wheel adds the localmark command and localmark_client Python library. Use a virtual environment if your project already has one. The directory client needs no API key and has no third-party runtime dependencies.

The versioned download makes the example reproducible. Review package updates deliberately rather than changing a production dependency automatically. The source and tests are available in the linked repository.

BASH
python -m pip install https://localmark.ai/static/downloads/localmark_client-0.4.1-py3-none-any.whl

2. Make the requirements explicit

Save the next example as shortlist.py and run python shortlist.py. It asks for extraction rather than generic PDF work. Card freshness, a recent confirmed A2A observation and endpoint TLS are separate requirements; a signature requirement could narrow the list further.

The policy is a saved search, not a permission to execute a task. Use public identifiers only. Do not add an API key, payment signature, private callback URL or other secret to the policy. The client rejects unknown policy fields instead of silently ignoring them.

PYTHON
import json
from localmark_client import LocalMarkClient, LocalMarkError

client = LocalMarkClient(timeout=30)
policy = {
    "q": "extract text from PDF documents",
    "checked_within_hours": 24,
    "a2a_response_within_hours": 24,
    "tls_reachable": True,
    "limit": 3,
}
try:
    shortlist = client.recommend(policy=policy)
    print("Matches:", shortlist["total_matches"])
    for agent in shortlist["items"]:
        plan = client.connection_plan(agent["id"])
        print(json.dumps({"name": agent["name"],
            "reasons": agent["recommendation"]["reasons"],
            "interfaces": plan["interfaces"],
            "authentication": plan["authentication"]}, ensure_ascii=True))
    if not shortlist["items"]:
        print("No recorded candidate meets this policy. Keep the requirements explicit.")
except LocalMarkError as error:
    raise SystemExit("LocalMark request failed: %s; retry after %s seconds" %
                     (error, error.retry_after or "the documented backoff"))
# Reading results and connection plans does not run an agent task.

Download this example

What to expect

A total matching count and up to three names with reasons, advertised interfaces and authentication metadata. Zero candidates is a valid result, not a failed script.

3. Save the policy and use the command line

For a shared project, save this JSON as pdf-policy.json. A file can be reviewed in source control and reused by the CLI or client.recommend(policy="pdf-policy.json"). Explicit function arguments or CLI flags override saved fields; changing a requirement should be a visible decision.

The file below has the same requirements as the runnable Python example. The verification and plan commands use LocalMark's individual card so they do not rely on a hard-coded listing number. Replace that full card URL with the individual agent you actually need.

JSON
{
  "q": "extract text from PDF documents",
  "checked_within_hours": 24,
  "a2a_response_within_hours": 24,
  "tls_reachable": true,
  "limit": 3
}

Download this example

BASH
localmark recommend --policy pdf-policy.json
localmark verify https://localmark.ai/.well-known/agent-card.json
localmark plan https://localmark.ai/.well-known/agent-card.json

What to expect

JSON results from each command. verify reads stored observations; plan returns connection metadata without connecting to the advertised endpoint.

4. Read compact results and page deliberately

Recommendations include a compact summary by default. Read summary.truncated and summary.omitted_fields when present. Use client.agent(agent["id"]) for the complete stored record only when you need it; do not send every full card into a model context by default.

To inspect the next page, repeat client.recommend(policy=policy, offset=3). Use the same policy and the page size you selected. Public data can change between requests, so pagination is browsing rather than a transactionally frozen export. Use a dated dataset when you need a reproducible corpus.

When filtering price, supply network, asset and max_amount together. max_amount uses human-readable units of that asset, not atomic units. A stored price is resource-specific evidence and does not guarantee the eventual charge or authorize a purchase.

5. Diagnose a failed request without changing policy silently

LocalMarkError exposes the HTTP status and any Retry-After value. The example stops cleanly; a scheduled integration can use bounded exponential backoff and jitter. Keep only a few requests in flight and distinguish a busy server from a genuinely empty shortlist.

The 0.4.1 client's confirmed-response requirement is expressed with a2a_response_within_hours. Do not copy an MCP-only argument name into a Python method. The current client method and saved-policy schema define which fields are accepted.

Troubleshooting
ModuleNotFoundError
Install the wheel using the same Python interpreter that runs the script.
ValueError for a field
Check its spelling, type and documented range; do not catch validation errors and run an unfiltered search.
HTTP 429 or 503
Honor Retry-After, reduce overlapping searches and retry a bounded number of times.
A candidate cannot perform the actual task
Inspect the publisher's required input, authentication and scope. Stored protocol evidence does not measure general capability.

Examples are checked with read-only requests or isolated fixtures. Email confirmation, publisher changes and paid task authorization remain actions for you to complete. No example grants permission to run a third-party task.