Skip to content

[Doc] Improve Agent core concepts, Actions, Events, and execution guides #1229

Closed

Description

@wenjin272

Parent: #1225

Problem and scope

Core Agent guidance needs a consistent Events/Actions/Resources model, practical authoring examples, and a clearer separation between common behavior and detailed reference material.

Scope

  • Define Resource as a reusable, named runtime component, explain registration and references, and link Chat Models, Tools, Prompts, Vector Stores, and Skills. Do not classify Memory as a ResourceType. Make this explanation the shared source for Overview, Quickstart, and YAML.
  • Describe Actions as listening/reacting to matching Events, not exclusive consumption; show symmetric minimal Java/Python programmatic registration.
  • Add multiple-trigger-condition examples and explain OR semantics and one execution when multiple conditions match the same Event.
  • Keep common trigger guidance in the tutorial and move the complete condition reference to an appendix. Replace event-time evaluation failure with runtime/per-event condition evaluation, including the corresponding configuration description.
  • Keep missing attributes/null/has guards separate from failure strategy configuration. Remove unnecessary coercion, flattening, compiler, and initialization details; state dynamic root-access restrictions concisely.
  • Present Async before Durable and explain start/await/gather, recovery/reconciliation, and context constraints in user terms. Explain supported cross-language round trips with positive and negative examples, verified against current behavior.
  • Present immutable Event identity and reconstruct_from/reconstructFrom as current APIs. Put Java JSON constructor annotations and reconstruction into the normal Custom Event example. Move historical beta migration details out of the evergreen guide.

Coordination and acceptance

Use #1226's layout and #1227's language contract. Own the shared Resource explanation; coordinate its use in #1228 and #1231, and synchronize the introductory Overview. Coordinate configuration wording with #1234.

Related API work: #1191 (ordinary async), #1192 (Event emission invariants). Finalize affected examples against the API actually delivered in 0.4; the remaining edits can proceed independently.

Examples and stated runtime/recovery contracts must match current Java/Python behavior. The umbrella's final review must verify that Quickstart, YAML, Overview, and ReAct consistently apply these concepts.

Review coverage

DOC-002, DOC-018, DOC-019, DOC-020, DOC-021, DOC-022, DOC-023, DOC-024, DOC-025, DOC-026, DOC-027, DOC-028, DOC-029, DOC-030, DOC-031. These are traceability identifiers; the full actionable scope is described above.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

fixVersion/0.4.0priority/majorDefault priority of the PR or issue.tech debt[Issue Type] User-unaware issues, such as code refactor and infrastructure maintenance.

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions