Skip to main content

agentic-settle

Python client SDK for the AgenticSettle Pro settlement engine.

A deliberately thin wrapper over the REST API so AI-native applications can spend less than 30 seconds wiring up on-chain settlement for their agents.

pip install agentic-settle

Quickstart (synchronous)

One-shot verification (no escrow):

import os
from agentic_settle import SettleClient

client = SettleClient(
    base_url="https://app.agenticsettle.io",
    api_key=os.environ["AGENTIC_SETTLE_API_KEY"],
)

verdict = client.verify(
    request_content="What is the capital of France?",
    result_content="Paris",
)

print(verdict)   # a dict: report_id, score, tier, verdict, fail_codes, evidence_hash, ...

verify returns a plain dict, so read fields with verdict["score"], not verdict.score. A very short answer such as "Paris" can legitimately come back as a FAIL (for example MIN_LENGTH): the verifier judges the output, not the question.

Free vs paid keys. A key from POST /v2/signup is a free key: it works for verify and the read-only verification endpoints only. Everything below that touches escrow (register_agent, register_token, purchase_tokens, create_task, ...) returns 403 with a free key. Paid keys are issued by the operator (see the pilot onboarding guide); the paid flow also needs a registered agent and token and a funded customer balance before create_task can succeed.

Paid flow (escrow + verification): create_task -> deliver -> accept_report (the agent and the customer each accept the report) -> decide. The legacy v1 settle() / get_status() call routes that current servers do not serve (they return 404) and are deprecated.

Quickstart (asyncio)

import asyncio
from agentic_settle import AsyncSettleClient

async def main() -> None:
    client = AsyncSettleClient(api_key="...")
    verdict = await client.verify(
        request_content="...",
        result_content="...",
    )
    print(verdict)

asyncio.run(main())

Environment variables

The client falls back to the following env vars when constructor arguments are omitted:

Variable Purpose
AGENTIC_SETTLE_BASE_URL Base URL of the settlement service
AGENTIC_SETTLE_API_KEY API key (preferred)

The client does not read any other key variable. When base_url is omitted it defaults to http://localhost:8000 (a local development server).

VOP Layer 0 — embed verification in the agent loop

Instead of bolting verification on after the fact, the VOP façade embeds it inside the agent execution loop: one call drives verification → settlement decision → feedback, and (when you pass an agent callable) the FAIL → retry → refund ladder. It is dependency-free and deterministic over an injectable verify_fn — wire verify_fn to client.as_verify_fn() in production (SettleClient.verify itself is keyword-only, so it cannot be passed directly), or pass a stub in tests.

from agentic_settle import VOP, Task, Criteria, RetryPolicy

vop  = VOP(verify_fn=client.as_verify_fn())            # verify_fn(req, res, sla) -> verdict dict
task = Task(
    id="t1",
    description="Draft a customer outreach email",
    criteria=Criteria(sla={"min_words": 50}),
)

result = my_agent(task)                          # your code produces the result
out = vop.verify(task=task, result=result,
                 retry_policy=RetryPolicy(max_retries=2))

if out.status == "PASS":
    ...                                          # out.decision == "SETTLE"
elif out.status == "PARTIAL":
    print(out.feedback.summary)                  # out.decision == "PARTIAL_SETTLE"
else:
    ...                                          # RETRY / REFUND / ESCALATE / FAIL_FINAL

A2A (agent-to-agent) chains

TaskChain runs a pipeline of agents where each step is VOP-verified before the chain proceeds. The weakest verified step bounds the chain payout.

from agentic_settle import VOP, TaskChain, ChainStep, Criteria

chain = TaskChain(steps=[
    ChainStep(id="research", description="Gather sources", agent=research_agent,
              criteria=Criteria(sla={"min_sources": 3})),
    ChainStep(id="draft",    description="Write the draft", agent=writing_agent,
              criteria=Criteria(sla={"min_words": 200})),
])
chain_result = VOP(verify_fn=client.as_verify_fn()).execute_chain(chain)
print(chain_result.status, chain_result.settlement_bps)

Framework integrations (optional extras)

VOP ships as optional-import plugins for popular agent frameworks. The core install pulls neither LangChain nor AutoGen — install an extra only when you wire the matching adapter into a live run:

pip install "agentic-settle[langchain]"   # VOPCallback
pip install "agentic-settle[autogen]"     # with_vop / VOPVerifiedAgent
pip install "agentic-settle[all]"         # both
# LangChain — verify an LLM/chain's final output as it is produced
from langchain_openai import ChatOpenAI
from agentic_settle.vop import VOP, Task, Criteria
from agentic_settle.integrations import VOPCallback

vop = VOP(verify_fn=client.as_verify_fn())
cb  = VOPCallback(vop=vop, task=Task(id="t1", description=prompt,
                                     criteria=Criteria(sla={"min_words": 50})))
llm = ChatOpenAI(callbacks=[cb])
llm.invoke(prompt)
print(cb.result.decision)                  # SETTLE | REFUND | ...
# AutoGen — VOP-verify each generated reply
from agentic_settle.vop import VOP, Task, Criteria
from agentic_settle.integrations import with_vop

vop     = VOP(verify_fn=client.as_verify_fn())
guarded = with_vop(my_reply_fn, vop=vop,
                   task=Task(id="t1", description=prompt, criteria=Criteria(sla={...})))
reply, result = guarded(messages)          # result is a VOPResult

Both modules import without their framework installed (they degrade to a plain base / plain callable), so they stay unit-testable with a stub verify_fn.

What's in the box

  • SettleClient — synchronous client (httpx under the hood)
  • AsyncSettleClient — asyncio variant for high-throughput agents
  • SettleRequest — request payload model (pydantic v2)
  • SettleReceipt — response receipt model (pydantic v2)
  • VOP / Task / Criteria / RetryPolicy / VOPResult — Layer 0 verification façade
  • TaskChain / ChainStep — A2A chain settlement
  • integrations.VOPCallback (LangChain), integrations.with_vop / VOPVerifiedAgent (AutoGen)

Type annotations ship with py.typed.

License

Apache-2.0

Metadata

Release files for agentic-settle 1.0.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for agentic-settle 1.0.2
File Size Uploaded Provenance Actions
agentic_settle-1.0.2.tar.gz 28.0 kB Without provenance Details for agentic_settle-1.0.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for agentic-settle 1.0.2
File Interpreter ABI Platform Actions
agentic_settle-1.0.2-py3-none-any.whl Python 3 none any Details for agentic_settle-1.0.2-py3-none-any.whl

Total release size: 60.0 kB

Release files / agentic_settle-1.0.2.tar.gz

Download URL agentic_settle-1.0.2.tar.gz
Size 28.0 kB
Tags Source
SHA-256 checksum
How to use checksums
8d82aad71444891f41dd6bf419765b52978278d2614cd76905b03ca152b0e4e1
BLAKE2b-256 checksum
How to use checksums
0b3eb87b5a0ffb343106208eb4c98e1df54cbbc9b0d5a3f5d0a67de7d3f5e994
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.14.4

Release files / agentic_settle-1.0.2-py3-none-any.whl

Download URL agentic_settle-1.0.2-py3-none-any.whl
Size 32.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
d4dbc8e157023370da76c7d3bb63ab485cff02a4b82eb58badf0dde95e4c201e
BLAKE2b-256 checksum
How to use checksums
bb2351e4fa666e01e5b9719de1407d02cad2868770fe11f13927634c80fd19d5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.14.4

Security for agentic-settle 1.0.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page