ag2: Instructions file for Codex

AG2 Development Guidelines

AI-assisted contribution policy

Before opening a PR, read and follow .github/AI_POLICY.md.

• Do not open PRs with unverified AI-generated code or text.
• Ensure the PR description explains the real problem or use case and accurately reflects the diff.
• Include validation and testing information in the PR body.
• Be prepared to explain and revise the contribution in response to reviewer questions.
• Write the PR description using .github/PULL_REQUEST_TEMPLATE.md. Keep its section headings (## Why are these changes needed?, ## Related issue number, ## Checks, ## AI assistance), fill each one in, and only check a checklist box once it is actually true.

Architecture Decision Records (ADR)

Cross-cutting and hard-to-reverse design decisions are recorded in docs/adr/, sequentially numbered (0001-*.md, 0002-*.md, …) with status / date frontmatter and a short Context / Decision / Consequences body.

• Consult them before changing established public API or architecture. They explain why something is the way it is — e.g. 0003-eval-run-api-takes-agent-instances.md records that the eval run_* API takes prebuilt Agent instances (not factories) and explicitly-built Suites. If a change contradicts an ADR, supersede it rather than silently reverting the code.
• Add one when a decision qualifies: it is hard to reverse, surprising without context (a reader would assume the opposite), and the result of a real trade-off. Scan docs/adr/ for the highest number and increment. Keep it short — recording that a decision was made and why is the value.

Code Style Guidelines

• Do not use from __future__ import annotations.
• With @contextmanager / @asynccontextmanager, annotate the return type as Generator[T] / AsyncGenerator[T], never Iterator[T] / AsyncIterator[T]. The decorator needs a real generator — it calls throw() / athrow() on it — so the iterator form is an under-specification that typeshed marks deprecated. Import them from collections.abc (not typing) and omit the default send type: AsyncGenerator[None], not AsyncGenerator[None, None].
• Do not use global variables or top-level side-effect function calls unless the user explicitly allows it.
• For filesystem paths, use pathlib.Path internally. Public signatures should accept str | os.PathLike[str].
• Top-level imports from ag2.* are for common APIs that are broadly reusable across scenarios and core agent flows. Good: ag2.[Input] — common structures usable in await agent.ask(Input()) and as tool results. Bad: ag2.middleware.BaseMiddleware — this is advanced/specialized and should be imported only when implementing custom middleware.
• Do not use function-level imports unless the user explicitly allows it.

  # === BAD - import inside function ===
  def execute_tool():
      from .tool import Tool
  
      ...
  
  
  # === GOOD - top-level import ===
  from .tool import Tool
  
  
  def execute_tool(): ...
  

• Do not create nested functions inside runtime execution paths.

  # === BAD - function will be created each call ===
  def execute_tool():
      def _inner_function():
          pass
  
      _inner_function()
  
  
  # === GOOD - function created once, executed each call ===
  def execute_tool():
      _inner_function()
  
  
  def _inner_function():
      pass
  
  
  # === GOOD - decorator executed import time, so we can use closure functions here ===
  def decorator(func):
      def wrapper():
          return func()
  
      return wrapper
  

• Do not perform side effects in initialization methods. Apply side effects only at runtime.

  # === BAD - create directory in initial method ===
  class KnowledgeStore:
      def __init__(self, path: str | os.PathLike[str]) -> None:
          self.path = Path(path)
          # side effect - directory creation
          self.path.parent.mkdir(parents=True, exist_ok=True)
  
      def run(self) -> None: ...
  
  
  # === GOOD - create directory in runtime method ===
  class KnowledgeStore:
      def __init__(self, path: str | os.PathLike[str]) -> None:
          self.path = Path(path)
  
      def run(self) -> None:
          self.path.parent.mkdir(parents=True, exist_ok=True)
          ...