Hello World: Your First Maitento Agent

This tutorial walks you through creating your first AI agent in Maitento and running a simple interaction. By the end, you will have a working agent that responds to prompts.

What You Will Learn

• How to create an AI agent using Shell, SDK, and API
• How to set up a OneShot interaction
• How to run the interaction and retrieve the response

Prerequisites

Before starting, ensure you have:

• A Maitento account with API access
• Your API key (found in your account settings)
• For SDK examples: .NET 8.0 or later installed
• For API examples: curl or any HTTP client

Step 1: Create Your First Agent

An Agent is an AI entity configured with a specific AI model and system prompt. Think of it as defining a persona for the AI to assume when responding.

Option A: Using the Shell

The Maitento Shell provides the quickest way to create an agent interactively.

# First, list available AI models to find one to use
> ai-model-list

# Create a simple greeting agent
> agent-create hello-world-agent \
    --ai-model-id 550e8400-e29b-41d4-a716-446655440001 \
    --system-prompt "You are a friendly assistant. When someone says hello, respond with a warm greeting and a fun fact about the day." \
    --summary "A friendly agent that greets users warmly"

Agent 'hello-world-agent' created (a1b2c3d4-e5f6-7890-abcd-ef1234567890)

Verify your agent was created:

> agent-get hello-world-agent --namespace default

Name: hello-world-agent
ID: a1b2c3d4-e5f6-7890-abcd-ef1234567890
Version: 1
AI Model: Claude Sonnet 4.5
System Prompt: You are a friendly assistant...

Option B: Using the C# SDK

For programmatic agent creation, use the Maitento SDK:

using Maitento.Sdk;
using Maitento.Entities.Database;

// Initialize the client with your API key
await using IMaitentoClient client = MaitentoClient.Create("your-api-key");

// Create the agent
Agent helloAgent = await client.Agents.CreateAsync(
    namespaceName: "default",
    name: "hello-world-agent",
    aiModelId: Guid.Parse("550e8400-e29b-41d4-a716-446655440001"),
    systemPrompt: @"You are a friendly assistant.
When someone says hello, respond with a warm greeting and a fun fact about the day.",
    summaryForOtherAgents: "A friendly agent that greets users warmly"
);

Console.WriteLine($"Created agent: {helloAgent.Name}");
Console.WriteLine($"Agent ID: {helloAgent.Id}");
Console.WriteLine($"Version: {helloAgent.Versions[0].Version}");

Complete console application example:

// Program.cs
using Maitento.Sdk;
using Maitento.Entities.Database;

// Replace with your actual API key
const string apiKey = "your-api-key";

// Replace with an actual AI model ID from your tenant
Guid aiModelId = Guid.Parse("550e8400-e29b-41d4-a716-446655440001");

await using IMaitentoClient client = MaitentoClient.Create(apiKey);

try
{
    Agent agent = await client.Agents.CreateAsync(
        namespaceName: "default",
        name: "hello-world-agent",
        aiModelId: aiModelId,
        systemPrompt: @"You are a friendly assistant.
When someone says hello, respond with a warm greeting and a fun fact about the day.",
        summaryForOtherAgents: "A friendly agent that greets users warmly"
    );

    Console.WriteLine("Agent created successfully!");
    Console.WriteLine($"  Name: {agent.Name}");
    Console.WriteLine($"  ID: {agent.Id}");
}
catch (Exception ex)
{
    Console.WriteLine($"Error: {ex.Message}");
}

Option C: Using the HTTP API

Make a direct HTTP request to the Maitento API:

curl -X POST "https://api.maitento.com/namespaces/default/agents" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key" \
  -d '{
    "name": "hello-world-agent",
    "aiModelId": "550e8400-e29b-41d4-a716-446655440001",
    "systemPrompt": "You are a friendly assistant. When someone says hello, respond with a warm greeting and a fun fact about the day.",
    "summaryForOtherAgents": "A friendly agent that greets users warmly",
    "externalOperationReferences": []
  }'

Response:

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "hello-world-agent",
  "tenantId": "...",
  "namespaceId": "...",
  "dateCreated": "2024-01-15T10:30:00Z",
  "dateUpdated": "2024-01-15T10:30:00Z",
  "versions": [
    {
      "version": 1,
      "date": "2024-01-15T10:30:00Z",
      "isDisabled": false,
      "aiModelId": "550e8400-e29b-41d4-a716-446655440001",
      "systemPrompt": "You are a friendly assistant...",
      "summaryForOtherAgents": "A friendly agent that greets users warmly",
      "externalOperationReferences": []
    }
  ]
}

Step 2: Create a OneShot Interaction

An Interaction defines how agents process tasks. A OneShot interaction is the simplest type: one agent, one task, one response.

Option A: Using the Shell

# Create a OneShot interaction using the agent we created
> interaction-create-one-shot hello-interaction \
    --agent hello-world-agent \
    --prompt "{{message}}" \
    --input-message "The greeting message to respond to" \
    --namespace default

Interaction 'hello-interaction' created (b2c3d4e5-f6a7-8901-bcde-f12345678901)

Option B: Using the C# SDK

using Maitento.Sdk;
using Maitento.Entities.Interactions;

await using IMaitentoClient client = MaitentoClient.Create("your-api-key");

// Reference the agent we created (use the actual ID from Step 1)
Guid agentId = Guid.Parse("a1b2c3d4-e5f6-7890-abcd-ef1234567890");

// Create the agent binding for the interaction
var agentBinding = new InteractionAgentBinding(
    agent: new VersionReference(agentId, version: 1),
    name: "Greeter",
    externalOperationsMcp: Array.Empty<McpExternalOperationBinding>(),
    externalOperationsOpenApi: Array.Empty<OpenApiExternalOperationBinding>()
);

// Define the input parameter
var promptInputs = new[]
{
    new PromptInput(
        name: "message",
        description: "The greeting message to respond to",
        dataType: InteractionInputType.String,
        isRequired: true
    )
};

// Create the OneShot interaction
OneShotInteraction interaction = await client.Interactions.CreateOneShotAsync(
    namespaceName: "default",
    name: "hello-interaction",
    prompt: "{{message}}",
    solutionSchema: null,
    systemPromptMode: InteractionSystemPromptMode.AppendToDefault,
    systemPrompts: Array.Empty<string>(),
    durationWarningToAi: null,
    durationAutoTermination: TimeSpan.FromMinutes(5),
    externalOperationsMcp: Array.Empty<McpExternalOperationBinding>(),
    externalOperationsOpenApi: Array.Empty<OpenApiExternalOperationBinding>(),
    promptInputs: promptInputs,
    connectorBindingInputs: Array.Empty<ConnectorBindingInput>(),
    connectorAuthenticationSecretInputs: Array.Empty<ConnectorAuthenticationSecretInput>(),
    agent: agentBinding
);

Console.WriteLine($"Created interaction: {interaction.Name}");
Console.WriteLine($"Interaction ID: {interaction.Id}");

Option C: Using the HTTP API

curl -X POST "https://api.maitento.com/namespaces/default/interactions/one-shot" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key" \
  -d '{
    "name": "hello-interaction",
    "prompt": "{{message}}",
    "solutionSchema": null,
    "systemPromptMode": "AppendToDefault",
    "systemPrompts": [],
    "durationWarningToAi": null,
    "durationAutoTermination": "00:05:00",
    "externalOperationsMcp": [],
    "externalOperationsOpenApi": [],
    "promptInputs": [
      {
        "name": "message",
        "description": "The greeting message to respond to",
        "dataType": "String",
        "isRequired": true
      }
    ],
    "connectorBindingInputs": [],
    "connectorAuthenticationSecretInputs": [],
    "agent": {
      "name": "Greeter",
      "agent": {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "version": 1
      },
      "externalOperationsMcp": [],
      "externalOperationsOpenApi": []
    }
  }'

Step 3: Run the Interaction and Get the Response

Now let’s run our interaction and see the agent respond!

Option A: Using the Shell

The easiest way to run an interaction is with interaction-run, which starts the interaction and waits for completion:

> interaction-run hello-interaction \
    --namespace default \
    --input-message "Hello! How are you today?" \
    --stream

Starting interaction process...
Process ID: c3d4e5f6-a7b8-9012-cdef-123456789012

[Greeter]: Hello there! What a wonderful day to connect!
I hope you're doing fantastically well. Here's a fun fact for you:
Did you know that January 15th marks the anniversary of Wikipedia's launch in 2001?
It started as a small project and now contains over 60 million articles!
Is there anything I can help you with today?

Process completed successfully.

Alternative: Start without waiting

# Start the interaction (non-blocking)
> interaction-start hello-interaction \
    --namespace default \
    --input-message "Hello! How are you today?"

Process started: c3d4e5f6-a7b8-9012-cdef-123456789012

# Check the status later
> interaction-ps --namespace default

ID                                   | Interaction        | Status   | Duration
-------------------------------------|--------------------|---------|---------
c3d4e5f6-a7b8-9012-cdef-123456789012 | hello-interaction  | Finished | 2.3s

# Attach to see the full output
> interaction-attach c3d4e5f6-a7b8-9012-cdef-123456789012

Option B: Using the C# SDK

using Maitento.Sdk;
using Maitento.Entities.Interactions;

await using IMaitentoClient client = MaitentoClient.Create("your-api-key");

// Prepare the input
var inputs = new[]
{
    new NameValuePair("message", "Hello! How are you today?")
};

// Start the interaction by name
InteractionProcess process = await client.InteractionProcesses.StartAsync(
    namespaceName: "default",
    name: "hello-interaction",
    inputs: inputs
);

Console.WriteLine($"Process started: {process.Id}");
Console.WriteLine($"Status: {process.Status}");

// Poll for completion
while (process.Status == InteractionProcessStatus.Running ||
       process.Status == InteractionProcessStatus.New)
{
    await Task.Delay(TimeSpan.FromSeconds(2));
    process = await client.InteractionProcesses.GetInstanceAsync(process.Id);
    Console.WriteLine($"Status: {process.Status}...");
}

// Display the result
if (process.Status == InteractionProcessStatus.Finished)
{
    Console.WriteLine("\n--- Agent Response ---");
    Console.WriteLine(process.Output);
    Console.WriteLine($"\nExecution time: {process.ExecutionTime}");
}
else if (process.Status == InteractionProcessStatus.Error)
{
    Console.WriteLine($"Error: {process.FailureDetails}");
}

Complete runnable example:

// HelloWorld.cs
using Maitento.Sdk;
using Maitento.Entities.Interactions;
using Maitento.Entities.Database;

const string apiKey = "your-api-key";
Guid aiModelId = Guid.Parse("550e8400-e29b-41d4-a716-446655440001");

await using IMaitentoClient client = MaitentoClient.Create(apiKey);

// Step 1: Create the agent
Console.WriteLine("Creating agent...");
Agent agent = await client.Agents.CreateAsync(
    namespaceName: "default",
    name: $"hello-agent-{DateTime.Now.Ticks}",  // Unique name
    aiModelId: aiModelId,
    systemPrompt: "You are a friendly assistant. Respond warmly to greetings.",
    summaryForOtherAgents: "Friendly greeting agent"
);
Console.WriteLine($"Agent created: {agent.Id}");

// Step 2: Create the interaction
Console.WriteLine("Creating interaction...");
var agentBinding = new InteractionAgentBinding(
    agent: new VersionReference(agent.Id, version: 1),
    name: "Greeter",
    externalOperationsMcp: Array.Empty<McpExternalOperationBinding>(),
    externalOperationsOpenApi: Array.Empty<OpenApiExternalOperationBinding>()
);

var promptInputs = new[]
{
    new PromptInput("message", "The message", InteractionInputType.String, true)
};

OneShotInteraction interaction = await client.Interactions.CreateOneShotAsync(
    namespaceName: "default",
    name: $"hello-interaction-{DateTime.Now.Ticks}",  // Unique name
    prompt: "{{message}}",
    solutionSchema: null,
    systemPromptMode: InteractionSystemPromptMode.AppendToDefault,
    systemPrompts: Array.Empty<string>(),
    durationWarningToAi: null,
    durationAutoTermination: TimeSpan.FromMinutes(5),
    externalOperationsMcp: Array.Empty<McpExternalOperationBinding>(),
    externalOperationsOpenApi: Array.Empty<OpenApiExternalOperationBinding>(),
    promptInputs: promptInputs,
    connectorBindingInputs: Array.Empty<ConnectorBindingInput>(),
    connectorAuthenticationSecretInputs: Array.Empty<ConnectorAuthenticationSecretInput>(),
    agent: agentBinding
);
Console.WriteLine($"Interaction created: {interaction.Id}");

// Step 3: Run it!
Console.WriteLine("\nRunning interaction...");
var inputs = new[] { new NameValuePair("message", "Hello! How are you today?") };

InteractionProcess process = await client.InteractionProcesses.StartAsync(
    interactionId: interaction.Id,
    inputs: inputs
);

// Wait for completion
while (process.Status == InteractionProcessStatus.Running ||
       process.Status == InteractionProcessStatus.New)
{
    await Task.Delay(2000);
    process = await client.InteractionProcesses.GetInstanceAsync(process.Id);
}

// Show result
Console.WriteLine("\n========== RESPONSE ==========");
if (process.Status == InteractionProcessStatus.Finished)
{
    Console.WriteLine(process.Output);
}
else
{
    Console.WriteLine($"Error: {process.FailureDetails}");
}
Console.WriteLine("===============================");

Option C: Using the HTTP API

Start the interaction:

curl -X PUT "https://api.maitento.com/namespaces/default/interactions/by-name/hello-interaction/start" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key" \
  -d '{
    "inputs": [
      { "name": "message", "value": "Hello! How are you today?" }
    ]
  }'

Response:

{
  "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "status": "Running",
  "dateStarted": "2024-01-15T10:35:00Z",
  "inputs": [
    { "name": "message", "value": "Hello! How are you today?" }
  ]
}

Poll for completion:

curl -X GET "https://api.maitento.com/interactions/processes/by-id/c3d4e5f6-a7b8-9012-cdef-123456789012" \
  -H "Authorization: Bearer your-api-key"

When complete:

{
  "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "status": "Finished",
  "dateStarted": "2024-01-15T10:35:00Z",
  "dateEnded": "2024-01-15T10:35:03Z",
  "executionTime": "00:00:02.847",
  "output": "Hello there! What a wonderful day to connect! I hope you're doing fantastically well...",
  "inputs": [
    { "name": "message", "value": "Hello! How are you today?" }
  ]
}

Understanding the Response

When the interaction completes successfully, the InteractionProcess contains:

What is Next?

Congratulations! You have created your first Maitento agent and interaction. Here are some next steps:

1. Add External Operations: Let your agent call external APIs and services. See External Operations Guide.

2. Try Multi-Agent Interactions: Create collaborative workflows with RoundRobin or Managed interactions. See Agents and Interactions.

3. Explore the Shell: Discover all available commands with help in the Maitento Shell. See Shell Reference.

4. Build with the SDK: Create production applications using the full SDK. See SDK Reference.

Troubleshooting

”Agent not found” error

Ensure you are using the correct namespace. Agents are scoped to namespaces:

# List agents in your namespace
> agent-list --namespace default

“AI Model not found” error

List available AI models and use a valid ID:

# Via Shell
> ai-model-list

# Via API
curl -X GET "https://api.maitento.com/ai-models" \
  -H "Authorization: Bearer your-api-key"

Process stuck in “Running” status

Check the auto-termination timeout. You can also kill a stuck process:

# Via Shell
> interaction-kill c3d4e5f6-a7b8-9012-cdef-123456789012

Authentication errors

Verify your API key is correct and has not expired. API keys can be managed in your account settings.

Summary

In this tutorial, you learned:

1. Agents are AI entities with configured models and system prompts
2. Interactions define how agents process tasks
3. OneShot is the simplest interaction type: one agent, one response
4. You can work with Maitento via Shell, SDK, or HTTP API

Now you are ready to build more sophisticated AI workflows with Maitento!