Skip to content

AI-Assisted Development

Patterns for using AI coding agents (Cursor, GitHub Copilot, custom agents) with the neops Worker SDK.

Why AI Works Well with neops

The SDK is designed with properties that make it particularly suitable for AI-assisted development:

  • Typed interfaces — Pydantic parameters and results give AI models clear contracts to work with.
  • Declarative registration — the @register_function_block decorator provides structured metadata that AI can generate consistently.
  • Pattern consistency — every function block follows the same acquire() / run() structure, making it easy for AI to learn the pattern from a single example.
  • JSON schemas — parameter and result schemas are auto-generated, providing machine-readable API descriptions.

Providing Context to AI Agents

When asking an AI agent to write function blocks, provide:

  1. The base classes and their signatures:

    FunctionBlock[ParamsT, ResultDataT]
FunctionBlockParams (Pydantic BaseModel, extra="ignore")
FunctionBlockResultData (Pydantic BaseModel, extra="forbid")

  2. An example function block — point the agent at examples/getting-started/echo/echo.py as a template.

  3. The registration decorator fields:

    Field Required Purpose
    name Yes Unique identifier
    description Yes Human-readable description
    package Yes Package name
    version No Semantic version tuple (major, minor, patch), default (1, 0, 0)
    run_on Yes Entity type: "device", "group", "interface", or "global"
    fb_type Yes Function block type
    param_cls Yes Parameter Pydantic model class
    result_cls Yes Result Pydantic model class
    is_pure No No side effects (default False)
    is_idempotent No Safe to retry (default False)

  4. The knowledge base documents in .agent/knowledge/ — these contain concise architecture summaries suitable for agent context windows.

Patterns for AI-Generated Function Blocks

Scaffold generation

Ask the agent to generate:

  • Parameter and result Pydantic models
  • The function block class with acquire() and run()
  • The registration decorator
  • A matching test file

Network-specific prompts

Effective prompts for network automation:

  • "Write a function block that collects BGP neighbor state from a device using the DeviceInfoCapability proxy and stores the result in device facts."
  • "Write an idempotent function block that pushes an ACL configuration to a device. It should back up the current config first."
  • "Write a pure function block that validates NTP configuration against a policy defined in the parameters."

Test generation

AI agents can generate tests from function block code:

  • "Write a standalone pytest test for this function block using create_workflow_context with mock device data."
  • "Add @fb_test_case decorators for success and failure paths."

Agent Knowledge Base

The .agent/knowledge/ directory contains markdown documents summarizing:

Document Content
worker-sdk-architecture.md SDK structure, key modules, public API
workflow-engine-architecture.md Workflow engine internals, job lifecycle
neops-core-architecture.md CMS data models, GraphQL API
remote-lab-architecture.md Remote lab service, topology provisioning
neops-ecosystem-overview.md High-level system overview

These are optimized for AI context windows — concise, structured, and focused on the information agents need to generate correct code.

Tips

  • Start with parameters. Define the Pydantic models first — they constrain the function block's behavior and give the AI a clear contract.
  • Reference real examples. Point to examples/ for patterns rather than describing them from scratch.
  • Validate with tests. Always generate a test alongside the function block and run it immediately.
  • Use the type system. The SDK's type annotations help AI models generate correct code. Avoid Any types in parameters and results.