fruxon 0.5.16

The Fruxon SDK is a lightweight Python client for integrating with the Fruxon platform.

fruxon

Run, build, and orchestrate AI agents from your terminal — the official Python SDK and CLI for the Fruxon platform.

Install

pip install fruxon

Requires Python 3.10+.

30-second quickstart

fruxon login                 # opens a browser; stores the API key in your OS keychain
fruxon agents list           # see what's deployed in your org
fruxon run my-agent -p question="hello"
fruxon chat my-agent         # interactive multi-turn REPL

fruxon doctor will tell you if anything's misconfigured.

The CLI

Command	What it does
fruxon login	Browser-based sign-in. API key goes to your OS keychain (Keychain on macOS, Secret Service on Linux, Credential Manager on Windows).
fruxon whoami	Show the active key/org and where each value came from (flag, env, keychain, file).
fruxon logout	Forget stored credentials.
fruxon agents list	Browse every agent in your org. Use --output json for scripting, --output id for shell pipes.
fruxon agents get <id>	Inspect one agent — display name, deployed revision, tags, and the parameters it expects.
fruxon agents test <id> --file <def.json>	Run a draft flow definition against an existing agent without publishing it. Same output as run; exits non-zero on failure — a CI gate for agent changes.
fruxon integrations list/get/create/update/verify	Manage external integrations — the connections agents draw tools from. create/update/verify take a --file JSON body.
fruxon tools list/get/create/update/delete/test	Manage the tools inside an integration. Integration-scoped — every command takes <integration> as its first argument. test runs a tool with sample params before you wire it into an agent.
fruxon run <agent>	One-shot execution. Streams text by default; pass --output json or --no-stream for the full result envelope.
fruxon chat <agent>	Interactive REPL with session continuity.
fruxon trace <agent> <record-id>	Inspect a past execution — duration, cost, step-by-step trace.
fruxon doctor	Diagnose local setup (interpreter, SDK version, credentials, API reachability, auth).
fruxon config	Read/edit the persistent CLI config.

fruxon run — examples

fruxon run my-agent -p question="Hello" -p lang=en
fruxon run my-agent -p temp:=0.7 -p tags:='["a","b"]'   # ':=' for typed JSON
fruxon run my-agent -p prompt=@./prompt.md              # '@file' reads from disk
fruxon run my-agent --params ./params.json              # whole-object input
cat params.json | fruxon run my-agent --stdin
fruxon run my-agent --output json                       # full result envelope
fruxon run my-agent --revision 42                       # pin a specific revision

Agent mode

When CLAUDECODE=1, CI=1, or FRUXON_AGENT_MODE=1 is set, the CLI:

• defaults --output to json for run, agents get, agents list, doctor,
• suppresses banners and color chrome,
• emits a one-line JSON manifest on bare fruxon invocation describing auth state and next-step commands.

This makes the CLI ergonomic for LLM agents and CI pipelines without extra flags.

The Python client

from fruxon import FruxonClient

client = FruxonClient(api_key="...", org="acme-corp")

# One-shot
result = client.execute(
    "support-agent",
    parameters={"question": "How do I reset my password?"},
)
print(result.response)
print(f"{result.trace.duration}ms · ${result.trace.total_cost:.4f}")

# Multi-turn — thread the session ID into subsequent calls
followup = client.execute(
    "support-agent",
    parameters={"question": "Tell me more"},
    session_id=result.session_id,
)

# Streaming
for chunk in client.stream_text("support-agent", parameters={"question": "Hi"}):
    print(chunk, end="", flush=True)

# Lower-level: typed SSE events (text, tool_call, tool_result, done, …)
for event in client.stream("support-agent", parameters={"question": "Hi"}):
    ...

# Discovery
for agent in client.list_agents():
    print(agent.id, agent.current_revision)

params = client.get_agent_parameters("support-agent", revision=1)

# Test a draft flow without publishing it (same result shape as execute)
result = client.test("support-agent", {"flow": {...}, "baseRevision": 3, "parameters": {...}})
for event in client.stream_test("support-agent", {"flow": {...}}):
    ...

# Integrations & tools — the connections + capabilities agents are built from
for integ in client.list_integrations(types=["CUSTOM"]):
    print(integ.id, integ.type)
client.create_integration({"id": "github", "displayName": "GitHub", "configMetadata": {...}})
for tool in client.list_tools("github"):
    print(tool.id, tool.tool_type)
client.create_tool("github", {"id": "list_commits", "integrationId": "github", "descriptor": {...}})
client.test_tool("github", {"descriptor": {...}, "parameters": {"repo": "fruxon-sdk"}})

The client picks up FRUXON_API_KEY, FRUXON_ORG, and FRUXON_BASE_URL only if you read them yourself — the constructor takes explicit values. The CLI resolves them automatically (flags → env → stored config).

Credentials & storage

The CLI resolves auth in this order (first non-empty wins):

1. Explicit flags — --api-key / --org / --base-url
2. Environment — FRUXON_API_KEY / FRUXON_ORG / FRUXON_BASE_URL
3. Stored credentials (managed by fruxon login)

The stored layer is split:

• API key → OS keychain via keyring. Set FRUXON_NO_KEYRING=1 or let the keyring be unavailable to fall back to a 0600 JSON file.
• Non-secrets (org, base_url) → plain JSON under ~/.fruxon/credentials.

fruxon config list shows both sources side by side.

Environment variables

Var	Effect
FRUXON_API_KEY	Default API key.
FRUXON_ORG	Default organization.
FRUXON_BASE_URL	Override the API base URL (staging / self-hosted).
FRUXON_CONFIG_DIR	Override the credentials directory (default ~/.fruxon).
FRUXON_DASHBOARD_URL	Override where fruxon login points the browser.
FRUXON_AGENT_MODE=1	Optimize for AI-agent / script consumption (also auto-detected from CLAUDECODE=1 / CI=1).
FRUXON_NO_KEYRING=1	Force the JSON-file fallback for the API key.
FRUXON_NO_BANNER=1	Suppress all branding chrome.
FRUXON_NO_UPDATE_CHECK=1	Opt out of the "newer version available" notifier.
NO_COLOR=1	Standard convention — disables color output.

Docs

• Installation
• CLI reference
• Python client
• Auth & configuration

License

MIT — see LICENSE.