Hello World Example

This guide demonstrates creating your first conversation using the Amigo SDK in Python or TypeScript.

Prerequisites

Before You Begin

1. Installed the SDK in your project

2. Configured your credentials with valid API keys

3. Service ID from your Amigo dashboard

Quick Overview

Code Examples

Python

Here's a complete example that creates a conversation, sends a message, and handles the streaming response:

from amigo_sdk import AmigoClient
from amigo_sdk.models import (
    ConversationCreateConversationRequest,
    CreateConversationParametersQuery,
    InteractWithConversationParametersQuery,
)

def hello_world():
    # Initialize the client
    with AmigoClient(
        api_key="your-api-key",
        api_key_id="your-api-key-id",
        user_id="your-user-id",
        organization_id="your-org-id"
    ) as client:

        # Step 1: Create a conversation
        print("Creating conversation...")
        create_events = client.conversation.create_conversation(
            ConversationCreateConversationRequest(
                service_id="your-service-id",
                service_version_set_name="release"
            ),
            CreateConversationParametersQuery(response_format="text")
        )

        # Process creation events
        conversation_id = None
        for event in create_events:
            event_data = event.model_dump(mode="json")
            print(f"Create event: {event_data.get('type')}")

            if event_data.get("type") == "conversation-created":
                conversation_id = event_data.get("conversation_id")
                print(f"Conversation created: {conversation_id}")

            if event_data.get("type") == "interaction-complete":
                break

        if not conversation_id:
            raise RuntimeError("Failed to create conversation")

        # Step 2: Send a message
        print("\nSending message...")
        interaction_events = client.conversation.interact_with_conversation(
            conversation_id,
            InteractWithConversationParametersQuery(
                request_format="text",
                response_format="text"
            ),
            text_message="Hello! Can you help me get started with Amigo?"
        )

        # Process interaction events
        full_response = ""
        for event in interaction_events:
            event_data = event.model_dump(mode="json")

            if event_data.get("type") == "new-message":
                message_chunk = event_data.get("message", "")
                full_response += message_chunk
                print(message_chunk, end="", flush=True)

            elif event_data.get("type") == "interaction-complete":
                print(f"\nResponse complete!")
                break

        print(f"\nFull response: {full_response}")

        # Step 3: Finish the conversation
        print("\nFinishing conversation...")
        try:
            client.conversation.finish_conversation(conversation_id)
            print("Conversation finished successfully!")
        except Exception as e:
            print(f"Warning: {e}")

if __name__ == "__main__":
    hello_world()

TypeScript

Here's the equivalent example in TypeScript:

import { AmigoClient } from "@amigo-ai/sdk";

async function helloWorld(): Promise<void> {
  // Initialize the client
  const client = new AmigoClient({
    apiKey: "your-api-key",
    apiKeyId: "your-api-key-id",
    userId: "your-user-id",
    orgId: "your-org-id",
  });

  try {
    // Step 1: Create a conversation
    console.log("Creating conversation...");
    const createEvents = await client.conversations.createConversation(
      {
        service_id: "your-service-id",
        service_version_set_name: "release",
      },
      { response_format: "text" }
    );

    // Process creation events
    let conversationId: string | undefined;
    for await (const event of createEvents) {
      console.log(`Create event: ${event.type}`);

      if (event.type === "conversation-created") {
        conversationId = event.conversation_id;
        console.log(`Conversation created: ${conversationId}`);
      }

      if (event.type === "interaction-complete") {
        break;
      }
    }

    if (!conversationId) {
      throw new Error("Failed to create conversation");
    }

    // Step 2: Send a message
    console.log("\nSending message...");
    const interactionEvents =
      await client.conversations.interactWithConversation(
        conversationId,
        "Hello! Can you help me get started with Amigo?",
        { request_format: "text", response_format: "text" }
      );

    // Process interaction events
    let fullResponse = "";
    for await (const event of interactionEvents) {
      if (event.type === "new-message") {
        const messageChunk = event.message || "";
        fullResponse += messageChunk;
        process.stdout.write(messageChunk);
      } else if (event.type === "interaction-complete") {
        console.log("\nResponse complete!");
        break;
      }
    }

    console.log(`\nFull response: ${fullResponse}`);

    // Step 3: Finish the conversation
    console.log("\nFinishing conversation...");
    try {
      await client.conversations.finishConversation(conversationId);
      console.log("Conversation finished successfully!");
    } catch (error) {
      console.log(`Warning: ${error}`);
    }
  } catch (error) {
    console.error("Error:", error);
    process.exit(1);
  }
}

// Run the example
helloWorld();

Next Steps

Now that you've created your first conversation, explore:

• Error Handling — Handle errors and edge cases properly

• Conversations: Create — Agent-first, user-first, external-event patterns

• Conversations: Interact — Streaming responses and event handlers

• User Management — Managing users with the SDK