Inputs, Outputs & Variables

Inputs are how you pass data to an agent when starting a run. They make agents reusable and dynamic - the same agent handles different tasks depending on the input. For marketplace agents, inputs define the form that buyers fill in on app.flymy.ai.

Outputs describe what the agent produces. Together with inputs they form the canonical contract of the agent — the only path that survives when you freeze the pipeline.

How Inputs Work

Input Schema (JSON Schema)          Goal Prompt (Handlebars)
         │                                    │
         ▼                                    ▼
┌─────────────────────┐    ┌─────────────────────────────────┐
│ {                   │    │ Research {{ topic }} focusing    │
│   "topic": "string",│───▶│ on {{ depth }} level analysis.  │
│   "depth": "string" │    │ {{#if sources}}Use: {{sources}} │
│ }                   │    │ {{/if}}                         │
└─────────────────────┘    └─────────────────────────────────┘
         │                                    │
         ▼                                    ▼
┌─────────────────────┐    ┌─────────────────────────────────┐
│  Auto-generated     │    │  Resolved goal at runtime:      │
│  form on flymy.ai   │    │  "Research AI in healthcare     │
│  [topic: ________]  │    │   focusing on deep analysis."   │
│  [depth: ________]  │    │                                 │
└─────────────────────┘    └─────────────────────────────────┘

Defining Input Schema

Every agent can have an input schema written in JSON Schema. This schema defines:

• What fields the agent expects
• Which fields are required vs. optional
• Data types and validation rules
• Descriptions that become form labels and tooltips

Python

agent = client.agents.create(
    name="Market Analyst",
    goal="...",
    tools=["web_search"],
    input_schema={
        "type": "object",
        "properties": {
            "company": {
                "type": "string",
                "description": "Company name to analyze"
            },
            "industry": {
                "type": "string",
                "description": "Industry sector",
                "enum": ["tech", "healthcare", "finance", "retail", "energy"]
            },
            "competitors": {
                "type": "array",
                "items": {"type": "string"},
                "description": "List of competitor names to compare against"
            },
            "time_period": {
                "type": "string",
                "description": "Analysis time range",
                "enum": ["last_quarter", "last_year", "last_3_years"],
                "default": "last_year"
            },
            "include_financials": {
                "type": "boolean",
                "description": "Include financial data in the report",
                "default": False
            }
        },
        "required": ["company", "industry"]
    }
)

JavaScript

const agent = await client.agents.create({
    name: "Market Analyst",
    goal: "...",
    tools: ["web_search"],
    inputSchema: {
        type: "object",
        properties: {
            company: {
                type: "string",
                description: "Company name to analyze"
            },
            industry: {
                type: "string",
                description: "Industry sector",
                enum: ["tech", "healthcare", "finance", "retail", "energy"]
            },
            competitors: {
                type: "array",
                items: { type: "string" },
                description: "List of competitor names to compare against"
            },
            time_period: {
                type: "string",
                description: "Analysis time range",
                enum: ["last_quarter", "last_year", "last_3_years"],
                default: "last_year"
            },
            include_financials: {
                type: "boolean",
                description: "Include financial data in the report",
                default: false
            }
        },
        required: ["company", "industry"]
    }
});

Supported Field Types

Type	JSON Schema	Form Control on flymy.ai
Text	"type": "string"	Text input
Long text	"type": "string", "format": "textarea"	Textarea
Number	"type": "number"	Number input
Boolean	"type": "boolean"	Toggle switch
Select	"type": "string", "enum": [...]	Dropdown
Array of strings	"type": "array", "items": {"type": "string"}	Tag input
URL	"type": "string", "format": "uri"	URL input with validation
Email	"type": "string", "format": "email"	Email input
File	"type": "string", "format": "file"	File upload (stored in Drive)

Handlebars Templating

Use Handlebars syntax in your goal prompt to inject input values at runtime. This is what makes agents dynamic.

Basic Variables

agent = client.agents.create(
    name="Content Writer",
    goal="""Write a {{ content_type }} about {{ topic }}.
    Target audience: {{ audience }}.
    Tone: {{ tone }}.
    Word count: approximately {{ word_count }} words.""",
    tools=["web_search"],
    input_schema={
        "type": "object",
        "properties": {
            "topic": {"type": "string", "description": "What to write about"},
            "content_type": {
                "type": "string",
                "enum": ["blog post", "whitepaper", "email newsletter", "social thread"],
                "description": "Type of content"
            },
            "audience": {"type": "string", "description": "Target reader persona"},
            "tone": {
                "type": "string",
                "enum": ["professional", "casual", "technical", "persuasive"],
                "description": "Writing tone"
            },
            "word_count": {"type": "number", "description": "Target word count", "default": 800}
        },
        "required": ["topic", "content_type", "audience"]
    }
)

When a user runs this agent with:

{
    "topic": "AI agents in enterprise",
    "content_type": "blog post",
    "audience": "CTOs and VPs of Engineering",
    "tone": "professional"
}

The agent receives this resolved goal:

Write a blog post about AI agents in enterprise.
Target audience: CTOs and VPs of Engineering.
Tone: professional.
Word count: approximately 800 words.

Conditional Blocks

Use {{#if}} to include instructions only when optional fields are provided:

agent = client.agents.create(
    name="Competitive Analysis",
    goal="""Perform a competitive analysis of {{ company }} in the {{ industry }} sector.

    {{#if competitors}}
    Compare specifically against these competitors:
    {{#each competitors}}
    - {{ this }}
    {{/each}}
    {{else}}
    Identify the top 3-5 competitors automatically.
    {{/if}}

    {{#if include_financials}}
    Include financial metrics: revenue, growth rate, market cap, and funding.
    {{/if}}

    {{#if focus_areas}}
    Pay special attention to these areas:
    {{#each focus_areas}}
    - {{ this }}
    {{/each}}
    {{/if}}

    Time period: {{ time_period }}.""",
    tools=["web_search", "browse_website"],
    input_schema={
        "type": "object",
        "properties": {
            "company": {"type": "string", "description": "Company to analyze"},
            "industry": {"type": "string", "description": "Industry sector"},
            "competitors": {
                "type": "array",
                "items": {"type": "string"},
                "description": "Specific competitors to compare (leave empty to auto-detect)"
            },
            "include_financials": {
                "type": "boolean",
                "description": "Include financial data",
                "default": False
            },
            "focus_areas": {
                "type": "array",
                "items": {"type": "string"},
                "description": "Specific areas to focus on"
            },
            "time_period": {
                "type": "string",
                "enum": ["last_quarter", "last_year", "last_3_years"],
                "default": "last_year"
            }
        },
        "required": ["company", "industry"]
    }
)

Iterating Over Arrays

Use {{#each}} to loop through array inputs:

goal="""Review the following repositories and provide a security assessment:
{{#each repositories}}
- Repository: {{ this.url }}
  {{#if this.branch}}Branch: {{ this.branch }}{{/if}}
{{/each}}

Focus on: dependency vulnerabilities, exposed secrets, insecure configurations."""

Supported Handlebars Helpers

Helper	Usage	Description
{{variable}}	{{ name }}	Insert value
{{#if}}	{{#if website}}...{{/if}}	Conditional block
{{else}}	{{#if x}}...{{else}}...{{/if}}	Else branch
{{#unless}}	{{#unless skip}}...{{/unless}}	Negated conditional
{{#each}}	{{#each items}}{{this}}{{/each}}	Iterate array
{{this}}	Inside {{#each}}	Current item

Plain-text Descriptions

Alongside the JSON Schemas, each agent stores two human-readable strings:

• input_description — a plain-English summary of what the user provides.
• output_description — a plain-English summary of what the agent returns.

These are first-class fields, not just hints for schema generation. They serve two purposes:

1. Authoritative scope for freeze. When you freeze a run, the compiler reads both descriptions and the schemas as the canonical input → output path. Any chat turns that fall outside that path (exploratory questions, abandoned branches, one-off favors) are dropped from the frozen instruction.
2. Surface copy. The descriptions appear above the input form on the marketplace and inside the run UI on app.flymy.ai.

agent = client.agents.create(
    name="Site Auditor",
    goal="Audit {{ website_url }} and return a score.",
    input_schema={
        "type": "object",
        "properties": {"website_url": {"type": "string"}},
        "required": ["website_url"],
    },
    input_description="A website URL to audit for SEO health.",
    output_schema={
        "type": "object",
        "properties": {"score": {"type": "number"}},
        "required": ["score"],
    },
    output_description="A numeric SEO score between 0 and 100.",
)

If you provide hints to client.agents.suggest_schema(...), the same strings are echoed back as input_description / output_description so the frontend can persist them in one round-trip.

The generated JSON Schema body (property names, description fields, enum labels, title) is always written in English, even if your input_description / output_description is in another language. The schema is a machine-facing contract; only the descriptions are localized.

Output Schema

Define what the agent returns. This is especially important for marketplace agents where consumers expect predictable output.

Freeform Output (Default)

Without an output schema, the agent returns unstructured text. Fine for personal use.

Structured Output

Define a JSON Schema for the output to ensure consistent, parseable results:

agent = client.agents.create(
    name="Lead Scorer",
    goal="Score and profile the given sales lead.",
    tools=["web_search", "browse_website"],
    input_schema={
        "type": "object",
        "properties": {
            "name": {"type": "string"},
            "company": {"type": "string"},
            "email": {"type": "string"}
        },
        "required": ["name", "company"]
    },
    output_schema={
        "type": "object",
        "properties": {
            "score": {
                "type": "number",
                "description": "Lead quality score 0-100"
            },
            "profile": {
                "type": "object",
                "properties": {
                    "role": {"type": "string"},
                    "seniority": {"type": "string", "enum": ["junior", "mid", "senior", "executive"]},
                    "company_size": {"type": "string"}
                }
            },
            "signals": {
                "type": "array",
                "items": {
                    "type": "object",
                    "properties": {
                        "signal": {"type": "string"},
                        "sentiment": {"type": "string", "enum": ["positive", "neutral", "negative"]}
                    }
                }
            },
            "recommended_action": {"type": "string"}
        }
    }
)

Inputs on the Marketplace

When you publish an agent with an input schema, FlyMy.AI automatically generates:

1. Input form - each schema property becomes a form field
2. Validation - required fields, type checking, enum dropdowns
3. Documentation - field descriptions become help text
4. API spec - consumers can also call the agent programmatically

How Schema Maps to the Form

{
  "company": {
    "type": "string",
    "description": "Company to analyze"
  }
}

→ Text input labeled "Company to analyze" (required)

{
  "industry": {
    "type": "string",
    "enum": ["tech", "healthcare", "finance"],
    "description": "Industry sector"
  }
}

→ Dropdown with options: tech, healthcare, finance

{
  "competitors": {
    "type": "array",
    "items": {"type": "string"},
    "description": "Competitor names"
  }
}

→ Tag input - user types names and presses Enter to add

{
  "include_financials": {
    "type": "boolean",
    "default": false,
    "description": "Include financial data"
  }
}

→ Toggle switch (off by default)

Best Practices

1. Always add descriptions - they become form labels and API docs
2. Use required carefully - only require what's truly needed; optional fields with good defaults make the agent easier to use
3. Use enum for constrained choices - renders as dropdowns, prevents invalid input
4. Set default values - pre-fill form fields for the best default experience
5. Match schema to templating - every {{variable}} in the goal should have a corresponding schema property
6. Test with minimal input - make sure the agent works well when only required fields are provided
7. Add structured output for marketplace - consumers need predictable output to integrate into their workflows

Next Steps

• Runs - understand how input becomes execution
• Agents - full agent configuration reference