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.
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.
python -m pip install https://localmark.ai/static/downloads/localmark_client-0.4.1-py3-none-any.whl2. 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.
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.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.
{
"q": "extract text from PDF documents",
"checked_within_hours": 24,
"a2a_response_within_hours": 24,
"tls_reachable": true,
"limit": 3
}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.jsonWhat 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.