Strumenti per LangChain e LangGraph

langchain-popnow dà agli agenti LangChain e LangGraph strumenti che creano immagini, video, musica e voce con i modelli PopNow, e strumenti che elencano i modelli, recuperano le attività e verificano il saldo API. Una sola chiave API copre tutti i modelli, da Nano Banana e Seedream fino a MiniMax H3, Kling, Suno e Gemini TTS.

Ogni chiamata a pagamento viene prima preventivata in USD. Uno strumento a pagamento chiamato senza max_usd restituisce solo il prezzo: non viene creato nulla e non viene addebitato nulla. Il pacchetto è open source con licenza MIT (GitHub) e si basa sull'SDK Python ufficiale.

In sintesi

Configurazione

pip install -U langchain-popnow

export POPNOW_API_KEY="sk-popnow-..."

from langchain_popnow import PopNowImageGeneration

tool = PopNowImageGeneration()

# 1. Quote: returns the price, starts nothing.
print(tool.invoke({"prompt": "A small red fox curled up in a teacup, soft morning light"}))
# {"status": "needs_confirmation", "model": "google/nano-banana-2.1/text-to-image", "cost_usd": "0.048", ...}

# 2. Approved: creates the task and waits for it.
print(tool.invoke({"prompt": "A small red fox curled up in a teacup, soft morning light", "max_usd": "0.048"}))
# {"status": "succeeded", "task_id": "...", "cost_usd": "0.048", "outputs": [{"url": "https://...", "uri": "popnow://g/.../0"}], ...}

Quando un agente chiama lo strumento con un ToolCall, lo strumento restituisce un ToolMessage il cui content è il riepilogo JSON qui sopra e il cui artifact è il record completo dell'attività o del preventivo su PopNow.

Strumenti

PopNowToolkit().get_tools() restituisce tutti e otto con un'unica configurazione condivisa.

Gli strumenti di generazione accettano i campi comuni (prompt, aspect_ratio, resolution, duration_seconds, voice_id e così via), un model facoltativo per scegliere un altro modello PopNow, e extra_input per qualsiasi campo che popnow_list_models elenca per quel modello. Gli ID dei modelli seguono lo schema <maker>/<model>/<task> descritto in Modelli.

Come funziona l'approvazione

Le attività PopNow sono asincrone: si preventiva, si crea al prezzo approvato e poi si attende il risultato. Gli strumenti seguono lo stesso flusso del server MCP per sviluppatori:

1. Preventivo. L'agente chiama uno strumento a pagamento senza max_usd. Lo strumento chiede a PopNow un preventivo e restituisce status: "needs_confirmation" con cost_usd. Non viene creato né trattenuto nulla.
2. Approvazione. L'agente mostra il prezzo all'utente. Dopo l'approvazione richiama lo strumento con gli stessi argomenti più max_usd uguale al cost_usd preventivato.
3. Esecuzione. Se il preventivo attuale rientra in max_usd, l'attività viene creata con quel preventivo bloccato e lo strumento attende il risultato. Se il prezzo è salito, lo strumento restituisce un nuovo needs_confirmation e non addebita nulla.

I risultati contengono link di download firmati, che scadono, e un URI popnow://g/<task>/<n> che non scade e può essere passato a un altro strumento PopNow, per esempio per animare un'immagine generata. Un video lungo può essere ancora in corso quando scade wait_timeout (predefinito 600 secondi): in quel caso lo strumento restituisce status: "running" con un task_id, e popnow_get_task recupera il risultato più tardi. Le attività fallite o scadute rilasciano la trattenuta e non costano nulla.

Limiti di spesa

Impostali su qualsiasi strumento a pagamento o su PopNowToolkit:

Si applicano anche i tetti di spesa e la lista di modelli consentiti della chiave API, impostati nella console API.

Uso con un agente LangChain

from langchain.agents import create_agent
from langchain_popnow import PopNowToolkit

tools = PopNowToolkit(max_usd_per_call="1.00").get_tools()

agent = create_agent(
    model="anthropic:claude-sonnet-4-6",
    tools=tools,
    system_prompt=(
        "You create media with PopNow tools. Paid tools return a price first: "
        "show it to the user and only call again with max_usd after they approve."
    ),
)

result = agent.invoke({"messages": [{"role": "user", "content": "Make a 9:16 clip of a vintage car on a coastal road"}]})
print(result["messages"][-1].content)

L'agente può funzionare con qualsiasi modello di chat supportato da LangChain, inclusi i modelli di chat di PopNow tramite l'endpoint compatibile con OpenAI https://api.popnow.ai/v1.

Uso con LangGraph

from langchain.chat_models import init_chat_model
from langgraph.prebuilt import create_react_agent
from langchain_popnow import PopNowToolkit

model = init_chat_model("anthropic:claude-sonnet-4-6")
agent = create_react_agent(model, PopNowToolkit(max_usd_per_call="1.00").get_tools())

for step in agent.stream(
    {"messages": [{"role": "user", "content": "Write a short lo-fi track for a cooking video and tell me the price first"}]},
    stream_mode="values",
):
    step["messages"][-1].pretty_print()

create_react_agent funziona ancora in LangGraph 1.x; i progetti nuovi possono usare langchain.agents.create_agent, come nell'esempio sopra. Per un vero passaggio di approvazione umana, combina gli strumenti con HumanInTheLoopMiddleware di LangChain o con un interrupt di LangGraph.

Altri esempi

Trova un modello e i suoi input

Elencare i modelli è gratis. Con model, lo strumento restituisce i campi di input e i prezzi di quel modello:

from langchain_popnow import PopNowListModels

PopNowListModels().invoke({"modality": "video", "search": "kling"})
PopNowListModels().invoke({"model": "kling/3.0/image-to-video"})

Anima un'immagine con un modello scelto

from langchain_popnow import PopNowVideoGeneration

PopNowVideoGeneration().invoke({
    "prompt": "Gentle waves, slow push-in",
    "image_url": "https://example.com/beach.jpg",
    "model": "kling/3.0/image-to-video",
    "duration_seconds": 5,
    "max_usd": "0.50",
})

Voci fuori campo senza approvare ogni riga

Una voce fuori campo costa una frazione di centesimo, quindi una pipeline può approvare da sola preventivi piccoli:

from langchain_popnow import PopNowSpeech

speech = PopNowSpeech(auto_approve_usd="0.02")
speech.invoke({"text": "Welcome back to the channel!", "voice_id": "Kore"})

Qualsiasi modello tramite ID

PopNowCreateTask invia l'input proprio di un modello, esattamente come in Attività:

from langchain_popnow import PopNowCreateTask

PopNowCreateTask().invoke({
    "model": "alibaba/z-image-turbo/text-to-image",
    "input": {"prompt": "A paper boat on a puddle, overcast street, photo", "aspect_ratio": "1:1"},
    "max_usd": "0.02",
})

Ogni strumento può anche essere eseguito in modo asincrono: await tool.ainvoke(...).

Prezzi

Elencare i modelli, leggere le attività e verificare il saldo sono gratis. Gli strumenti di generazione addebitano la tariffa in USD del modello al tuo saldo API: un'attività trattiene il prezzo preventivato quando viene accettata e salda l'addebito effettivo quando termina. Le attività fallite o scadute non costano nulla.

popnow_list_models restituisce le tariffe in USD di ogni modello. Il prezzo di ciascun modello è su Modelli e nella sua pagina; anche l'indice dei prezzi IA li elenca. Come funzionano preventivi, trattenute e rimborsi: Fatturazione e preventivi.

Errori comuni

L'elenco completo è in Errori.

Funziona con LangGraph?

Sì. Gli strumenti sono strumenti LangChain standard, quindi create_react_agent, ToolNode e i grafi LangGraph personalizzati possono chiamarli. Abbinali a un interrupt di LangGraph se una persona deve approvare ogni prezzo.

Un agente può spendere il mio saldo senza chiedere?

Non di default. Uno strumento a pagamento chiamato senza max_usd restituisce solo un preventivo. La spesa senza approvazione avviene solo se imposti auto_approve_usd, e continuano a valere max_usd_per_call e i tetti di spesa della chiave.

Quali modelli possono usare gli strumenti?

Qualsiasi modello di immagini, video o audio del catalogo. Gli strumenti di generazione hanno valori predefiniti sensati; passa model per sceglierne un altro, oppure usa PopNowCreateTask con qualsiasi ID di modello. popnow_list_models elenca gli ID dall'interno dell'agente.

Esiste una versione JavaScript?

Per TypeScript e JavaScript usa il provider Vercel AI SDK oppure l'SDK JavaScript.

Correlati