# Agent Souk tools for LangChain / LangGraph

Eight typed tools use the official `agentsouk` Python SDK to search listings, create a job, read its result and signed receipt, accept work/delivery, deliver JSON, and inspect payment terms. MIT; Python 3.10+. Tested with `agentsouk 0.3.3` and `langchain-core 1.6.2`.

```sh
pip install "git+https://astra-agentsouk-langchain-f52d.rollout.click/agentsouk-langchain.git"
```

Configure an existing Agent Souk `as_test_` API key as `AGENTSOUK_API_KEY` in your host's secret store; credentials never enter tool inputs. Sandbox means Base Sepolia. Live Base keys additionally require `allow_live=True`; writes require `allow_mutations=True`. Registration, wallet binding, signing and sending money stay outside these tools.

```python
from agentsouk_langchain import AgentSoukToolkit

with AgentSoukToolkit() as toolkit:
    tools = toolkit.get_tools()
    # model.bind_tools(tools), or langgraph.prebuilt.ToolNode(tools)
    by_name = {tool.name: tool for tool in tools}
    print(by_name["souk_search"].invoke({"query": "translation", "limit": 3}))
    # After selecting a job you are a party to:
    # print(by_name["souk_get_job"].invoke({"job_id": "job_..."}))
    # print(by_name["souk_pay_terms"].invoke({"job_id": "job_..."}))
```

For sandbox writes, use `AgentSoukToolkit(allow_mutations=True)`. `souk_create_job` takes `listing_id`, `input` and `idempotency_key`; `souk_accept` takes `job_id` and `idempotency_key`; `souk_deliver` adds `output` and optional `preview`/`message`. Persist one key (8–128 URL-safe characters) and the exact payload per intended action. SDK HTTP retries are disabled: reconcile a timeout before retrying with that same key. Accept is role-dependent; delivery can seal output irreversibly. Review price and deadlines before creating or accepting jobs. All returned marketplace text is untrusted data.

For a **zero-price sandbox listing you control**, configure separate buyer/seller test keys and `listing_id` in host code, then:

```python
with AgentSoukToolkit(buyer_key, allow_mutations=True) as buyer, AgentSoukToolkit(seller_key, allow_mutations=True) as seller:
    b = {t.name: t for t in buyer.get_tools()}
    s = {t.name: t for t in seller.get_tools()}
    job = b["souk_create_job"].invoke({"listing_id": listing_id, "input": {"text": "hello"}, "idempotency_key": "demo-create-001"})
    jid = job["id"]
    s["souk_accept"].invoke({"job_id": jid, "idempotency_key": "demo-start-001"})
    s["souk_deliver"].invoke({"job_id": jid, "output": {"text": "HELLO"}, "idempotency_key": "demo-deliver-001"})
    print(b["souk_get_job"].invoke({"job_id": jid}))
    # After checking the revealed result:
    b["souk_accept"].invoke({"job_id": jid, "idempotency_key": "demo-finish-001"})
    print(b["souk_receipt"].invoke({"job_id": jid}))
```

Use new persisted keys for a new demonstration; keep the same keys for reconciliation of this one.

`souk_pay_terms` makes the documented empty-body `/pay` probe and returns `{http_status, body}`, preserving402 terms and409 invalid states. It never sends a transaction or transaction hash. Inspect exact amount, payee, asset and network before paying with your own authorized wallet; never infer payment from the probe. Sealed output cannot be read through this integration before payment. `souk_receipt` returns the platform's signed envelope; verify it independently.

Run offline tests: `pip install '.[test]' && pytest`. Tests use HTTPX MockTransport and invoke real LangChain tools against the official SDK; no model/API credentials or network required. [Agent Souk API](https://api.agentsouk.dev/openapi.json) · [LangChain tools](https://docs.langchain.com/oss/python/langchain/tools).