Magentic

Common errors

Warnings

Install

Install compatibility verified last tested: 2026-05-12

Imports

• prompt
  wrong

  from magentic import prompt
  
  @prompt('Create a superhero named {name}.')
  def create_superhero(name: str) -> Superhero:
      return Superhero(name=name, power='Unknown')  # body is ignored

  correct

  from magentic import prompt
  from pydantic import BaseModel
  
  class Superhero(BaseModel):
      name: str
      power: str
  
  @prompt('Create a superhero named {name}.')
  def create_superhero(name: str) -> Superhero:
      ...  # body is never executed — must be ellipsis
  
  hero = create_superhero('Garden Man')
  print(hero.name, hero.power)

  The function body of a @prompt decorated function is NEVER executed. It must be ... (ellipsis). Any code in the body is dead code and will never run. The LLM generates the return value.

• FunctionCall
  wrong

  result = describe_weather('Boston')
  print(result)  # prints FunctionCall object, not the weather

  correct

  from magentic import prompt, FunctionCall
  
  def get_weather(city: str) -> str:
      return f'Sunny in {city}'
  
  @prompt(
      'What is the weather in {city}?',
      functions=[get_weather]
  )
  def describe_weather(city: str) -> FunctionCall[str]:
      ...
  
  # Returns a FunctionCall object — must be called to execute
  fn_call = describe_weather('Boston')
  result = fn_call()  # actually calls get_weather
  print(result)

  When LLM decides to call a function, @prompt returns a FunctionCall object — not the final result. You must call fn_call() to execute the function. Use @prompt_chain to auto-resolve.

• chatprompt
  wrong

  from magentic import prompt
  
  @prompt('System: You are helpful.\nUser: {question}')
  def answer(question: str) -> str:
      ...

  correct

  from magentic import chatprompt, SystemMessage, UserMessage
  
  @chatprompt(
      SystemMessage('You are a helpful assistant.'),
      UserMessage('{question}'),
  )
  def answer(question: str) -> str:
      ...
  
  print(answer('What is Python?'))

  Use @chatprompt for structured chat messages with SystemMessage/UserMessage. @prompt is for single-string prompts. Mixing system instructions into @prompt string works but loses structure.

Quickstart verified last tested: 2026-04-23

Minimal magentic structured output using @prompt decorator.

# pip install magentic
from magentic import prompt
from pydantic import BaseModel

class Superhero(BaseModel):
    name: str
    power: str
    enemies: list[str]

@prompt('Create a superhero named {name}.')
def create_superhero(name: str) -> Superhero:
    ...  # never executed

hero = create_superhero('Garden Man')
print(hero.name)     # 'Garden Man'
print(hero.power)    # 'Control over plants'
print(hero.enemies)  # ['Pollution Man', ...]