OpenProgram · NOOAChinese

Direct calls, Agent classes and automatic DAG context

Maintainer design · Agent and Context implementation

Design scope

Agent defines reusable model configuration. Context defines parent inheritance, named content, dynamic evaluation, and history visibility.

The framework manages execution context automatically. Applications can call agent() or ordinary Agent methods without manual Context construction.

All entries reuse Runtime, AgentSpec, tool policy, execution control, and Session DAG. An Agent configuration does not own a default conversation.

Public usage

Direct call

from openprogram import agent

answer = agent("Analyze this paper",
               model="configured-model")

Use the current execution session; create one independent execution when no outer execution exists.

Reuse an Agent

from openprogram import Agent

bot = Agent(model="configured-model")
first = bot("Investigate this topic")
second = bot(first)

No subclass is required. The instance reuses configuration; execution scope determines history continuity. Independent top-level calls on the same instance do not share history by default.

Define a class

class Researcher(Agent):
    model = "configured-model"

    def research(self, question):
        text = self.prepare(question)
        return self(text)

    def prepare(self, text):
        return text.strip()

result = Researcher().research("A topic")

Write ordinary methods without per-method decorators; research is an entry; prepare is an unrecorded helper. self(...) uses the same Agent execution core.

Lowercase agent() is a convenient call entry; uppercase Agent is a configurable callable class. Both delegate to one internal execution function. No process-global default Bot stores history. Construction resolves configuration only, without a model request or persistent session. The first execution resolves the session and opens the call.

Synchronous entry points serve synchronous code. The asynchronous forms are await bot.arun(...) and await agent_async(...). Calls inside an active event loop use the asynchronous entry.

Context lifecycle

Trigger	Rule
Program or top-level entry	Establish an execution scope and bind its current Context; inherit an ambient session and explicit branch when present.
Function or method entry	Derive a scope with ancestry and visibility rules, without copying full history.
Before each model request	Resolve DAG sources, instance content, dynamic content and call overrides; select, deduplicate and budget the resulting input.
Model return	Update current execution state with the model interaction, available to subsequent construction under visibility rules.
Function return, error or cancellation	Restore the parent scope. Completed model interactions follow expose / render_range; do not merge every child context unconditionally.
Top-level exit	Unbind task-local state and close owned resources. Reusing an Agent alone does not continue history; the host or explicit session selection determines continuity.

Invocation ancestry determines inheritance and visibility; predecessor determines conversation order. Context is a runtime construction object, without a requirement to copy or persist each complete intermediate value. Existing session persistence and Trace export remain separate from Agent context ownership.

Each Agent execution owns its DAG. Chat records user messages, model requests and directly dispatched tools; ordinary helpers create no durable nodes. Calling another Agent creates an independent DAG; the parent stores the invocation result and a child_session_id reference. Permission, cancellation and file-checkpoint ownership remain with the originating execution, independent of graph ownership.

The behavior-test host initializes the standard SessionStore before applying the OS sandbox. The test runner binds its existing SessionNodeWriter through Context; Agent calls reuse it. Candidate tests cannot spawn processes, write the source snapshot, access host secrets, or use the network. Cancellation closes the canonical execution; unresolved external effects remain available for inspection. The exact assistant projection retries through the durable DAG outbox when its node or storage is unavailable. A display projection failure does not reject an applied cancellation. Cancelling a paused continuation error replaces its error display with cancelled, clears error metadata, and preserves recorded content. Resource-release observer failures remain visible to the control caller. Normal Job completion retains its result-bearing projection owner. Cancellation notifications do not publish other terminal Job rows before that owner supplies result and error fields.

Ordinary function capture

def research(question):
    data = prepare(question)
    return analyze(data)

def prepare(question):
    return question.strip()

def analyze(data):
    return agent(data)

The managed Program loader retains Runtime injection and entry adaptation. Internal helpers use lightweight scopes without per-call persistence. Signatures, return values, exceptions and imports retain Python semantics.

Instance, static and class methods follow Agent ownership boundaries. Ordinary internal methods neither append DAG nodes nor automatically become tools.

Agent methods and managed Agent methods share scope handling without duplicate capture. Entry registration and tool exposure remain explicit.

Arbitrary host files, dependency packages, lambdas, dynamically generated code, and unavailable source do not receive automatic source capture. Their agent() calls still work; ordinary Python ancestry is not persisted.

One Context model

Context has a parent, named content, dynamic providers, and history visibility rules. Every model request uses this model.

Part	Behavior
Parent	A child inherits the current execution context. Scope exit restores the parent binding.
Content	Named values provide instructions and business data. A child can override a name without modifying its parent.
Evaluation	Python providers receive the current Context. They run when the framework constructs a model request.
Visibility	Existing Session DAG rules select permitted interactions by branch, call scope, expose, and render_range.

Instance binding is a special case of named content. Agent configuration contributes content when the invocation derives its Context. The Agent instance does not own a default execution session.

parent Context + Agent configuration + call content
    → derive current Context
    → evaluate named content and select visible DAG interactions
    → apply existing budget and compaction
    → Runtime.exec model request

History selection and content replacement are separate operations. Equal text does not identify the same interaction. The framework records selected DAG identities at the actual request.

Context does not provide a second history database or a second provider runtime. Tool authorization remains independent of history visibility.

Explicit event lifetime

Context(store=writer, head_id=None) binds an existing SessionNodeWriter for repeated calls. The Context session continues model interactions using the existing Session DAG.

head_id selects an existing branch tip. With no explicit head, the invocation continues the current session head. The caller owns the supplied store.

This supplies NOOA-style instance event lifetime as an explicit Context binding. Agent configuration still does not implicitly own history.

Configuration and authority

Setting	Ownership and precedence
model / effort / instructions / tools	Explicit call override → instance setting → class default → ambient session default → product default. Distinguish omission from explicit empty values.
expose / render_range	Preserve existing defaults. method_options or explicit function metadata supplies visibility settings.
tool visibility / approval	Separate from DAG visibility; use existing tool registration, authorization and approval. Inner configuration cannot expand outer authority.
AgentSpec / session	Saved Bot configuration reuses AgentSpec; execution scopes reference Session DAG; instances may configure Context content and sources. Constructing a Python object does not create a sidebar Bot or schedule.

Default context construction needs model interactions and necessary call relationships, not complete ordinary-function arguments, outputs or locals. Explicit model content still uses bounded serialization. Represent self by identity or type, not a whole object or client. Qualify method names by module and class to avoid collisions. Ordinary Python effects remain governed by host execution and sandbox rules; call recording is not per-operation approval of arbitrary Python.

Concurrency and failure

Bind current Context, call identity and effective configuration per task, restoring them on exit. Inheritance does not copy full history or share mutable branch configuration. Permit nested reentry; shared Agent configuration does not imply shared execution context. Explicit mutable instance content and shared sessions require defined synchronization and snapshot rules.

Errors, timeouts and cancellation restore the parent scope and preserve completed model-interaction state. Standalone calls reuse existing permission request context and noninteractive approval rules. Recovery uses existing safe points and explicit steps, without restoring arbitrary Python stacks.

Code boundaries

The implementation uses openprogram/context/model.py for Context, agentic_programming/agent_class.py for Agent, and agentic_programming/call_scope.py for shared scopes.

Runtime history selection remains in agentic_programming/runtime/history.py. Managed source loading remains in programs/_source_loader.py and _registry.py.

Code review and affected checks remain necessary before the implementation status can claim completion.

Relationship to NOOA

Area	Choice
Classes and methods	Adopt class declarations, ordinary calls and framework-managed method handling; basic binding already exists.
Context modeling	Adopt class-based instance content, dynamic resolution and scoped overrides; add existing DAG sources and composition. Effective context belongs to execution scope by default.
History filtering	NOOA filters current-call events by call_id and supports nested policy inheritance. Retain DAG branch/frame rules; do not claim NOOA lacks call-aware context.
Trace and model context	NOOA separates events and traces. Retain one DAG with distinct display and model-input views.
Generation strategies	Predict, CodeAct, typed returns and persistent cells remain separate later work using the existing llm/agent core.
Not adopted	No per-function manual contexts, process-global shared history, whole-interpreter tracing or second provider/event database.

Public documentation and examples credit NVIDIA-labs OO Agents and cite its repository and paper. An independent implementation does not claim upstream API compatibility or reproduced benchmark results. Retain applicable licenses and attribution if source is reused.

Unified model and implementation contract

Context has a parent scope, named content, dynamic providers, and history visibility rules. Every request uses the same construction process. DAG supplies visible interactions and call relationships. Instance binding is a special case. It attaches named content to an instance and includes that content at invocation.

The public entries are Agent, Context, agent, and agent_async. Agent.__call__ is synchronous. Agent.arun is asynchronous. Ordinary Agent methods, including single-underscore helpers, create scopes automatically. A source loader handles ordinary functions in registered Programs. Application code requires no per-function decorator or manual Trace startup.

Context.current() returns the current binding. Context.derive() creates a child. Context supports named content, dynamic providers, and optional history filters. bind() publishes the selected task context and explicit writer. It rejects a conflicting ambient writer and restores bindings on exit. Dynamic providers receive the current Context and run during request construction. Providers are Python callables. The framework does not evaluate expression strings. Explicit instance content persists on that instance. Model interactions belong to the execution session.

CallScope separates recorded operations from lightweight function execution. Another Agent uses its own session writer; same-Agent internal helpers create no structural nodes.

Requests use Runtime.exec and existing providers, tool authorization, budgets, and compaction. Without an outer execution, the entry owns an execution environment and releases it on exit. Shared model configuration or Agent identity does not imply shared history. Concurrent tasks derive separate contexts and retain explicit call identity.

The implementation contains Context, Runtime construction, shared call scopes, Agent entries, registered source capture, product documentation, and shipped migrations. NOOA Predict, CodeAct, and unchanged upstream API execution are separate from context-model equivalence.

Prioritize implementation as requested. Limit verification to public entry behavior, branch isolation, method behavior, and authorization. Run checks in the background while independent coding continues. Inspect results before completion. Use ASD-STE100 sentence structure and consistent terms for English interface text and errors.

Implementation boundaries

The implementation reuses Session DAG, Runtime, AgentSpec, permission checks, budgets, and compaction. Shared call scopes handle both explicit method metadata and new automatic scopes.

Automatic source capture applies only to sources selected by the managed Program loader. Ordinary host files and dependency packages do not receive automatic function capture.

Entry registration and tool exposure remain explicit. A recorded private helper does not become a model tool. Generator creation does not produce a completed function record.

The public API and shipped migration must match the implemented loader and execution boundaries. Independent code review and affected checks determine the implementation status below.

Acceptance criteria

Scenario	Observable result
Non-model parent	Correct research → prepare / analyze → agent scopes, with attributable model inputs, outputs and failures; full ordinary-function data is not required.
Context inheritance and evaluation	Verify parent inheritance, instance blocks, dynamic evaluation, and visibility through public entries; refresh dynamic values per request, enforce override ordering and deduplicate sources without dropping distinct repeated interactions.
Context equivalence	Equivalent history for old/new entries with the same DAG, branch and policy; record provenance at actual requests.
Session lifetime	No constructor effects; same-instance calls in unrelated tasks remain isolated, different Agents in one task share permitted context, and existing sessions require explicit continuation.
Automatic budget and compaction	Long history triggers existing compaction with provenance; summary usage is metered; failures do not silently discard history.
Concurrency and resources	Sibling branch isolation, explicit concurrency policy for shared mutable instance state, nested reentry, parent restoration and owner-only resource cleanup.
Loading and identity	Capture authorized sources only; recursion/import aliases retain records; same-name methods do not collide; explicit method metadata do not duplicate nodes.
Policy and display	Recording does not expose a tool; deny before effects; standalone entries enforce policy; the default App displays function/model/tool calls and terminal state.

Verification uses the smallest affected checks needed for public entries, branch isolation, preserved behavior, and authorization. Completed results provide evidence. The default installed App uses profile default, port 18100, ~/.openprogram, and /Applications/OpenProgram.app.

Resumable function execution uses one durable function node ID across the initial call and continuation. Provider tool-call identity stays in node metadata. A continuation reuses that node and retains its original provider identity.

Removal of the decorator API

Agent and Context own the complete function execution contract. The removed public decorator has no compatibility adapter. Agent method_options preserves input metadata, Runtime injection, registration and schemas, availability, permissions, visibility, retry behavior, execution controls, and explicit-step recovery.

Managed sources declare PROGRAM_ENTRIES and __agent_options__. Internal modules import call_state.py. Methods carry the _is_agent_method marker. Existing execution node schemas and stored session history remain available.

First-party workflows, generated programs, scanners, dispatchers, and documentation use ordinary Agent classes. No replacement public decorator is introduced.

GUI, research, and wiki harness source migrations retain their agentics package paths. Build-time source patches in scripts/release/program-patches produce the staged packages. stage-program-source.py applies the source changes, and product-runtime.json verifies their checksums. This is a source build step, not a runtime compatibility adapter.

Six locally published workflows also receive isolated source migration and local integration. These local and packaged changes do not establish an upstream remote release.

The decorator removal and source migrations are implemented. Independent specification and quality reviews pass. Focused checks cover source loading, schemas, Runtime injection, permissions, cancellation, recovery, and distinct method identities. Deployment of local sources and the installed App is verified separately.

Graph ownership code has independent specification and quality review coverage. Installed behavior is verified separately.

Implementation status

Agent and Context public entries and source migrations are present. Focused specification and quality reviews cover the core migration. Full preservation of existing framework behavior requires independent specification and quality reviews and the complete verification gate. The task evidence records those results separately from core migration checks. Acceptance includes automatic call scopes, conversation projections, Goal lifecycle, cancellation, recovery, and shipped Programs. Recording must retain DAG relationships without changing conversation content, session ownership, or execution authority.

Item	Status
Session DAG, Runtime, AgentSpec, permissions, and compaction	Existing infrastructure reused by this design.
Public Agent and Context entries, shared scopes, and managed sources	Implemented. Affected public-entry checks and both independent reviews pass.
Default installed App acceptance	Installation is verified separately after committing the source. Use scripts/refresh-local-app.sh and the default installed App. Source checks alone do not establish installed App behavior.
NOOA Predict, persistent cells, and CodeAct compatibility	Outside this implementation. No upstream API compatibility or benchmark parity is claimed.