Python SDK for inference.sh agents and apps.
The Python SDK provides both sync and async clients for running apps and chatting with agents.
Installation
bash
1pip install inferenceshRunning Apps
Basic Usage
python
1from inferencesh import inference2 3client = inference(api_key="inf_your_key")4 5result = client.run({6 "app": "infsh/echo",7 "input": {"message": "Hello from Python!"}8})9 10print(result["output"])Streaming Progress
python
1for update in client.run({"app": "infsh/flux-schnell", "input": {...}}, stream=True):2 print(f"Status: {update['status']}")3 if update.get("logs"):4 print(update["logs"][-1])Fire and Forget
python
1task = client.run({"app": "infsh/slow-task", "input": {...}}, wait=False)2print(f"Task ID: {task['id']}")Agent SDK
Chat with AI agents programmatically.
Using an Existing Agent
Reference agents by namespace/name and version:
python
1from inferencesh import inference2 3client = inference(api_key="inf_your_key")4 5# Use an agent you created in the workspace6agent = client.agent("my-org/my-agent@abc123") # Format: namespace/name@version7 8response = agent.send_message("Hello!")9print(response)Creating Ad-Hoc Agents
Create agents on-the-fly without saving to workspace:
python
1from inferencesh import inference, AdHocAgentOptions, tool, string2 3client = inference(api_key="inf_your_key")4 5# Define tools6calculator = (7 tool("calculator")8 .describe("Performs math operations")9 .param("expression", string("Math expression"))10 .build()11)12 13# Create ad-hoc agent14agent = client.agent(AdHocAgentOptions(15 core_app_ref="infsh/claude-sonnet-4@latest",16 name="Math Assistant",17 system_prompt="You help with math. Use the calculator tool.",18 tools=[calculator],19))20 21response = agent.send_message("What is 42 * 17?")Streaming Responses
python
1def handle_message(msg):2 if msg.get("content"):3 print(msg["content"], end="", flush=True)4 5def handle_tool(call):6 print(f"\n[Tool: {call.name}]")7 # Execute tool and return result string8 result = execute_my_tool(call.name, call.args)9 agent.submit_tool_result(call.id, result)10 11 # For widget interactions, you can also pass action + form_data:12 # agent.submit_tool_result(call.id, {13 # "action": {"type": "confirm"},14 # "form_data": {"name": "John", "email": "[email protected]"}15 # })16 17response = agent.send_message(18 "Explain quantum computing",19 on_message=handle_message,20 on_tool_call=handle_tool,21)File Attachments
python
1# From file path2response = agent.send_message(3 "What's in this image?",4 files=[open("image.png", "rb").read()]5)6 7# From base648response = agent.send_message(9 "Analyze this",10 files=["data:image/png;base64,iVBORw0KGgo..."]11)Chat Management
python
1# Get current chat2chat = agent.get_chat()3print(f"Chat ID: {chat['id']}")4print(f"Messages: {len(chat['messages'])}")5 6# Stop generation7agent.stop_chat()8 9# Start fresh10agent.reset()Tool Builder
Define tools with the fluent API:
python
1from inferencesh import (2 tool, app_tool, agent_tool, webhook_tool, internal_tools,3 string, number, integer, boolean, enum_of, array, obj, optional4)5 6# Client tool (runs in your code)7search = (8 tool("search_files")9 .describe("Search for files")10 .param("pattern", string("Glob pattern"))11 .param("recursive", optional(boolean("Search subdirs")))12 .build()13)14 15# App tool (calls another inference app)16generate = (17 app_tool("generate", "infsh/flux-schnell@latest")18 .describe("Generate an image")19 .param("prompt", string("Image description"))20 .build()21)22 23# Agent tool (delegates to sub-agent)24researcher = (25 agent_tool("research", "my-org/researcher@v1")26 .describe("Research a topic")27 .param("topic", string("Topic"))28 .build()29)30 31# Webhook tool (calls external API)32notify = (33 webhook_tool("slack", "https://hooks.slack.com/...")34 .describe("Send Slack message")35 .secret("SLACK_SECRET")36 .param("message", string("Message"))37 .build()38)39 40# Internal tools config41internals = internal_tools().memory().plan().build()Async Support
python
1from inferencesh import async_inference2import asyncio3 4async def main():5 # Async app client6 client = async_inference(api_key="inf_...")7 result = await client.run({"app": "...", "input": {...}})8 9 # Async agent10 agent = client.agent("my-org/assistant@abc123")11 response = await agent.send_message("Hello!")12 13 # Async streaming14 async for msg in agent.stream_messages():15 print(msg)16 17asyncio.run(main())Error Handling
python
1from inferencesh import RequirementsNotMetException2 3try:4 result = client.run({"app": "my-app", "input": {...}})5except RequirementsNotMetException as e:6 print(f"Missing requirements: {e.errors}")7 for err in e.errors:8 print(f" - {err['type']}: {err['key']}")9except RuntimeError as e:10 print(f"Error: {e}")File Upload
python
1# Upload separately2file = client.upload_file("/path/to/image.png")3print(f"Uploaded: {file['uri']}")4 5# Use in app input6result = client.run({7 "app": "image-processor",8 "input": {"image": file["uri"]}9})10 11# Or auto-upload from paths12result = client.run({13 "app": "image-processor",14 "input": {"image": "/path/to/local/image.png"} # Auto-uploaded15})REST API (curl)
For simple integrations, you can use the REST API directly with streaming:
bash
1# Single call with streaming2curl -N -X POST \3 -H "Authorization: Bearer YOUR_API_KEY" \4 -H "Content-Type: application/json" \5 -d '{6 "agent": "my-org/assistant@abc123",7 "input": {"text": "Hello!", "role": "user"},8 "stream": true9 }' \10 https://api.inference.sh/agents/runThe -N flag disables curl's buffering so you see events in real-time.
Without streaming (returns JSON with chat_id for subsequent messages):
bash
1curl -X POST \2 -H "Authorization: Bearer YOUR_API_KEY" \3 -H "Content-Type: application/json" \4 -d '{5 "agent": "my-org/assistant@abc123",6 "input": {"text": "Hello!", "role": "user"}7 }' \8 https://api.inference.sh/agents/runWhat's Next?
- JavaScript SDK — JS/TS SDK reference
- Tool Builder — Full tool builder API
- REST API — Direct HTTP endpoints