GETTING_STARTED

From zero to a running autonomous agent in under 5 minutes. We'll build a simple research assistant that can use tools and maintain conversation history.

PREREQUISITES#

SYSTEM_REQUIREMENTS

• Node.js 18+ or Bun 1.0+
• npm, yarn, or pnpm
• 4GB RAM minimum
• Internet connection

API_KEYS_NEEDED

• OpenAI API key (recommended)
• Anthropic API key (optional)
• Mistral API key (optional)

QUICK_START_GUIDE#

INSTALL_AKIOS_CLI

The AKIOS CLI provides project scaffolding, local development server, and deployment tools.

bash

# Install globally
npm install -g @akios/cli

# Verify installation
akios --version

ALTERNATIVE_INSTALLATION

You can also use npx @akios/cli for one-off commands without global installation.

CREATE_NEW_PROJECT

Use the CLI to scaffold a new agent project with TypeScript, testing, and best practices pre-configured.

bash

# Create a new project
akios init my-first-agent

# Navigate to the project
cd my-first-agent

# Install dependencies
npm install

CONFIGURE_ENVIRONMENT

Set up your API keys and configuration. The CLI will help you create a secure environment file.

bash

# Set up secrets (interactive)
akios secrets init

# Or manually create .env file
echo "OPENAI_API_KEY=your_key_here" > .env

SECURITY_NOTE

Never commit .env files to git. Use akios secrets for production deployments.

BUILD_YOUR_FIRST_AGENT

The scaffolded project includes a basic agent. Let's examine and run it.

src/agent.ts

import { Agent, Tool } from '@akios/core'
import { z } from 'zod'

// 1. Define a Tool
const weatherTool = new Tool({
  name: 'get_weather',
  description: 'Get current weather for a location',
  schema: z.object({
    city: z.string().describe('The city name')
  }),
  handler: async ({ city }) => {
    // In a real app, you'd call a weather API
    return `The weather in ${city} is sunny and 72°F`
  }
})

// 2. Create Agent with Memory
const agent = new Agent({
  name: 'WeatherAssistant',
  model: 'gpt-4-turbo',
  tools: [weatherTool],
  systemPrompt: `You are a helpful weather assistant.
  Use the get_weather tool when users ask about weather.
  Keep responses conversational and friendly.`,
  // Enable conversation memory
  memory: true
})

// 3. Export for use
export { agent }

TEST_LOCALLY

Start the development server and test your agent in the browser.

bash

# Start development server
npm run dev

# Or use the CLI
akios dev

Open http://localhost:3000 in your browser. You should see a chat interface where you can test your agent.

DEPLOY_TO_PRODUCTION

Once you're happy with your agent, deploy it to the AKIOS Edge Runtime.

bash

# Deploy to AKIOS Cloud
akios deploy

# Or deploy to Vercel
npm run build
vercel deploy

COMMON_ISSUES_AND_TROUBLESHOOTING#

ERROR:_OPENAI_API_KEY_MISSING

Ensure you have a .env file in your root directory and that dotenv/config is imported at the top of your file.

bash

echo "OPENAI_API_KEY=sk-your-key-here" > .env

ERROR:_TOOL_SCHEMA_MISMATCH

If the LLM tries to call a tool with invalid arguments, AKIOS will throw a validation error. Improve your tool description to guide the model.

typescript

// Bad - vague description
description: 'Get data'

// Good - specific with examples
description: 'Get weather data for a city (e.g., "Tokyo", "New York")'

ERROR:_MODEL_NOT_RESPONDING

Check your API key is valid and has sufficient credits. Try a different model or provider.

typescript

// Try different models
model: 'gpt-3.5-turbo' // Fallback option
model: 'claude-3-haiku-20240307' // Alternative provider

PERFORMANCE:_AGENT_IS_SLOW

Enable streaming for better UX and consider caching for frequent queries.

typescript

// Use streaming
const stream = await agent.stream(message)

// Add caching for tools
const cachedTool = new CachedTool(weatherTool, {
  ttl: 300000 // 5 minutes
})

CONFIGURATION_DEEP_DIVE#

AKIOS agents can be configured via constructor options, environment variables, or configuration files.

SUPPORTED_MODELS_&_PROVIDERS

Provider	Models	Key Variable
OpenAI	gpt-4o, gpt-4-turbo, gpt-3.5-turbo	OPENAI_API_KEY
Anthropic	claude-3-opus, claude-3-sonnet, claude-3-haiku	ANTHROPIC_API_KEY
Mistral	mistral-large, mistral-medium, mistral-small	MISTRAL_API_KEY
Google	gemini-pro, gemini-pro-vision	GOOGLE_API_KEY
Azure OpenAI	gpt-4, gpt-3.5-turbo (Azure deployment)	AZURE_OPENAI_API_KEY

ADVANCED_CONFIGURATION

src/config.ts

import { AgentConfig } from '@akios/core'

export const config: AgentConfig = {
  // Model settings
  model: 'gpt-4o',
  temperature: 0.7,
  maxTokens: 1000,

  // Memory settings
  memory: {
    type: 'redis',
    url: process.env.REDIS_URL,
    ttl: 3600000 // 1 hour
  },

  // Guardrails
  guardrails: {
    input: ['pii-detection', 'prompt-injection'],
    output: ['content-filter', 'json-validation']
  },

  // Observability
  logging: {
    level: 'info',
    sentry: process.env.SENTRY_DSN
  }
}

WHATS_NEXT

BUILD_CUSTOM_TOOLS

Connect to databases, APIs, and services

ADD_SAFETY_GUARDRAILS

Prevent hallucinations and policy violations

IMPLEMENT_MEMORY

Give your agent conversation history

BUILD_RAG_AGENTS

Add knowledge bases and document search

DEPLOY_TO_PRODUCTION

Edge runtime, Docker, and cloud options

OPTIMIZE_PERFORMANCE

Optimization techniques and best practices

JOIN_THE_COMMUNITY

Have questions or want to contribute? Join our community of developers building the future of autonomous agents.

JOIN_COMMUNITY VIEW_GLOSSARY