Run with Python SDK

Use the official fetch-hive-sdk package when you want to send a message to an agent from Python. The SDK wraps the public POST /v1/agent/invoke endpoint, handles authentication, supports streaming and multimodal inputs, and exposes both synchronous and asyncio variants.

Installation

pip install fetch-hive-sdk

The SDK requires Python 3.9+ and uses httpx under the hood.

Authentication

Set the FETCH_HIVE_API_KEY environment variable to your workspace API key (the SDK reads it automatically):

export FETCH_HIVE_API_KEY=fhk_...

from fetch_hive_sdk import FetchHive

client = FetchHive()

Or pass the key explicitly:

client = FetchHive(api_key="fhk_...")

See API Keys for how to create and rotate keys.

Basic example

Send a message to an agent and read the final response:

from fetch_hive_sdk import FetchHive

client = FetchHive()

reply = client.invoke_agent(
    agent="AGENT_UUID",
    message="Summarize the latest AI infrastructure trends",
)

print(reply["response"])

See the non-streaming response shape.

Method reference

Argument	Type	Required	Description
`agent`	`str`	Yes	The agent ID
`message`	`str`	Yes	The message you want to send
`thread_id`	`str`	No	An arbitrary string identifying a persistent conversation thread. Fetch Hive creates the thread on first use and resumes it on subsequent calls.
`messages`	`list[dict]`	No	Caller-managed conversation history. Each item: `{"role": "user" \| "assistant" \| "system", "content": str}`.
`user`	`str`	No	Opaque caller identifier surfaced in User Tracking
`metadata`	`dict[str, str \| int \| float \| bool \| None]`	No	Flat caller-defined metadata for audit and log filtering. See Invoke metadata
`tool_approval`	`"policy" \| "auto_approve"`	No	Omit it, or send `"policy"`, to follow saved rules. `"auto_approve"` applies to this call only when the API key is allowed to auto-approve actions.

The SDK injects streaming: false for invoke_agent. To stream, use invoke_agent_stream (below).

Handling the response

reply = client.invoke_agent(agent="AGENT_UUID", message="Hello")

print(reply["response"])      # final text
print(reply["model"])         # model identifier
print(reply["usage"])         # token usage breakdown
print(reply["request_id"])    # use this to look up the run in Logs
print(reply.get("tool_calls"))  # tool invocations made during the run

Streaming

Use invoke_agent_stream to receive Server-Sent Events as they arrive. The method returns a generator that yields parsed event dicts:

for chunk in client.invoke_agent_stream(
    agent="AGENT_UUID",
    message="Summarize the latest AI infrastructure trends",
    thread_id="user-456-support-session",
):
    if chunk.get("type") == "response":
        print(chunk.get("response", ""), end="", flush=True)
    elif chunk.get("type") == "tool":
        print(f"\n[Calling tool: {chunk.get('tool')}]")
    elif chunk.get("type") == "usage":
        print("\n\nUsage:", chunk["usage"])

The stream yields the same event types documented in Invoke Agent → Response: summary (when auto-summarization fires), reasoning, response, tool, a final usage event, or an error event if the provider fails mid-stream.

Async streaming

For asyncio applications, use ainvoke_agent_stream. It has the same arguments but returns an async iterator:

import asyncio
from fetch_hive_sdk import FetchHive

async def main():
    client = FetchHive()
    async for chunk in client.ainvoke_agent_stream(
        agent="AGENT_UUID",
        message="Hello",
        thread_id="user-456-support-session",
    ):
        if chunk.get("type") == "response":
            print(chunk.get("response", ""), end="", flush=True)

asyncio.run(main())

Multi-turn conversations

Persistent threads

Pass any string as thread_id and Fetch Hive will create the thread on the first call and resume it on subsequent calls with the same value:

client.invoke_agent(
    agent="AGENT_UUID",
    message="What are the main AI infrastructure trends right now?",
    thread_id="user-456-support-session",
)

client.invoke_agent(
    agent="AGENT_UUID",
    message="Which of those trends have the most enterprise adoption?",
    thread_id="user-456-support-session",
)

Stateless history

Manage state yourself by passing the previous turns in messages. Fetch Hive uses the supplied history for context but does not persist it:

client.invoke_agent(
    agent="AGENT_UUID",
    message="Which of those trends have the most enterprise adoption?",
    messages=[
        {"role": "user", "content": "What are the main AI infrastructure trends right now?"},
        {"role": "assistant", "content": "Teams are focusing on evals, tool routing, and observability."},
    ],
)

Multimodal inputs

Attach images to the current message with attachments:

result = client.invoke_agent(
    agent="vision-agent",
    message="Describe this image",
    attachments=["https://example.com/photo.jpg"],
)
print(result["response"])

URLs must start with https://.

Configuration

Option	Default	Description
`api_key`	`FETCH_HIVE_API_KEY` env var	Bearer token from the dashboard
`base_url`	`https://api.fetchhive.com/v1`	Override the API base URL
`timeout`	`120`	Request timeout in seconds

client = FetchHive(
    api_key="fhk_...",
    base_url="https://api.fetchhive.com/v1",
    timeout=120,
)

Errors

Non-2xx responses raise an httpx.HTTPStatusError with the status code and response body:

import httpx

try:
    reply = client.invoke_agent(agent="AGENT_UUID", message="Hello")
except httpx.HTTPStatusError as exc:
    print("Fetch Hive returned", exc.response.status_code, exc.response.text)

See Errors and Rate Limits for status code meanings.

Next steps

Run with API - The same flow with cURL
Run with Node.js SDK
Run with Ruby SDK
Run with PHP SDK
Invoke Agent - Full endpoint reference

Tool approvals

When a tool needs approval, the invoke response has status: "awaiting_approval" and pending_tool_approvals. Decide with decide_tool_action_approval. decision is "allow_once" or "deny". List pending approvals with list_tool_action_approvals, or fetch one with get_tool_action_approval. always_allow is only available in the dashboard. An API key call resumes on the server after the decision. Poll the run or use the webhook. Do not send decided_tool_approvals. A workspace owner or admin can allow this API key to auto-approve actions in Settings → API keys. Pass tool_approval as "auto_approve" on invoke_agent, invoke_agent_stream, or invoke_workflow. That applies to this call only. Omit the field, or pass "policy", to follow workspace rules and any saved auto-approve switch. Destructive actions still ask. Deny rules still block the action. See Tool approvals.

Getting Started

Live Chat

Prompts

Workflows

Hive Agents

Agents

Knowledge Bases

Your Workspace

Monitoring

User Tracking

MCP Gateway

Resources

Installation

Authentication

Basic example

Method reference

Handling the response

Streaming

Async streaming

Multi-turn conversations

Persistent threads

Stateless history

Multimodal inputs

Configuration

Errors

Links

Next steps

Tool approvals

​Installation

​Authentication

​Basic example

​Method reference

​Handling the response

​Streaming

​Async streaming

​Multi-turn conversations

​Persistent threads

​Stateless history

​Multimodal inputs

​Configuration

​Errors

​Links

​Next steps

​Tool approvals

Installation

Authentication

Basic example

Method reference

Handling the response

Streaming

Async streaming

Multi-turn conversations

Persistent threads

Stateless history

Multimodal inputs

Configuration

Errors

Links

Next steps

Tool approvals