Managing Agents with .smyth Files

The SmythOS SDK introduces .smyth files to bridge the gap between visual agent design and code implementation. While you can define agents entirely in code, .smyth files—which are JSON exports from the SmythOS visual builder—offer a powerful way to represent an agent's structure, including its name, behavior, and skills.

This approach offers several advantages:

• Visual Workflow: It allows complex agent workflows to be visualized, making them easier to understand and manage, which is especially useful for critical processes.
• Collaboration: It facilitates collaboration between developers and non-developers. Product managers or designers can use the visual builder to create or modify agent logic, which developers can then import and extend in code.
• Separation of Concerns: It promotes a clean separation where the agent's high-level structure is defined in the .smyth file, and the application code handles the runtime logic and interaction.

The examples/02-agent-smyth-file directory contains a working example of this concept.

The .smyth File Format

A .smyth file is a JSON file that describes the agent's configuration. The format is an export from the SmythOS builder, but you can create them by hand. Here's a simplified example of what my-crypto-agent.smyth might look like, containing two connected components for fetching a cryptocurrency price:

// my-crypto-agent.smyth
{
    "name": "Crypto Info Agent",
    "behavior": "You are a cryptocurrency information assistant that uses the CoinGecko API.",
    "defaultModel": "gpt-4",
    "components": [
        {
            "id": "CP001",
            "name": "APIEndpoint",
            "description": "Exposes an endpoint to get a crypto price.",
            "data": { "endpoint": "get_price", "method": "GET" },
            "inputs": [{ "name": "coin_id", "type": "String", "index": 0 }],
            "outputs": [
                { "name": "headers", "index": 0 },
                { "name": "body", "index": 1 },
                { "name": "query", "index": 2 },
                { "name": "query.coin_id", "index": 3 }
            ]
        },
        {
            "id": "CP002",
            "name": "APICall",
            "title": "CoinGecko Price",
            "description": "Calls the CoinGecko API to get the price.",
            "data": {
                "method": "GET",
                "url": "https://api.coingecko.com/api/v3/simple/price?ids={{coin_id}}&vs_currencies=usd"
            },
            "inputs": [{ "name": "coin_id", "type": "String", "index": 0 }]
        }
    ],
    "connections": [
        {
            "sourceId": "CP001",
            "sourceIndex": "query.coin_id",
            "targetId": "CP002",
            "targetIndex": "coin_id"
        }
    ]
}
Copy

Importing an Agent

You can easily load an agent from a .smyth file using the static Agent.import() method. This method is asynchronous and returns a fully hydrated Agent instance, ready to be used.

import { Agent } from '@smythos/sdk';
import path from 'path';

async function main() {
    // Construct the full path to your .smyth file
    const agentPath = path.resolve(__dirname, 'my-crypto-agent.smyth');

    console.log(`Importing agent from: ${agentPath}`);

    // Import the agent definition from the file
    const agent = await Agent.import(agentPath);

    // Now you can interact with the agent as usual
    const response = await agent.prompt('What is the price of bitcoin?');
    console.log(response); // Outputs the price of Bitcoin.
}

main();
Copy

Overriding Configuration

A key feature of Agent.import() is the ability to override any property of the .smyth file at load time. This is extremely useful for adapting a single agent definition to different environments or for using more powerful models.

For instance, you can override the defaultModel to use a different LLM without touching the original .smyth file.

import { Agent, Model } from '@smythos/sdk';
import path from 'path';

async function main() {
    const agentPath = path.resolve(__dirname, 'my-crypto-agent.smyth');

    // Import the agent, but override the model to use gpt-4o
    const agent = await Agent.import(agentPath, {
        // The second argument to import() is an override object
        defaultModel: 'gpt-4o',
    });

    console.log(`Agent model is now: ${agent.data.defaultModel}`);

    const response = await agent.prompt('What is the price of ethereum?');
    console.log(response); // Outputs the price of Ethereum.
}

main();
Copy

Using .smyth files allows for a modular and maintainable architecture, making it easy to manage and version your agent designs separately from your application logic.

Next Steps

Now that you can manage agents as files, let's explore how to orchestrate multiple agents and components together in Workflows.