Skip to content

Rethinking the ActorTemplate and ActorTemplateVersion relationship, inspired by ActorSnapshotTag - #905

Open
Zoe Zhao (zoez7) wants to merge 1 commit into
agent-substrate:mainfrom
zoez7:rethink-api
Open

Rethinking the ActorTemplate and ActorTemplateVersion relationship, inspired by ActorSnapshotTag#905
Zoe Zhao (zoez7) wants to merge 1 commit into
agent-substrate:mainfrom
zoez7:rethink-api

Conversation

@zoez7

@zoez7 Zoe Zhao (zoez7) commented Aug 13, 2026

Copy link
Copy Markdown
Collaborator

Previously, the ActorTemplate object expressed both a group and a pointer.

  • It's a grouping mechanism of ActorTemplateVersions.
  • It has a pointer to one of the ATVs, the pointer is default_version_on_create.

In this modified API, we separate out the "pointer" into ActorTemplateVersionTag, similar to ActorSnapshotTag.
After this, the ActorTemplate resource itself doesn't have any field anymore, therefore the "ActorTemplate" as a grouping concept only exists as an ID string.

  • ATVTag is more flexible, is not restricted to default_version_on_create only.
  • below is an illustration of the relationships. This PR doesn't have rollout policy, but we can add that in the future.
// +-- Actor Template    -----------------------------------+
// |                                                        |
// |   +------------+            rollout policy             |
// |   | DefaultTag |             /        \                |
// |   +------------+        10% /          \ 90%           |
// |         |                  /            \              |
// |         v                 v              v             |
// |     +-------+         +-------+      +-------+         |
// |     | ATV-1 |         | ATV-2 |      | ATV-3 |         |
// |     +-------+         +-------+      +-------+         |
// +--------------------------------------------------------+

Julian Gutierrez Oschmann (@juli4n) Let me know what you think.

Initial API definition only, haven't run "go generate" yet.

// CreateActor calls that do not pin a version. If unset, CreateActor
// without an explicit version fails with FailedPrecondition.
ObjectRef default_version_on_create = 3;
// Output only. Set at creation to the tagged version's actor_template_id;

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why we need the actor_template_id here if you can extract it from actor_template_version? Is it to save one read?

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is useful to support APIs like ListActorTemplateVersionTags(actor_template_id), so we don't have to first list all ATVs by actor_template_version

ObjectRef default_version_on_create = 3;
// Output only. Set at creation to the tagged version's actor_template_id;
// the tag can only ever point at versions of this actor template.
string actor_template_id = 2;

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Who will generate the id? There's no message ActorTemplate anymore

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The user will decide this. Perhaps calling it application_name would be more appropriate.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's a good point actually, the server would need to keep record of mapping between (name <-> id)

// versions across all templates.
ObjectRef actor_template = 1;
// The actor template whose versions to list. Required.
string actor_template_id = 1;

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This field is where ate.template.name comes from, and it's a metric label today. We are also planning to leverage it in #853. Can we ensure this is globally unique?

@mini-cookie

Copy link
Copy Markdown

Good mr!I want to add support for the E2B protocol. Building on the ActorTemplateVersion design, we should be able to implement the fork and checkpoint endpoints in ate-api-server fairly quickly~

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants