Activepieces

Invoke Zihin agents from Activepieces with the Zihin piece. The Invoke Agent action calls a hosted agent (over @zihin/agent-client) and returns the result.

info

See the current npm release versions. @zihin/piece-zihin is published on npm; the Activepieces marketplace listing is in progress. Self-hosted instances can install the piece from npm today (Settings → Pieces → Install).

Connect your account

Add the Zihin piece and create a connection:

Field	Description
API Key	zhn_live_* / zhn_test_* from Settings → API Keys (the tenant is embedded).
Base URL	Defaults to https://llm.zihin.ai. Override only for a private deployment.
Allow custom base URL	Off by default. Enable only to target a base URL outside the Zihin domain whitelist — your key is sent there.
Allow HTTP / localhost	Development only.

The connection is validated by listing your agents.

Action: Invoke Agent

Field	Description
Agent	The agent to invoke — loaded from your tenant (dropdown).
Message	The input sent to the agent.
Session ID	Reuse to continue a conversation; the output returns the session ID.
Temperature / Max Tokens / Timeout	Optional call controls. Temperature and Max Tokens are not applied by the /stream endpoint (configure them in the agent's llm_config); Timeout only shortens the turn deadline. See Agent invocation contract.
Client Message ID (Idempotency)	Optional UUID that makes retries safe. See below.
Include Raw Events	Include the raw SSE events in the output (debugging).

Output: content, contentSource, sessionId, blocks, usage, model, sources, iterations, executionTimeMs, outcome, finishReason, truncated, executionId, clientMessageId, idempotentReplay, gated, acceptedFields, ignoredFields.

• clientMessageId echoes the Client Message ID property; idempotentReplay is true when the backend replayed the stored answer of an earlier call with the same ID.
• A turn refused by the model provider (REFUSED), that hit the context limit (CONTEXT_LIMIT), timed out or failed is an error of the step — the backend's neutral sentence is never returned as the answer.

Client Message ID (Idempotency)

An optional UUID that makes retries safe. Sending the same UUID with the same message again never runs a finished turn twice: while the first run is still in flight you get a retryable session busy error; once it finished, the stored answer is replayed (idempotentReplay: true).

Use a new UUID per message, never a fixed value — a fixed UUID with a fixed message would return the same stored answer for 24 hours. It is best effort: only a finished turn is protected (a turn that was cut off, timed out or failed runs again), and the backend skips the check if its cache is unavailable. It requires a Zihin backend from October 2026 or later; otherwise the step fails instead of silently running without the guarantee. See the contract.

Example

[Trigger] → [Zihin · Invoke Agent] → [Next step]

1. Create a Zihin connection (above).
2. Add Zihin → Invoke Agent, pick the Agent, and map the Message from the trigger.
3. Use content downstream; pass sessionId back on the next run for continuity.

tip

Activepieces pieces declare their dependencies, so the Zihin piece consumes @zihin/agent-client directly — the same governed invocation as every other connector.

What changed in 0.5.0

Upgrading from 0.4.x (the piece now uses @zihin/agent-client 0.7.0):

• Steps that used to succeed can now fail. A turn refused by the model provider (REFUSED) or that hit the context limit (CONTEXT_LIMIT) is an error with that code, not an output with the backend's neutral sentence.
• SESSION_BUSY (another turn still running in the session) is a retryable error now; before it was a generic server error.
• New optional property Client Message ID (Idempotency).
• Output gains clientMessageId and idempotentReplay.