DocumentationConceptsWhat is an Agent?

What is an Agent?

An Agent is a declarative definition that describes a complete task workflow. The SDK helps you build valid definitions for submission to Platform Core.

Core Concept

An Agent Definition specifies:

  • Task inputs and outputs
  • Processing workflow (DAG of nodes)
  • Required resources (prompts, tools, modules)
  • Version and metadata

The SDK compiles Agent Definitions to YAML. Platform Core executes them.

Structure

Every Agent has these components:

agent = (
    AgentBuilder("agent-name")
    .version("1.0.0")           # Required: Semantic version
    .description("What it does") # Required: One-line description
    .add_workflow(workflow)      # Required: At least one workflow
    .add_prompt(prompt)          # Optional: LLM prompt templates
    .add_tool(tool)              # Optional: External service definitions
    .add_module(module)          # Optional: Reusable components
    .build()
)

Workflows

Define processing logic as directed acyclic graphs (DAGs):

workflow = (
    WorkflowBuilder("process")
    .description("Main processing workflow")
    .add_node(node1)
    .add_node(node2)
    .entry_node("node1")  # Required: Entry point
    .build()
)

Nodes

Individual processing steps:

node = (
    NodeBuilder("extract-data")
    .description("Extract data from input")
    .uses_prompt("extraction-prompt")  # References a prompt
    .outputs("extracted_data")
    .next_nodes("validate-data")
    .build()
)

Node types are determined by resource reference:

  • uses_prompt() - LLM-based processing
  • uses_tool() - External service call
  • uses_module() - Reusable component invocation

SDK Boundary

The SDK is a compiler, not a runtime:

SDK DoesSDK Does NOT Do
Validate definition structureExecute workflows
Check reference integrityMake network requests
Generate YAML outputCalculate execution costs
Perform static analysisHandle authentication
Catch cycles and unreachable nodesManage retries
⚠️

Local compilation success does not guarantee platform execution. Platform Core applies additional validation and governance policies.

Execution Flow

  1. Developer builds Agent Definition using SDK
  2. SDK validates structure and exports YAML
  3. Developer submits YAML to Platform Core
  4. Platform reviews and approves definition
  5. Users invoke Agent through official clients
  6. Platform creates Execution instance
  7. Platform runs workflow and returns results
  8. Platform handles billing and payment

Agent Definition vs Execution

Key distinction:

# This creates a DEFINITION
agent = AgentBuilder("my-agent").build()
 
# This validates and exports the DEFINITION
validate(agent)
yaml = export_yaml(agent)
 
# Platform Core handles EXECUTION (not SDK)
# - User authentication
# - Resource allocation
# - Workflow execution
# - Result delivery
# - Billing

Required Fields

Agent Definition:

  • name - Matches pattern [a-z][a-z0-9-]*
  • version - Semantic versioning (e.g., “1.0.0”)
  • description - Human-readable summary
  • workflows - At least one workflow

Workflow:

  • name - Matches pattern [a-z][a-z0-9-]*
  • description - Workflow purpose
  • nodes - At least one node
  • entry_node - Name of starting node

Node:

  • name - Matches pattern [a-z][a-z0-9-]*
  • description - Node purpose
  • type - One of: prompt, tool, module
  • reference - Name of referenced resource

Example: Email Extractor

from ainalyn import AgentBuilder, WorkflowBuilder, NodeBuilder, PromptBuilder
from ainalyn.api import validate, export_yaml
 
# Define prompt
extraction_prompt = (
    PromptBuilder("extract-emails")
    .description("Extract email addresses from text")
    .template("Extract all email addresses from: {{text}}")
    .variables("text")
    .build()
)
 
# Define workflow
workflow = (
    WorkflowBuilder("extract")
    .description("Email extraction workflow")
    .add_node(
        NodeBuilder("parse-text")
        .description("Parse input text")
        .uses_prompt("extract-emails")
        .outputs("email_list")
        .build()
    )
    .entry_node("parse-text")
    .build()
)
 
# Build agent
agent = (
    AgentBuilder("email-extractor")
    .version("1.0.0")
    .description("Extract email addresses from documents")
    .add_prompt(extraction_prompt)
    .add_workflow(workflow)
    .build()
)
 
# Validate
result = validate(agent)
if result.is_valid:
    yaml_output = export_yaml(agent)
    print(yaml_output)

Validation

The SDK performs:

  1. Schema validation - Structural correctness
  2. Static analysis - Logical consistency

Checks include:

  • Required fields present
  • Names match pattern [a-z][a-z0-9-]*
  • Versions follow semantic versioning
  • All references resolve (no undefined resources)
  • Workflows form valid DAGs (no cycles)
  • All nodes reachable from entry node
  • No duplicate names within scope

Output Format

Agents compile to YAML:

name: email-extractor
version: 1.0.0
description: Extract email addresses from documents
workflows:
- name: extract
  description: Email extraction workflow
  entry_node: parse-text
  nodes:
  - name: parse-text
    description: Parse input text
    type: prompt
    reference: extract-emails
    outputs:
    - email_list
prompts:
- name: extract-emails
  description: Extract email addresses from text
  template: Extract all email addresses from: {{text}}
  variables:
  - text

This YAML is submitted to Platform Core for execution.

Next Steps

Your First AgentAgent Definition