[SILO-788] feat: add docs for Agents in Plane #176
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
Linked to Plane Work Item(s) This comment was auto-generated by Plane |
WalkthroughThis PR introduces comprehensive documentation for Plane Agents, including an overview, building guide, best practices, and signals/content payload reference. The navigation configuration is updated to expose these new agent-related pages under a dedicated "Agents" group. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
📜 Review details
Configuration used: defaults
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (5)
dev-tools/agents/best-practices.mdx(1 hunks)dev-tools/agents/building-an-agent.mdx(1 hunks)dev-tools/agents/overview.mdx(1 hunks)dev-tools/agents/signals-content-payload.mdx(1 hunks)mint.json(1 hunks)
🔇 Additional comments (8)
dev-tools/agents/overview.mdx (1)
1-138: LGTM! Well-structured overview documentation.The overview provides a comprehensive introduction to Plane Agents, covering key concepts like Agent Runs, Activity types, and the lifecycle flow. The Mermaid sequence diagram clearly illustrates the webhook interaction pattern, and the Agent Run states table is thorough.
dev-tools/agents/best-practices.mdx (1)
79-94: Good guidance on thought activity messaging.The examples of good vs. bad thought messages are helpful for developers to understand the expected user experience. The guidance to avoid exposing technical implementation details is particularly valuable.
dev-tools/agents/building-an-agent.mdx (3)
350-425: Comprehensive webhook documentation.The webhook payload structures and handling examples are thorough and will help developers understand the integration flow. Good inclusion of both
agent_run_createandagent_run_user_promptevents with sample payloads.
173-176: No action needed. The packageplane-sdkis published on PyPI and installable viapip install plane-sdk.
101-104: SDK package name is correct and available.The npm package
@makeplane/plane-node-sdkis published with latest version 0.1.4. The installation command in the documentation is accurate and ready for publication.dev-tools/agents/signals-content-payload.mdx (2)
563-579: Helpful visual example of ephemeral vs permanent activities.This visual representation clearly demonstrates how ephemeral activities (thoughts, actions) behave compared to permanent responses. This will help developers understand the user experience impact of different activity types.
1-7: Well-structured reference documentation.The signals and content payload reference is comprehensive, with clear TypeScript interfaces, JSON examples, and SDK usage patterns for both TypeScript and Python. The section organization makes it easy to find specific information.
mint.json (1)
510-519: Navigation structure looks good.The new Agents subgroup is correctly added under "Build and extend Plane" with a logical page ordering: Overview → Building an Agent → Best Practices → Signals & Content Payload. The paths match the new documentation files added in this PR.
| async def handle_webhook(webhook: dict): | ||
| agent_run_id = webhook["agent_run"]["id"] | ||
|
|
||
| # IMMEDIATELY acknowledge receipt | ||
| plane_client.agent_runs.activities.create( | ||
| workspace_slug=workspace_slug, | ||
| agent_run_id=agent_run_id, | ||
| type="thought", | ||
| content={ | ||
| "type": "thought", | ||
| "body": "Received your request. Analyzing...", | ||
| }, | ||
| ) | ||
|
|
||
| # Now proceed with actual processing | ||
| result = await process_request(webhook) | ||
|
|
||
| # ... rest of the logic | ||
| ``` |
There was a problem hiding this comment.
Inconsistent async/await usage in Python example.
The function handle_webhook is declared as async def, but the SDK call plane_client.agent_runs.activities.create(...) on line 60 is called synchronously (without await). Either make the SDK call awaited if the SDK supports async, or remove the async keyword from the function definition for consistency.
async def handle_webhook(webhook: dict):
agent_run_id = webhook["agent_run"]["id"]
# IMMEDIATELY acknowledge receipt
- plane_client.agent_runs.activities.create(
+ await plane_client.agent_runs.activities.create(
workspace_slug=workspace_slug,
agent_run_id=agent_run_id,
type="thought",
content={
"type": "thought",
"body": "Received your request. Analyzing...",
},
)
# Now proceed with actual processing
result = await process_request(webhook)
# ... rest of the logicCommittable suggestion skipped: line range outside the PR's diff.
| ```python | ||
| async def handle_webhook(webhook: dict): | ||
| signal = webhook["agent_run_activity"]["signal"] | ||
| agent_run_id = webhook["agent_run"]["id"] | ||
|
|
||
| # ALWAYS check for stop signal first | ||
| if signal == "stop": | ||
| # Cancel any ongoing work | ||
| cancel_ongoing_tasks(agent_run_id) | ||
|
|
||
| # Acknowledge the stop | ||
| plane_client.agent_runs.activities.create( | ||
| workspace_slug=workspace_slug, | ||
| agent_run_id=agent_run_id, | ||
| type="response", | ||
| content={ | ||
| "type": "response", | ||
| "body": "Understood. I've stopped processing your previous request.", | ||
| }, | ||
| ) | ||
|
|
||
| return # Exit early | ||
|
|
||
| # Continue with normal processing... | ||
| ``` |
There was a problem hiding this comment.
Same async/await inconsistency as previous example.
The Python example at lines 140-163 has the same issue: async def handle_webhook with a synchronous plane_client.agent_runs.activities.create(...) call on line 150. Apply the same fix for consistency.
🤖 Prompt for AI Agents
In dev-tools/agents/best-practices.mdx around lines 139 to 163, the async
handler calls the synchronous plane_client.agent_runs.activities.create(...) on
line 150; change this to an awaited call so the async function properly awaits
the I/O (i.e., use await plane_client.agent_runs.activities.create(...)); if the
client method is not async, wrap the call in asyncio.to_thread(...) and await
that instead; keep the early return and error handling unchanged.
| ### Ephemeral Activities | ||
|
|
||
| Activities with `ephemeral: true` are temporary and don't create comments. They're useful for showing agent progress without cluttering the conversation. | ||
|
|
||
| The following activity types are automatically marked as ephemeral: | ||
| - `thought` | ||
| - `action` | ||
| - `error` | ||
|
|
||
| Ephemeral activities are displayed temporarily in the UI and replaced when the next activity arrives. |
There was a problem hiding this comment.
Inconsistency: error activity type described as both ephemeral and creating a comment.
Lines 343-346 state that error is automatically marked as ephemeral. However, lines 315-324 state that error "Creates a comment and sets run to failed." These are contradictory—ephemeral activities don't create comments.
Please clarify the actual behavior. Based on the context (error needing to inform users), it seems error should create a comment and likely shouldn't be ephemeral.
🤖 Prompt for AI Agents
In dev-tools/agents/building-an-agent.mdx around lines 339 to 348, the docs
contradict earlier lines (315–324) by listing `error` as an ephemeral activity;
update this section to remove `error` from the ephemeral list and instead state
that `error` activities create a comment and set the run to `failed`, and ensure
the earlier description and the ephemeral-activity list are consistent about
which types are ephemeral (keep `thought` and `action` as ephemeral, remove
`error`).
| ### Automatically Ephemeral Types | ||
|
|
||
| The following activity types are automatically marked as ephemeral: | ||
| - `thought` | ||
| - `action` | ||
| - `error` |
There was a problem hiding this comment.
Same inconsistency: error listed as ephemeral but also creates a comment.
Lines 551-554 list error as automatically ephemeral, but lines 454-456 state that error "Creates a comment and sets the Agent Run status to failed." This is the same inconsistency noted in building-an-agent.mdx.
Please resolve this across all documentation files to clarify the actual behavior of error activities.
Description
Type of Change
Screenshots and Media (if applicable)
Test Scenarios
References
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.