Agents

Agents are configurable AI assistants. Each agent has an LLM provider, a system prompt, and a set of enabled tools. Key properties:

Property	Description
`namespace` / `name`	Unique identifier (e.g., `support/ticket-agent`)
`llm_provider_id`	LLM provider to use (null = system default)
`model`	Model override (null = provider’s default)
`system_prompt`	Jinja2 template for the system message
`temperature`	Sampling temperature (default: 0.7)
`max_tokens`	Max token limit for responses
`input_schema`	JSON Schema for validating chat input variables
`output_schema`	JSON Schema for validating agent output
`initial_messages`	Few-shot example messages
`enabled_functions`	Functions available as tools. Supports wildcards: `namespace/` or `/*`.
`function_parameters`	Default parameter values per function (supports Jinja2)
`enabled_agents`	Other agents callable as sub-agents. Supports wildcards.
`enabled_skills`	Skills available to the agent. Supports wildcards.
`enabled_queries`	Database queries available as tools. Supports wildcards.
`query_parameters`	Default query parameter values
`enabled_collections`	File collections the agent can access. Plain string (readonly) or `{"collection": "namespace/name", "access": "readonly\|readwrite"}`. Supports wildcards. Readwrite enables write/edit/delete file tools.
`enabled_stores`	Stores the agent can access. List of `{"store": "namespace/name", "access": "readonly"}` or `{"store": "namespace/name", "access": "readwrite"}`
`enabled_connectors`	Connectors available as tools. List of `{"connector": "namespace/name", "operations": [...], "parameters": {"op_name": {"param": "value"}}}`. Parameters support Jinja2 templates and are locked (hidden from LLM).
`hooks`	Message lifecycle hooks. `{"on_user_message": [...], "on_assistant_message": [...]}`
`system_tools`	Platform capabilities. List of strings or config objects. See System Tools.
`icon`	Icon reference (see Icons)

Wildcard patterns for enabled_* fields:

Pattern	Matches
`namespace/name`	Exact resource
`namespace/*`	All active resources in that namespace
`/`	All active resources

enabledFunctions:
  - sales/*          # all functions in the sales namespace
  - shared/utils     # one specific function
enabledQueries:
  - "*/*"            # all queries (quote wildcards in YAML)
enabledCollections:
  - collection: "docs/*"
    access: readonly

Wildcards expand at tool discovery time. The resolved tools are validated against user permissions at execution time. Message hooks: Functions that run before/after agent messages. Each hook has:

function: reference to a function (namespace/name)
async: if true, fire-and-forget (no impact on latency)
on_timeout: block (stop pipeline) or passthrough (continue) — sync hooks only

Hook functions receive

{"message": {"role": "...", "content": "..."}, "chat_id": "...", "agent": {"namespace": "...", "name": "..."}, "user_id": "..."}

and can return:

{"content": "..."} to mutate the message
{"block": true, "reply": "..."} to stop the pipeline
null to pass through unchanged

agents:
  - name: my-agent
    hooks:
      onUserMessage:
        - function: default/guardrail
          async: false
          onTimeout: block
      onAssistantMessage:
        - function: default/pii-filter
          async: false
          onTimeout: passthrough

Management endpoints:

POST   /api/v1/agents                       # Create agent
GET    /api/v1/agents                       # List agents
GET    /api/v1/agents/{namespace}/{name}    # Get agent
PUT    /api/v1/agents/{namespace}/{name}    # Update agent
DELETE /api/v1/agents/{namespace}/{name}    # Delete agent

Runtime endpoints (chats):

POST   /agents/{namespace}/{name}/invoke             # Invoke (sync request/response)
POST   /agents/{namespace}/{name}/chats              # Create chat
GET    /chats                                        # List user's chats
GET    /chats/{id}                                   # Get chat with messages
PUT    /chats/{id}                                   # Update chat
DELETE /chats/{id}                                   # Delete chat
POST   /chats/{id}/messages                          # Send message
POST   /chats/{id}/messages/stream                   # Send message (SSE streaming)
GET    /chats/{id}/stream/{channel_id}               # Reconnect to active stream
POST   /chats/{id}/approve-tool/{tool_call_id}       # Approve/reject a tool call

Invoke endpoint: A synchronous request/response alternative to the two-step chat flow. Intended for integrations (Slack, Telegram, webhooks) that need a simple call-and-response.

# Simple invoke
curl -X POST https://yourdomain.com/agents/support/helper/invoke \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message": "What is the status of order #123?"}'
# → {"reply": "Your order is on its way...", "chat_id": "c_abc123"}

# With session key (conversation continuity)
curl -X POST https://yourdomain.com/agents/support/helper/invoke \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message": "Follow up on that", "session_key": "slack:U09ABC123"}'
# → Same chat_id as previous call with this session_key

session_key: Maps an external identifier (Slack channel, Telegram chat, WhatsApp number) to a persistent Sinas chat. One chat per (agent_id, session_key) pair.
reset: true: Archives the existing session and starts a new conversation.
input: Agent input variables, only used when creating a new chat.
Streams internally, returns assembled reply as a single JSON payload.

How chat works:

Create a chat linked to an agent (optionally with input variables validated against input_schema)
Send a message — Sinas builds the conversation context with the system prompt, preloaded skills, message history, and available tools
The LLM generates a response, possibly calling tools
If tools are called, Sinas executes them (in parallel where possible) and sends results back to the LLM for a follow-up response
The final response is streamed to the client via Server-Sent Events

Ephemeral chats can be created with a TTL by passing expires_in (seconds) when creating the chat. Expired chats are automatically hard-deleted (with all messages) by a scheduled cleanup job:

# Create an ephemeral chat that expires in 1 hour
curl -X POST https://yourdomain.com/agents/default/default/chats \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"expires_in": 3600}'

Chat archiving — Chats can be archived via PUT /chats/{id} with {"archived": true}. Archived chats are hidden from the default list but can be included with ?include_archived=true. Agent-to-agent calls go through the Redis queue so sub-agents run in separate workers, avoiding recursive blocking. Results stream back via Redis Streams. Function parameter defaults pre-fill values when an agent calls a function. Supports Jinja2 templates referencing the agent’s input variables:

{
  "email/send_email": {
    "sender": "{{company_email}}",
    "priority": "high"
  }
}

Getting Started

Platform

Build

Storage

Triggers

Configure

Admin