structured-data

Structured Data

Use this skill when an AI feature should return validated Elixir data instead of freeform text.

Goal

• Keep provider config in one place.
• Keep agent modules easy to find under MyApp.Agents.*.
• Return typed, validated structs through InstructorLite.
• Keep tests isolated with Mimic.

Install

def deps do
  [
    {:instructor_lite, "~> 1.2.0"}
  ]
end

Root Agents Module

Create one shared module for API keys and model names:

defmodule MyApp.Agents do
  @moduledoc """
  Central configuration for AI agents.
  Import this module in agent implementations to access API keys and models.
  """

  def anthropic_key, do: Application.get_env(:my_app, :anthropic)[:api_key]
  def openai_key, do: Application.get_env(:my_app, :openai)[:api_key]
  def gemini_key, do: Application.get_env(:my_app, :gemini)[:api_key]

  def model(:haiku), do: "claude-haiku-4-5"
  def model(:sonnet), do: "claude-sonnet-4-5"
  def model(:opus), do: "claude-opus-4-5"

  def model(:gpt_5_nano), do: "gpt-5-nano"
  def model(:gpt_5_mini), do: "gpt-5-mini"
  def model(:gpt_5), do: "gpt-5.2"
  def model(:gpt_4_1_mini), do: "gpt-4.1-mini"

  def model(:gemini_flash), do: "gemini-3-flash-preview"
  def model(:gemini_pro), do: "gemini-3-pro-preview"
end

Credential Placement

Do not put provider credentials in shared config/config.exs. Keep local credentials in config/dev.exs:

config :my_app, :anthropic, api_key: System.get_env("ANTHROPIC_API_KEY")
config :my_app, :openai, api_key: System.get_env("OPENAI_API_KEY")
config :my_app, :gemini, api_key: System.get_env("GEMINI_API_KEY")

Module Naming and Location

• Put agents in lib/my_app/agents/.
• Use MyApp.Agents.TopicSomeAction style names.
• Prefer names that describe one business task, such as MyApp.Agents.PostsWritePost.

Example:

lib/my_app/agents/posts_write_post.ex

defmodule MyApp.Agents.PostsWritePost do
end

Agent Pattern

Use one task-specific module with a nested Response schema: