Template Agents

Use existing agents from your workspace.

Basic Usage

1from inferencesh import inference23client = inference(api_key="inf_your_key")45# Reference by namespace/name@version6agent = client.agent("my-team/support-agent@latest")78# Send a message9response = agent.send_message("Hello!")10print(response.text)

Agent Reference Formats

1# Latest version2namespace/agent-name@latest34# Specific version5namespace/agent-name@abc123

Per-chat context

Agents declare context fields in their config; you pass values when you start a chat, the same as the CLI's --context key=value. The agent writes {{context.NAME}} in tool call arguments and the server substitutes the value when the tool runs; call tool URL and header templates use the same placeholders. Values stay out of the system prompt unless the field sets in_prompt: true. A declared default fills a key you do not send. required is not enforced: a chat without the value still runs. See Context.

1agent = client.agent(2    "my-team/pricing-agent@latest",3    context={"version_id": "v1", "app_id": "app_123"},4)56response = agent.send_message("Show me the current pricing")

Context is set once per chat and cannot change, so every tool call in that conversation uses the same values.

→ Context in call tools · Adding tools · Create chat REST API

File attachments

Send images, documents, or other files with a message. The SDK uploads them and attaches FileRef URIs to the user message. In React, AgentChatProvider / useAgentActions().sendMessage() post the refs as attachments on POST /chats/{id}/messages from @inferencesh/sdk ≥ v0.22.1; with an earlier release the files upload but the agent does not see them.

1# Paths, bytes, or data URIs — uploaded automatically2response = agent.send_message(3    "What's in this image?",4    files=[open("photo.png", "rb").read()],5)67# upload_file returns a FileRef (uri, filename, content_type) for logging or custom flows8ref = agent.upload_file(open("doc.pdf", "rb").read(), filename="doc.pdf")9response = agent.send_message("Summarize this PDF", files=[open("doc.pdf", "rb").read()])

→ Files API · Python SDK file attachments · JavaScript SDK file attachments

Multi-turn Conversations

State is maintained automatically:

1agent = client.agent("my-team/support-agent@latest")23response1 = agent.send_message("What's my account status?")4print(response1.text)56response2 = agent.send_message("Can you explain that more?")7print(response2.text)  # Has context from previous message

Reset Conversation

Start a new conversation. reset() clears the SDK's chat ID so the next sendMessage creates a fresh chat.

When a chat is created, the platform pins the resolved agent version on it (agent_version_id). Continuing the same chat always runs that version — redeploying the agent or changing @latest in your code does not upgrade an open conversation. Call reset() (or start a new chat via REST without chat_id) to pick up the latest definition, including updated tool schemas.

1agent.reset()23response = agent.send_message("Start fresh!")

Get Chat History

Message history is not included in GET /chats/:id or agent.getChat(). Fetch messages with the REST List chat messages endpoint (GET /chats/:id/messages). When streaming, chat_messages events deliver updates in real time.

With AgentChatProvider / useAgentChat, the SDK loads messages automatically when connecting or polling (metadata from GET /chats/:id, then GET /chats/:id/messages when the response has no chat_messages). The initial load uses the server default page size (50 newest messages) — not the full transcript. Hook state (chat.chat_messages) stays populated without extra calls; stream events append new messages during an active run.

Scroll-back pagination (v0.6.41+): when hasOlderMessages is true, call loadOlderMessages() from useAgentActions() to fetch the next page. The SDK prepends deduplicated messages and updates the internal cursor. Trigger this when the user scrolls near the top of your message list:

1const { messages } = useAgentChat();2const { loadOlderMessages, hasOlderMessages } = useAgentActions();34// e.g. on scroll near top5if (hasOlderMessages) {6  await loadOlderMessages(); // returns true when more pages remain7}

For imperative or non-React UIs, paginate with cursor or pass limit=-1 via the REST API (examples below).

1# REST: list messages (newest first by default)2messages = client.http.request(3    "get", f"/chats/{chat_id}/messages", params={"limit": -1}4).data["items"]56for message in messages:7    print(f"{message['role']}: {message['content']}")

Stop Active Response

1# Start streaming2for chunk in agent.send_message("Tell me a story", stream=True):3    if should_stop:4        agent.stop()5        break6    print(chunk.text)