Skip to main content
Use the official @fetch-hive/sdk package when you want to send a message to an agent from Node.js or TypeScript. The SDK wraps the public POST /v1/agent/invoke endpoint, handles authentication, exposes streaming as an AsyncIterable, and supports multimodal inputs.

​
Installation

npm install @fetch-hive/sdk
# or
yarn add @fetch-hive/sdk
# or
pnpm add @fetch-hive/sdk
The SDK targets Node.js 18+ (uses the global fetch) and ships with TypeScript types.

​
Authentication

Set the FETCH_HIVE_API_KEY environment variable to your workspace API key: 
export FETCH_HIVE_API_KEY=fhk_...

import { FetchHive } from '@fetch-hive/sdk';

const client = new FetchHive();
Or pass the key explicitly: 
const client = new FetchHive({ apiKey: 'fhk_...' });
See API Keys for how to create and rotate keys.

​
Basic example

Send a message to an agent and read the final response: 
import { FetchHive } from '@fetch-hive/sdk';

const client = new FetchHive();

const reply = await client.invokeAgent({
  agent: 'AGENT_UUID',
  message: 'Summarize the latest AI infrastructure trends',
});

console.log(reply.response);
See the non-streaming response shape.

​
Method reference

FieldTypeRequiredDescription
agentstringYesThe agent ID
messagestringYesThe message you want to send
thread_idstringNoAn arbitrary string identifying a persistent conversation thread
messagesArray<{ role, content, image_urls? }>NoCaller-managed conversation history
image_urlsstring[]NoHTTPS image URLs attached to the current message for multimodal inputs
userstringNoOpaque caller identifier surfaced in User Tracking
metadataRecord<string, string | number | boolean | null>NoFlat caller-defined metadata for audit and log filtering. See Invoke metadata
The SDK injects streaming: false for invokeAgent. To stream, use invokeAgentStream (below).

​
Handling the response

const reply = await client.invokeAgent({
  agent: 'AGENT_UUID',
  message: 'Hello',
});

console.log(reply.response);     // final text
console.log(reply.model);        // model identifier
console.log(reply.usage);        // token usage breakdown
console.log(reply.request_id);   // use this to look up the run in Logs
console.log(reply.tool_calls);   // tool invocations made during the run

​
Streaming

Use invokeAgentStream to receive Server-Sent Events as they arrive. The method returns an AsyncIterable: 
for await (const chunk of client.invokeAgentStream({
  agent: 'AGENT_UUID',
  message: 'Summarize the latest AI infrastructure trends',
  thread_id: 'user-456-support-session',
})) {
  if (chunk.type === 'response') {
    process.stdout.write(chunk.response ?? '');
  } else if (chunk.type === 'tool') {
    console.log(`\n[Calling tool: ${chunk.tool}]`);
  } else if (chunk.type === 'usage') {
    console.log('\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.

​
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: 
await client.invokeAgent({
  agent: 'AGENT_UUID',
  message: 'What are the main AI infrastructure trends right now?',
  thread_id: 'user-456-support-session',
});

await client.invokeAgent({
  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: 
await client.invokeAgent({
  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 image_urls: 
const result = await client.invokeAgent({
  agent: 'vision-agent',
  message: 'Describe this image',
  image_urls: ['https://example.com/photo.jpg'],
});
console.log(result.response);
URLs must start with https://.

​
Configuration

OptionDefaultDescription
apiKeyprocess.env.FETCH_HIVE_API_KEYBearer token from the dashboard
baseURLhttps://api.fetchhive.com/v1Override the API base URL
const client = new FetchHive({
  apiKey: 'fhk_...',
  baseURL: 'https://api.fetchhive.com/v1',
});

​
Errors

Non-2xx responses throw an Error whose message includes the status code and response body: 
try {
  const reply = await client.invokeAgent({
    agent: 'AGENT_UUID',
    message: 'Hello',
  });
} catch (err) {
  console.error('Fetch Hive error:', err);
}
See Errors and Rate Limits for status code meanings.

​
Next steps