agentic-settle

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)

import os
from agentic_settle import SettleClient

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

receipt = client.settle(
    agent_id="gpt-4o",
    request_content="What is the capital of France?",
    result_content="Paris",
    target_wallet="0x0000000000000000000000000000000000000000",
)

print(receipt.status, receipt.chain_tx_hash)

Quickstart (asyncio)

import asyncio
from agentic_settle import AsyncSettleClient

async def main() -> None:
    client = AsyncSettleClient(api_key="...")
    receipt = await client.settle(
        agent_id="claude-3.5",
        request_content="...",
        result_content="...",
        target_wallet="0x...",
    )
    print(receipt)

asyncio.run(main())

Environment variables

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

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 SettleClient.verify in production, or pass a stub in tests.

from agentic_settle import VOP, Task, Criteria, RetryPolicy

vop  = VOP(verify_fn=client.verify)            # 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.verify).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.verify)
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.verify)
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