Skip to content
toolnexusv0.27.0

API Reference — Python

Package toolnexus (PyPI, Python ≥ 3.11). See the combined API Reference for every symbol shown in eight-language synced tabs.

Toolkit

Section titled “Toolkit”
  • create_toolkit(...) -> Toolkit (async)
  • Keyword args: mcp_config, skills_dir, skills, skill_provider, skills_filter, skill_sample_limit, builtins, agents, extra_tools, wait_for.
  • Equivalents: createToolkit (js) · CreateToolkit (go) · Toolkit.create (java) · Toolkit.CreateAsync (c#) · Toolnexus.create_toolkit (elixir).

Skills

Section titled “Skills”
  • load_skills(dirs=None, *, skills=None, filter=None, sample_limit=0) -> SkillSource
  • list_skills(dirs=None, *, skills=None) -> SkillInventory — .skills, .skipped (SkillSkip.reason: missing-name · malformed-frontmatter · duplicate-name · unreadable).
  • SkillDef(name, content, description=None, resources=None, base=None)
  • skill_provider may be sync or async.
  • Equivalents: loadSkills / listSkills (js) · LoadSkillsWith / ListSkills (go) · SkillSource.loadWith / listSkills (java) · SkillSource.LoadWith / ListSkills (c#) · Toolnexus.Skill.load / Toolnexus.Skill.list (elixir).

MCP · Adapters · Client

Section titled “MCP · Adapters · Client”
  • load_mcp(config) -> McpSource (async)
  • to_openai(tk) · to_anthropic(tk) · to_gemini(tk)
  • create_client(...) -> Client → await client.ask(prompt, tk).

Tools you build — native, HTTP, built-ins

Section titled “Tools you build — native, HTTP, built-ins”
  • @tool / define_tool(fn, *, name?, description?, input_schema?) — schema inferred from type hints + docstring.
  • http_tool(*, name, description, method, url, headers?, query?, body?, result_mode?, timeout?) — timeout in seconds.
  • builtins toggle → ten built-ins: bash · read · write · edit · grep · glob · webfetch · question · apply_patch · todowrite.
  • Equivalents: defineTool / httpTool (js) · NativeTool / HTTPTool (go) · NativeTool.of / HttpTool.of (java) · NativeTool.Of / HttpTool.Of (c#) · Toolnexus.Native.define_tool / Toolnexus.Http.tool (elixir).

Sub-agents & teams

Section titled “Sub-agents & teams”
  • agent(name, *, does, uses?, soul?, soul_file?, team?, budget?, model?, wait_for?) -> Agent.
  • await agent.run(prompt, *, llm={...}, ...) -> TaskResult — .status, .text, .total_tokens, .runtime.
  • agent.as_tool(**rt_opts) -> Tool · compose_soul(dir) -> (soul, found) · Budget(...).
  • Equivalents: agents.agent / .run / .asTool / composeSoul (js) · agents.New (go) · Agents.agent (java/elixir) · new Agent (c#).

A2A — serve & remote agents

Section titled “A2A — serve & remote agents”
  • await tk.serve(addr, *, client, a2a: A2AConfig, on_task?, mcp?, on_call?) -> ServeHandle.
  • agent(card, *, headers?, timeout?, poll_every?) + create_toolkit(agents=[...]) / await tk.add_agent(card_url).
  • Equivalents: tk.serve / tk.addAgent (js) · Serve / AddAgent (go) · serve / addAgent (java) · ServeAsync / AddAgentAsync (c#) · Toolkit.serve / Toolkit.add_agent (elixir).

Suspension & the human loop

Section titled “Suspension & the human loop”
  • wait_for (toolkit option; callable (Request) -> Answer).
  • Request(id, kind, prompt, url?, data?, expiresAt?) · Answer(id, ok, data?, reason?).
  • pending(*, kind, prompt, url?, data?) · auth_required(url, prompt?) · pending_of(result).
  • Equivalents: waitFor / pending / authRequired / pendingOf (js) · WaitFor / Pending (go) · waitFor / ToolResult.pending (java) · WithWaitFor / ToolResult.Pending (c#) · wait_for / ToolResult.pending? (elixir).

Media generation

Section titled “Media generation”

Guide: Media generation · recipe: Generate images, video and speech · SPEC §7G.

  • load_media_style(path: str) -> dict — read one style JSON file.
  • create_media(styles: dict | list[dict], *, on_progress=None, http_transport: MediaTransport | None = None) -> Media — a verb resolves to the first style that declares it. on_progress({"verb", "jobId", "status"}) fires after every poll and may be sync or async. http_transport replaces the default UrllibMediaTransport; a MediaTransport has a blocking request(method, url, headers, body, timeout) -> (status, body_text) (run in a worker thread; timeout is the time left until the job deadline, and it must not send the style headers across a cross-origin redirect).
  • Verbs (all async, return MediaResult): image(prompt, *, width, height, aspect_ratio, seed, provider_options) · video(prompt, *, image, seconds, aspect_ratio, provider_options) · speech(text, *, voice, provider_options) · transcribe(audio, *, provider_options) · clone_voice(name, samples, *, provider_options) · talking(image, audio, *, provider_options). None arguments are not sent.
  • await media.generate(verb, args=None, provider_options=None) — the raw call; verb is the canonical name ("cloneVoice", not "clone_voice").
  • MediaResult(files: list[MediaFile], text, job_id, status) · MediaFile(type, mime_type, url); .to_dict() gives the canonical camelCase shape.
  • media.tools() -> list[Tool] (source "media"), or create_toolkit(media=media).
  • RunResult.files — list of dicts {type, mimeType, url, from, callId}, in call order; the same parts are on tool_calls[i]["parts"].
  • Errors: the function face raises MediaError (str(e) is the exact §7G message); a media tool never raises (is_error=True). Cancellation is asyncio’s: asyncio.CancelledError always propagates, from the function face and the tool face alike — it is never turned into a MediaError or a tool error.
  • Equivalents: createMedia (js) · CreateMedia (go) · Media.create (java) · Media.Create (c#) · Toolnexus.Media.new (elixir) · toolnexus.media/create-media (clojure) · create_media (rust).