Flare AI Kit — palveron-adk-tool

palveron-adk-tool is the explicit-governance companion to palveron-google-adk. It exposes Palveron as a Google ADK FunctionTool so a flare-ai-kit agent can verify content on demand — before signing a SparkDEX swap, before posting to X, before forwarding an A2A message.

flare-ai-kit ships agents inside Intel TDX with remote attestation. That guarantees code integrity — the binary that ran is the binary you signed off on. It does not constrain what the agent says or does inside that trusted boundary. PII in a tool result, a swap above the per-call budget, a social post that crosses the financial-advice line — those are governance concerns. Together: verifiable + governed Flare agent.

Architecture

palveron-adk-tool plugs into flare-ai-kit's Google-ADK runtime as the seventh engine — the Governance Engine that the alpha SDK leaves out.

┌────────────────────────────────────────────────────────────────┐
│                   flare-ai-kit Agent (TDX)                     │
│                                                                │
│   ┌──────────────────────────────────────────────────────────┐ │
│   │   Google ADK LlmAgent                                    │ │
│   │   tools = [palveron_governance, ftso, sparkdex, ...]     │ │
│   └────────────┬─────────────────────────────────────────────┘ │
│                │                                               │
│                ▼  agent decides when to verify                 │
│   ┌──────────────────────────────────────────────────────────┐ │
│   │   PalveronGovernanceTool                                 │ │
│   └────────────┬─────────────────────────────────────────────┘ │
└────────────────┼───────────────────────────────────────────────┘
                 │  POST /api/v1/verify  (sub-millisecond)
                 ▼
       ┌──────────────────────────┐
       │  Palveron Gateway        │  decision + trace_id
       └────────────┬─────────────┘
                    │ 30–60 s batch
                    ▼
       ┌──────────────────────────┐
       │  Palveron Notary on      │
       │  Coston2 / Flare mainnet │
       └──────────────────────────┘

Two planes, one API. The control plane returns ALLOW / BLOCK / MODIFY / REQUIRE_APPROVAL / FLAGGED synchronously. The attestation plane batches traces into a Merkle tree and anchors the root on the Flare blockchain — no impact on the agent loop.

Installation

pip install palveron-adk-tool

Python 3.10+. Depends on palveron-sdk, google-adk, and pydantic.

Quickstart

import os
from google.adk.agents import LlmAgent
from palveron_adk_tool import PalveronGovernanceTool, GovernanceConfig

governance_tool = PalveronGovernanceTool(GovernanceConfig(
    api_key=os.environ["PALVERON_API_KEY"],
    agent_id="flare-defi-agent-001",
    metadata={"source": "flare-ai-kit", "protocol": "sparkdex"},
))

agent = LlmAgent(
    name="governed_flare_agent",
    model="gemini-2.0-flash",
    tools=[governance_tool.as_tool(), ftso_get_price, sparkdex_build_tx],
    instruction=(
        "Before any DeFi action, call palveron_governance(content=...) "
        "and only proceed if decision is 'ALLOW' or 'FLAGGED'."
    ),
)

The agent now has a palveron_governance tool it can call during reasoning. Each call returns a typed GovernanceResult with a decision, a trace_id, and an attestation_status that flips from PENDING to ANCHORED once the trace lands on Coston2 / Flare mainnet.

palveron-adk-tool vs. palveron-google-adk

The two packages are complementary — one agent can use both.

Use the callback adapter for the safety floor; add this tool when the model itself should be aware that a check happened (e.g. to decide whether to ask the user for confirmation after a FLAGGED decision).

Flare-Specific Use Cases

DeFi agent on SparkDEX / OpenOcean

A non-custodial trading flow with three governance hops — pre-quote PII check on the user request, pre-trade budget enforcement on the draft transaction, post-trade redaction on the receipt before it returns to the chat. Wallet addresses and memo PII never leak into the LLM context window.

governance_tool = PalveronGovernanceTool(GovernanceConfig(
    api_key=os.environ["PALVERON_API_KEY"],
    agent_id="defi-trading-agent-001",
    metadata={"source": "flare-ai-kit", "engine": "ecosystem", "protocol": "sparkdex"},
    fail_open=False,  # DeFi in regulated jurisdictions: never fail-open silently
))

Policy bundle: PII detector on memo text and wallet addresses, budget cap (swap_notional_usd <= 5_000 per call, <= 25_000 per 24 h), asset allowlist (FLR, SGB, WFLR, USDC, USDT, WETH, WBTC), optional jurisdiction rule.

Social agent on X / Telegram / Farcaster

flare-ai-kit's Social Engine connects to X, Telegram, Farcaster, and Slack. Two governance failure modes you have to prevent before the post goes out: toxicity / harassment, and unlicensed financial advice. Drafts that hit the disclaimer policy come back as MODIFY with a regulator-friendly version; drafts that fail safety come back as BLOCK with a trace_id for the human review queue.

governance_tool = PalveronGovernanceTool(GovernanceConfig(
    api_key=os.environ["PALVERON_API_KEY"],
    agent_id="social-agent-x",
    metadata={"source": "flare-ai-kit", "engine": "social", "channel": "x.com"},
    fail_open=False,  # Public channel: better to skip the post than to leak
))

RAG agent over Flare Developer Hub

A RAG agent backed by Qdrant + the Flare Developer Hub knowledge base has a less obvious leak surface: the retrieved documents. Public docs are safe by definition, but if the index also contains internal runbooks or partner agreements, the retrieval step can pull PII into the prompt without anyone noticing. The agent calls palveron_governance on the retrieved chunks; PII gets redacted to <EMAIL> / <WALLET> before the LLM sees it.

FDC agent — governing which data sources are allowed

An agent that uses Flare Data Connector attestations (EVMTransaction, Web2Json, Payment, XRPPayment, …) talks to external verifiers and the DA Layer. Governance restricts which attestation types and source URLs the agent may request, and blocks requests whose headers or body carry credentials before they reach the verifier round.

governance_tool = PalveronGovernanceTool(GovernanceConfig(
    api_key=os.environ["PALVERON_API_KEY"],
    agent_id="fdc-agent-001",
    metadata={"source": "flare-ai-kit", "engine": "ecosystem", "protocol": "fdc"},
))

GovernanceConfig

The config is a frozen Pydantic model — once built, it cannot be mutated; create a new tool instance to change behaviour.

GovernanceResult

Two convenience properties:

• result.allowed — True when the agent should proceed (covers ALLOW and FLAGGED).
• result.blocked — True when the agent must stop (covers BLOCK and REQUIRE_APPROVAL).

Decision mapping

Gateway responses are normalised into the five-value action set:

Blockchain Attestation

Each Palveron trace is hashed, batched into a Merkle tree every 30–60 seconds, and anchored to Coston2 (testnet) or Flare mainnet through the Palveron Notary contract. The control plane stays sub-millisecond; the attestation plane provides the long-term, non-repudiable audit anchor.

result = governance_tool.verify("draft tweet about FLR/USD price action")
print(result.trace_id)             # "tr_abc123"
print(result.attestation_status)   # "PENDING" → "ANCHORED" within 60 s

To verify a trace independently after anchoring:

1. Reconstruct the leaf as keccak256(content_hash).
2. Walk the proof returned by GET /api/v1/traces/{trace_id} to recover the Merkle root.
3. Read the matching getRoot(batchId) view on the Palveron Notary contract on Coston2 and compare.

Look up the anchor transaction on the Coston2 explorer: coston2.testnet.flarescan.com. Mainnet anchoring is identical; only the explorer URL differs.

EU AI Act and DORA for Flare Agents

Flare-deployed agents that handle financial workflows or address EU users sit inside two regulatory regimes:

• EU AI Act (Regulation (EU) 2024/1689). Obligations for general-purpose AI models took effect 2 August 2025; high-risk-system obligations apply 2 August 2026. Article 14 requires effective human oversight — REQUIRE_APPROVAL decisions route to a review queue. Article 50 requires transparency to natural persons — automatic disclaimer policies on social-agent drafts cover this. Article 12 requires record-keeping — every trace is anchored on Coston2 / Flare mainnet.
• DORA (Regulation (EU) 2022/2554). Applicable to financial entities since 17 January 2025. Article 8 (ICT risk management) and Article 28 (third-party ICT risk) are the load-bearing articles for any flare-ai-kit DeFi or FAssets agent operated by a regulated entity. For DORA-scoped agents, set fail_open=False and use a regional Palveron deployment.

Policy results carry framework IDs so an audit bundle can be generated by framework_id instead of by policy_id. The Compliance Hub maps Palveron policies to twelve frameworks total: EU AI Act, DORA, GDPR, NIST AI RMF, ISO/IEC 42001, ISO/IEC 23894, SOC 2 Type II, HIPAA, PCI DSS, MAS TRM, MAS FEAT, UK PRA SS1/23.

Example Agents

The palveron-adk-tool repository ships three runnable examples that mirror the use cases above:

• examples/governed_flare_agent.py — minimal showcase: FTSO block-latency price quote → governance check → user-facing message. Run as a script to see the flow without spinning up Gemini.
• examples/defi_trading_agent.py — three-hop SparkDEX swap flow (pre-quote PII, pre-trade budget, post-trade receipt redaction). Mock FTSO + SparkDEX tools so the file is self-contained.
• examples/social_agent.py — X / Telegram posting with toxicity check and financial-advice disclaimer policy. Demonstrates the MODIFY → post-modified-content pattern.

Each example imports cleanly without google-adk installed, so unit tests and IDE introspection work on machines that do not have the full Gemini stack.

Source Code

Open source (MIT): github.com/palveron/palveron-adk-tool · PyPI.

A companion Agent Skill for Claude Code / Cursor / Codex is published in the flare-ai-skills marketplace as palveron-governance.

Next Steps

• Google ADK callback adapter — automatic governance on every model and tool call.
• Create your own policies — budget caps, PII detectors, jurisdiction rules.
• Multimodal governance — OCR / ASR / frame-sampling for image, audio, and video parts.
• Flare AI Kit on GitHub · Flare Developer Hub.