iwantfyi-crewai 0.1.0

CrewAI tools for iwant.fyi -- reference implementation of the iwant.fyi demand-side protocol v1.0. Lets any CrewAI agent express structured purchase intent and receive matched supply.

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:

Tool	Spec	Description
demand_create_want	§8.1	Create a Want and run matching
demand_search	§8.1	Ephemeral matching, no persistence
demand_get_want	§8.1	Retrieve a Want by ID
demand_record_outcome	§8.1	Report viewed/clicked/purchased outcome
demand_list_verticals	§8.2	Discover supported verticals
demand_list_constraints	§8.2	Discover constraint vocabulary
demand_health	§8.2	Liveness + readiness

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