Agents Quickstart

Build and run your first autonomous agent in under 5 minutes.

Two ways to run an agent

Execute it (this guide) for one-off or interactive work, or freeze it (a.k.a. compile) for anything you'll run repeatedly - on a schedule, for each item, or at scale. Freezing replays a fixed plan, so repeated runs cost fewer tokens, run faster, and stay deterministic. See Runs & Freeze.

Prerequisites

FlyMy.AI account with API key -- get one at app.flymy.ai/profile
Python 3.9+ or Node.js 18+

Install the SDK

Python
JavaScript

pip install flymyai

npm install flymyai-js-client

Scenario A: Agent for Yourself

Create an agent, run it, get results -- all from your code.

1. Create Tools and an Agent

Python
JavaScript

from flymyai import AgentClient

client = AgentClient(api_key="fly-***")

# Register tools first - each returns a Tool object with an integer .id
web_search = client.tools.create(mcp_tool="tavily")
browser = client.tools.create(mcp_tool="browser")

agent = client.agents.create(
    name="Web Researcher",
    goal="Search the web for the latest breakthroughs in quantum computing and return a concise summary with sources.",
    tools=[web_search.id, browser.id]
)

print(f"Agent created: {agent.id}")

import { AgentClient } from "flymyai-js-client";

const client = new AgentClient({ apiKey: "fly-***" });

// Register tools first - each returns a Tool object with an integer .id
const webSearch = await client.tools.create({ mcpTool: "tavily" });
const browser = await client.tools.create({ mcpTool: "browser" });

const agent = await client.agents.create({
    name: "Web Researcher",
    goal: "Search the web for the latest breakthroughs in quantum computing and return a concise summary with sources.",
    tools: [webSearch.id, browser.id]
});

console.log(`Agent created: ${agent.id}`);

Tools are MCP connectors - and you can call them directly

mcp_tool="tavily" pulls from the 130+ MCP catalog (Slack, Notion, GitHub, Sentry, and more). Two things worth knowing:

OAuth connectors (Sentry, Slack, Google, ...) must be connected once in app.flymy.ai before they answer - check tool.is_configured. API-key tools are set up with client.tools.provide_config(...).
You don't need an agent to use a connector: call any action directly with client.tools.call(tool.id, action=..., arguments=...). Already connected something earlier? client.tools.list() returns your tools with their ids.

Full lifecycle - catalog, list, create, configure, call, attach: Tools & MCP.

2. Start a Run

Python
JavaScript

run = client.runs.create(agent_id=agent.id)

print(f"Run started: {run.id} (status: {run.status})")

const run = await client.runs.create({ agentId: agent.id });

console.log(`Run started: ${run.id} (status: ${run.status})`);

3. Stream Events and Get Results

Python
JavaScript

# Watch execution in real-time
for event in client.runs.stream_events(run.id):
    print(f"[{event.type}] {event.message}")

# [declared_functions] Registered 3 tool functions
# [tool_called] tavily_search("quantum computing breakthroughs")
# [tool_called] browser_navigate("https://example.com/quantum-2025")
# [task_cancelled] - only if the run is cancelled

# Get final output
result = client.runs.wait(run.id)
print(result.output)

for await (const event of client.runs.streamEvents(run.id)) {
    console.log(`[${event.type}] ${event.message}`);
}

const result = await client.runs.get(run.id);
console.log(result.output);

Run Statuses

A run progresses through these statuses:

Status	Meaning
`pending`	Run created, waiting to start
`running`	Agent is actively executing
`completed`	Finished successfully
`failed`	Encountered an error
`cancelled`	Cancelled by the user

Reusable Agents with Inputs

To make an agent reusable, declare an input_schema and reference its fields in the goal with {{ variable }} (Handlebars). Pass concrete values as variables when you start the run -- they are rendered into the goal at runtime.

input_schema is required for variables

Placeholders are only rendered when the agent has an input_schema. Without one, the goal is sent verbatim and {{ topic }} reaches the model as literal text. With a schema set, variables are validated against it (and required) on every run.

agent = client.agents.create(
    name="Lead Profiler",
    goal="""Create a sales lead profile for {{ name }} at {{ company }}.
    {{#if job_title}}Their job title is {{ job_title }}.{{/if}}

    Return bullet points covering background, recent initiatives,
    buying triggers, and a recommended outreach angle.""",
    tools=[web_search.id, browser.id],
    input_schema={
        "type": "object",
        "properties": {
            "name": {"type": "string", "description": "Person's full name"},
            "company": {"type": "string", "description": "Company they work at"},
            "job_title": {"type": "string", "description": "Job title (optional)"},
        },
        "required": ["name", "company"],
    },
)

# Pass values for this run
run = client.runs.create(
    agent_id=agent.id,
    variables={"name": "Dana Lee", "company": "Acme Robotics"},
)
result = client.runs.wait(run.id)

Once a run does what you want, freeze it and re-run with fresh variables -- that frozen compilation becomes your reusable API endpoint. Full schema reference: Inputs, Outputs & Variables.

Marketplace publishing - Coming Soon

Scenario B: Agent for Marketplace

Build an agent that others can run on app.flymy.ai. You define the inputs -- FlyMy.AI generates the form. input_schema and output_schema are available today (see Inputs, Outputs & Variables). The marketplace settings shown below -- visibility, pricing, and client.agents.publish() -- are not yet available in the API.

1. Create with Input Schema and Templating

The input schema will define what data users provide. Handlebars templating ({{ variable }}) will inject those values into the agent's goal at runtime.

Python
JavaScript

# Planned API - not yet available
from flymyai import AgentClient

client = AgentClient(api_key="fly-***")

web_search = client.tools.create(mcp_tool="tavily")
browser = client.tools.create(mcp_tool="browser")

agent = client.agents.create(
    name="Sales Lead Profiler",
    goal="""Create a concise sales lead profile for {{ name }} at {{ company }}.
    {{#if job_title}}Their job title is {{ job_title }}.{{/if}}
    {{#if website}}Review the company website ({{ website }}) for recent news.{{/if}}
    {{#if linkedin_url}}Check their LinkedIn profile: {{ linkedin_url }}.{{/if}}

    Return bullet points covering:
    - Background and responsibilities
    - Recent company initiatives
    - Potential buying triggers
    - Recommended outreach angle""",

    tools=[web_search.id, browser.id],

    # JSON Schema defining form fields on app.flymy.ai
    input_schema={
        "type": "object",
        "properties": {
            "name": {
                "type": "string",
                "description": "Person's full name"
            },
            "company": {
                "type": "string",
                "description": "Company they work at"
            },
            "job_title": {
                "type": "string",
                "description": "Job title (optional)"
            },
            "website": {
                "type": "string",
                "description": "Company website URL (optional)"
            },
            "linkedin_url": {
                "type": "string",
                "description": "Public LinkedIn profile URL (optional)"
            }
        },
        "required": ["name", "company"]
    },

    # Structured output for programmatic consumers
    output_schema={
        "type": "object",
        "properties": {
            "background": {"type": "string"},
            "company_initiatives": {"type": "array", "items": {"type": "string"}},
            "buying_triggers": {"type": "array", "items": {"type": "string"}},
            "outreach_angle": {"type": "string"}
        }
    },

    # Planned - marketplace settings
    visibility="public",
    pricing={"per_run": 0.25}
)

// Planned API - not yet available
import { AgentClient } from "flymyai-js-client";

const client = new AgentClient({ apiKey: "fly-***" });

const webSearch = await client.tools.create({ mcpTool: "tavily" });
const browser = await client.tools.create({ mcpTool: "browser" });

const agent = await client.agents.create({
    name: "Sales Lead Profiler",
    goal: `Create a concise sales lead profile for {{ name }} at {{ company }}.
    {{#if job_title}}Their job title is {{ job_title }}.{{/if}}
    {{#if website}}Review the company website ({{ website }}) for recent news.{{/if}}
    {{#if linkedin_url}}Check their LinkedIn profile: {{ linkedin_url }}.{{/if}}

    Return bullet points covering background, initiatives, buying triggers, outreach angle.`,

    tools: [webSearch.id, browser.id],

    inputSchema: {
        type: "object",
        properties: {
            name: { type: "string", description: "Person's full name" },
            company: { type: "string", description: "Company they work at" },
            job_title: { type: "string", description: "Job title (optional)" },
            website: { type: "string", description: "Company website URL (optional)" },
            linkedin_url: { type: "string", description: "Public LinkedIn profile URL (optional)" }
        },
        required: ["name", "company"]
    },

    outputSchema: {
        type: "object",
        properties: {
            background: { type: "string" },
            company_initiatives: { type: "array", items: { type: "string" } },
            buying_triggers: { type: "array", items: { type: "string" } },
            outreach_angle: { type: "string" }
        }
    },

    // Planned - marketplace settings (not yet available)
    visibility: "public",
    pricing: { perRun: 0.25 }
});

2. Test Before Publishing

# Planned API - not yet available
test_run = client.runs.create(agent_id=agent.id)

result = client.runs.wait(test_run.id)
print(result.output)

3. Publish to Marketplace

# Planned API - not yet available
client.agents.publish(agent_id=agent.id)

After publishing, your agent will be live at app.flymy.ai/agents/your-username/sales-lead-profiler:

FlyMy.AI generates an input form from your input_schema
Required fields are marked, optional fields are collapsible
Field descriptions become placeholder text/tooltips
Users click "Run Agent", pay per execution, and see results in the UI

How It Looks for Buyers

When someone visits your agent page on FlyMy.AI:

┌──────────────────────────────────────────────────┐
│  Sales Lead Profiler               by @you       │
│                                                  │
│  ┌────────────────────────────────────────────┐  │
│  │  Name *               [Dana Lee         ]  │  │
│  │  Company *            [Acme Robotics    ]  │  │
│  │  Job title            [VP Engineering   ]  │  │
│  │  Company website      [acmerobotics.com ]  │  │
│  │  LinkedIn URL         [                 ]  │  │
│  └────────────────────────────────────────────┘  │
│                                                  │
│  ┌─────────────────────┐                         │
│  │   > Run Agent $0.25 │                         │
│  └─────────────────────┘                         │
└──────────────────────────────────────────────────┘

What's Next

Agents Overview -- architecture and key capabilities
Tools & MCP -- add tools and external services

Prerequisites​

Install the SDK​

Scenario A: Agent for Yourself​

1. Create Tools and an Agent​

2. Start a Run​

3. Stream Events and Get Results​

Run Statuses​

Reusable Agents with Inputs​

Scenario B: Agent for Marketplace​

1. Create with Input Schema and Templating​

2. Test Before Publishing​

3. Publish to Marketplace​

How It Looks for Buyers​

What's Next​