Skip to content

AI Agents

StackSpot AI Agents are interactive AI assistants that can chat with users, maintain conversation context, and leverage knowledge sources to provide enriched responses.

Simple API

The Agent client provides a simple interface for chatting with AI agents:

from stkai import Agent, ChatRequest

agent = Agent(agent_id="my-assistant")
response = agent.chat(ChatRequest(user_prompt="What is SOLID?"))

if response.is_success():
    print(response.result)

Key Concepts

ChatRequest

Represents a message to send to the agent:

from stkai import ChatRequest

request = ChatRequest(
    user_prompt="Explain dependency injection",  # Required
    id="my-request-id",                          # Optional: auto-generated
    conversation_id="conv-123",                  # Optional: for multi-turn (or use UseConversation)
    use_conversation=True,                       # Enable conversation context
    use_knowledge_sources=True,                  # Use StackSpot knowledge
    return_knowledge_sources=True,               # Include KS IDs in response
    upload_ids=["upload-id-1", "upload-id-2"],   # Optional: file upload IDs (Enterprise only)
    metadata={"source": "cli"},                  # Custom metadata
)

ChatResponse

Contains the agent's response:

response = agent.chat(request)

if response.is_success():
    result = response.result             # Processed response (use this by default)
    raw = response.raw_result            # Raw message from API (if needed)
    tokens = response.tokens             # Token usage info
    conv_id = response.conversation_id   # For continuing conversation
    ks_ids = response.knowledge_sources  # Knowledge sources used

Response Status

Status Description
SUCCESS Response received successfully
ERROR Client-side error (HTTP, network, parsing)
TIMEOUT Request timed out

Features

Feature Description
Synchronous Chat Simple, blocking chat interface with automatic error handling
Streaming (Experimental) Real-time SSE streaming with chat_stream() for token-by-token output
Batch Execution Process multiple chat requests concurrently with chat_many()
Automatic Retry Automatic retry with exponential backoff for transient failures
Conversation Context Multi-turn conversations with automatic ID tracking via UseConversation
Knowledge Sources Enrich responses with your organization's knowledge bases
Token Tracking Track token usage for monitoring and cost management
File Upload Upload files as context for agent conversations (Enterprise only)
Result Handlers Customize response processing (JSON parsing, transformations)

Quick Example

from stkai import Agent, ChatRequest

# Create an Agent client
agent = Agent(agent_id="code-assistant")

# Send a message
response = agent.chat(
    request=ChatRequest(
        user_prompt="What are the SOLID principles?",
        use_knowledge_sources=True,
    )
)

if response.is_success():
    print(f"Agent: {response.result}")

    if response.tokens:
        print(f"Tokens used: {response.tokens.total}")
else:
    print(response.error_with_details())

Next Steps