iwantfyi-crewai

CrewAI tools for iwant.fyi — the reference implementation of the iwant.fyi demand-side protocol v1.0.

iwant.fyi demand-side protocol is an open standard for how AI agents express structured purchase intent on behalf of users, receive matched supply across multiple sources, and report outcomes back. This package wraps iwant.fyi as a set of CrewAI BaseTool subclasses that any CrewAI agent or crew can use.

Install

pip install iwantfyi-crewai

Quick start

from iwantfyi_crewai import get_iwantfyi_crewai_tools
from crewai import Agent, Crew, Task

tools = get_iwantfyi_crewai_tools(api_key="iwant_ak_...")  # get one at https://iwant.fyi

shopper = Agent(
    role="Personal Shopping Assistant",
    goal="Find products matching the user's needs across multiple sources.",
    backstory="You have access to iwant.fyi which searches multiple merchants in one call.",
    tools=tools,
)

task = Task(
    description="Find me a 1/4-inch drive torque wrench under $150 in Brooklyn",
    agent=shopper,
    expected_output="Top 3 matches with prices and source merchants.",
)

crew = Crew(agents=[shopper], tasks=[task])
result = crew.kickoff()

What you get

Seven CrewAI BaseTool subclasses, one per iwant.fyi demand-side protocol v1.0 §8 tool:

Each tool uses a Pydantic v2 args schema; CrewAI will validate user inputs before invoking the underlying iwant.fyi API.

Direct client (no CrewAI)

from iwantfyi_crewai import IwantClient

with IwantClient(api_key="iwant_ak_...") as client:
    health = client.health()
    print(health["status"])

    response = client.create_want(
        title='Torque wrench, 1/4" drive, 25-100 ft-lb',
        price_cents=15000,
        vertical="tools",
    )
    print(f"Want {response['want']['id']} -> {response['matches']['match_count']} matches")

Picking individual tools

If you only need a subset:

from iwantfyi_crewai import CreateWantTool, RecordOutcomeTool, IwantClient

client = IwantClient(api_key="iwant_ak_...")
agent = Agent(
    role="...",
    goal="...",
    tools=[CreateWantTool(client=client), RecordOutcomeTool(client=client)],
)

Transports

MCP over HTTP is the default. The REST fallback (§9 of the spec) is available:

tools = get_iwantfyi_crewai_tools(api_key="...", transport="http")

Outcome events

Outcome events feed match-quality learning and (eventually) revenue-share attribution:

client.record_outcome(want_id=w_id, match_id=m_id, event="clicked")
client.record_outcome(want_id=w_id, match_id=m_id, event="purchased", value_cents=12500)

Idempotent server-side; replays are no-ops.

Errors

Typed exceptions from iwantfyi_crewai.errors:

from iwantfyi_crewai import IwantError, UnauthorizedError, ValidationError, RateLimitedError

Specification

Full iwant.fyi demand-side protocol v1.0 spec: iwant.fyi/protocol/v1

The protocol is open (Apache 2.0). iwant.fyi is the reference implementation; anyone may build their own.

License

Apache 2.0